O pacote mais recomendado para integrar Google Tag Manager (GTM) a aplicações React, o , está sem novas versões há mais de 12 meses.
Isso não quebra projetos já em produção, mas quem está começando um projeto novo precisa saber disso antes de instalar a dependência.
Este guia atualiza a implementação de GTM e Google Analytics 4 (GA4) em aplicações React, cobrindo o novo cenário.
Agora, o fork é mantido pela comunidade, a integração nativa do Next.js e o Consent Mode v2.
Implementando o GTM
Existem três caminhos possíveis hoje. A escolha depende do seu stack.
Método 1: Next.js com @next/third-parties
Se o projeto usa Next.js, esse é o caminho mais direto. O pacote é mantido pelo próprio time do Next e cobre GTM nativamente.
npm install @next/third-partiesNo arquivo de layout raiz:
import { GoogleTagManager } from '@next/third-parties/google'
export default function RootLayout({ children }) {
return (
<html lang="pt-BR">
<body>{children}</body>
<GoogleTagManager gtmId="GTM-XXXXXXX" />
</html>
)
}Dessa maneira, sem configuração manual de script, sem gerenciar carregamento assíncrono. O próprio Next cuida disso.
Método 2: React puro, com o fork mantido
Para projetos React sem Next.js (Vite, CRA legado, etc.), o original não recebe mais atualizações. A alternativa é o fork , que mantém a mesma API.
npm install @sooro-io/react-gtm-moduleimport TagManager from '@sooro-io/react-gtm-module'
const tagManagerArgs = {
gtmId: '<ID do GTM, formato GTM-XXXXXXX>'
}
TagManager.initialize(tagManagerArgs)Quem já usa o pacote antigo pode migrar trocando só o nome do pacote no import. A única mudança de API é no argumento : se você usava esse argumento na inicialização, precisa passar a virar .
Método 3: snippet direto no HTML
Para qualquer stack, incluindo aplicações sem bundler ou sem Next.js, o snippet oficial do GTM ainda funciona e é framework-agnóstico.
Cole o primeiro bloco o mais alto possível no :
<!-- Google Tag Manager -->
<script>(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start':
new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0],
j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src=
'https://www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f);
})(window,document,'script','dataLayer','GTM-XXXXXXX');</script>
<!-- End Google Tag Manager -->E o segundo, logo após a abertura do :
<!-- Google Tag Manager (noscript) -->
<noscript><iframe src="https://www.googletagmanager.com/ns.html?id=GTM-XXXXXXX"
height="0" width="0" style="display:none;visibility:hidden"></iframe></noscript>
<!-- End Google Tag Manager (noscript) -->Consent Mode v2
Desde 2024, o Consent Mode v2 é exigido pelo Google para contas que operam no espaço econômico europeu. Ou seja, já virou boa prática padrão em qualquer implementação, independente da região.
Sem ele, tags de anúncios e conversão podem ser bloqueadas ou reportar dados incompletos assim que o usuário interage com um banner de coockies.
A configuração básica define os estados de consentimento antes do carregamento do GTM:
window.dataLayer = window.dataLayer || [];
function gtag(){dataLayer.push(arguments);}
gtag('consent', 'default', {
'ad_storage': 'denied',
'analytics_storage': 'denied',
'ad_user_data': 'denied',
'ad_personalization': 'denied'
});Depois, quando o usuário aceita o banner de cookies, o consentimento é atualizado:
gtag('consent', 'update', {
'ad_storage': 'granted',
'analytics_storage': 'granted'
});Portanto, essa etapa precisa vir antes da inicialização do GTM em qualquer um dos três métodos acima.
Implementar Page Tracking
Aplicações de página única (SPA) não recarregam a URL a cada navegação, então a aplicação precisa avisar o GTM manualmente a cada troca de rota.
Com React Router ou gerenciamento de via :
window.dataLayer.push({
event: 'pageview'
});Sem gerenciamento de rotas, passando URL e título manualmente:
window.dataLayer.push({
event: 'pageview',
page: {
url: location,
title: title
}
});Implementar Event Tracking
Rastrear eventos segue a mesma lógica: um push na dataLayer.
window.dataLayer.push({
event: 'nome_do_evento'
});
Em resumo, o GTM aceita qualquer nome de evento e mapeia variáveis a partir dos dados que a aplicação envia. Ele também preenche lacunas quando algum campo fica em branco.
Tem mais alguma dúvida sobre GTM ou GA4? É só perguntar que a gente publica.
