Capítulo 90 de 456

Third Party Libraries

Core Idea

@next/third-parties é uma biblioteca experimental (instalar com @latest/canary) que fornece componentes otimizados para integrações populares de terceiros (foco em Google) — carregando scripts com o melhor timing possível sem trabalho manual de configuração.

Key Concepts

  • GoogleTagManager: instancia um container GTM; por padrão busca o script inline após a hidratação. Pode ser colocado no root layout (todas as rotas) ou numa page específica.
  • sendGTMEvent: envia eventos ao dataLayer — exige que <GoogleTagManager /> esteja incluído em algum ancestral, page ou no mesmo arquivo.
  • gtmScriptUrl: permite apontar para um servidor de tagging próprio (server-side tagging); gtmId pode ser omitido quando esse URL é fornecido.
  • GoogleAnalytics: injeta Google Analytics 4 via gtag.js; recomenda-se usar via GTM se este já estiver presente, em vez de componente separado.
  • sendGAEvent: envia eventos de interação via dataLayer, análogo ao sendGTMEvent.
  • Pageviews automáticos: GA4 rastreia mudanças de browser history state automaticamente — navegação client-side entre rotas Next.js já dispara pageview sem config extra (requer "Enhanced Measurement" habilitado no Admin).
  • GoogleMapsEmbed: embed de Google Maps com lazy-load via atributo loading por padrão.
  • YouTubeEmbed: usa lite-youtube-embed por baixo dos panos para carregamento mais rápido que o iframe padrão do YouTube.

Code Examples

import { GoogleTagManager } from '@next/third-parties/google'

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <GoogleTagManager gtmId="GTM-XYZ" />
      <body>{children}</body>
    </html>
  )
}
  • O que demonstra: carregar GTM globalmente a partir do root layout.
'use client'
import { sendGTMEvent } from '@next/third-parties/google'

export function EventButton() {
  return (
    <button onClick={() => sendGTMEvent({ event: 'buttonClicked', value: 'xyz' })}>
      Send Event
    </button>
  )
}
  • O que demonstra: disparar evento customizado para o dataLayer a partir de um Client Component.
import { YouTubeEmbed } from '@next/third-parties/google'

export default function Page() {
  return <YouTubeEmbed videoid="ogfYd705cRs" height={400} params="controls=0" />
}
  • O que demonstra: embed de vídeo otimizado, com parâmetros de player passados via query string.

Reference Tables

GoogleTagManagerTipoDescrição
gtmIdObrigatório*ID do container GTM (GTM-...)
gtmScriptUrlOpcional*URL do script GTM (default: googletagmanager.com/gtm.js)
dataLayerOpcionalObjeto para instanciar o container
dataLayerNameOpcionalNome da data layer (default dataLayer)
auth / previewOpcionalParâmetros de ambiente (gtm_auth/gtm_preview)

*gtmId pode ser omitido se gtmScriptUrl for fornecido.

GoogleAnalyticsTipoDescrição
gaIdObrigatórioMeasurement ID (G-...)
dataLayerNameOpcionalNome da data layer
debugModeOpcionalHabilita debug mode
nonceOpcionalNonce de CSP

Anti-patterns

  • Usar GoogleAnalytics separado quando GTM já está presente: recomenda-se configurar Analytics via o próprio GTM em vez de duplicar componentes.
  • Enviar pageview manualmente sem desabilitar a medição automática: gera dados duplicados no GA4 — desabilite o measurement padrão antes de enviar pageviews manuais.

Key Takeaways

  1. @next/third-parties ainda é experimental — instale com tag latest ou canary.
  2. GTM/GA carregam após hidratação por padrão, minimizando impacto em performance de carregamento inicial.
  3. sendGTMEvent/sendGAEvent exigem que o componente correspondente já esteja montado em algum ancestral da árvore.
  4. YouTubeEmbed e GoogleMapsEmbed já vêm com lazy-load configurado, reduzindo JS desnecessário acima da dobra.

Connects To

  • Scripts (ch077): next/script, mecanismo de baixo nível sobre o qual essas integrações são construídas.
AnteriorVitestPróximoUpgrading