Orbital

Como implementar o Google Tag Manager em aplicações React em 2026

Eduardo Silva

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.

shell
npm install @next/third-parties

No arquivo de layout raiz:

javascript
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.

shell
npm install @sooro-io/react-gtm-module
javascript
import 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 :

html
<!-- 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 :

html
<!-- 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:

javascript
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:

javascript
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 :

javascript
window.dataLayer.push({
  event: 'pageview'
});

Sem gerenciamento de rotas, passando URL e título manualmente:

javascript
window.dataLayer.push({
  event: 'pageview',
  page: {
    url: location,
    title: title
  }
});

Implementar Event Tracking

Rastrear eventos segue a mesma lógica: um push na dataLayer.

javascript
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.

Precisa de ajuda com GTM? Fale com a gente!
Sair da versão mobile