Bibliotecas de terceros

@next/third-parties es una biblioteca que proporciona una colección de componentes y utilidades que mejoran el rendimiento y la experiencia del desarrollador al cargar bibliotecas de terceros populares en tu aplicación Next.js.

Todas las integraciones de terceros proporcionadas por @next/third-parties han sido optimizadas para rendimiento y facilidad de uso.

Primeros pasos

Para comenzar, instala la biblioteca @next/third-parties:

Terminal

npm install @next/third-parties@latest next@latest

@next/third-parties es actualmente una biblioteca experimental en desarrollo activo. Recomendamos instalarla con las banderas latest o canary mientras trabajamos en agregar más integraciones de terceros.

Bibliotecas de Google

Todas las bibliotecas de terceros de Google admitidas pueden importarse desde @next/third-parties/google.

Google Tag Manager

El componente GoogleTagManager puede usarse para instanciar un contenedor de Google Tag Manager en tu página. Por defecto, recupera el script inline original después de que ocurra la hidratación en la página.

Para cargar Google Tag Manager en todas las rutas, incluye el componente directamente en tu layout raíz y pasa tu ID de contenedor GTM:

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>
  )
}

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

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <GoogleTagManager gtmId="GTM-XYZ" />
      <body>{children}</body>
    </html>
  )
}

Para cargar Google Tag Manager en una sola ruta, incluye el componente en tu archivo de página:

app/page.js

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

export default function Page() {
  return <GoogleTagManager gtmId="GTM-XYZ" />
}

Envío de eventos

La función sendGTMEvent puede usarse para rastrear interacciones del usuario en tu página enviando eventos usando el objeto dataLayer. Para que esta función funcione, el componente <GoogleTagManager /> debe estar incluido en un layout padre, página o componente, o directamente en el mismo archivo.

app/page.js

'use client'

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

export function EventButton() {
  return (
    <div>
      <button
        onClick={() => sendGTMEvent({ event: 'buttonClicked', value: 'xyz' })}
      >
        Enviar evento
      </button>
    </div>
  )
}

Consulta la documentación para desarrolladores de Tag Manager para aprender sobre las diferentes variables y eventos que pueden pasarse a la función.

Opciones

Opciones para pasar a Google Tag Manager. Para una lista completa de opciones, lee la documentación de Google Tag Manager.

Nombre	Tipo	Descripción
`gtmId`	Requerido	Tu ID de contenedor GTM. Usualmente comienza con `GTM-`.
`dataLayer`	Opcional	Array de la capa de datos para instanciar el contenedor. Por defecto es un array vacío.
`dataLayerName`	Opcional	Nombre de la capa de datos. Por defecto es `dataLayer`.
`auth`	Opcional	Valor del parámetro de autenticación (`gtm_auth`) para snippets de entorno.
`preview`	Opcional	Valor del parámetro de vista previa (`gtm_preview`) para snippets de entorno.

Google Analytics

El componente GoogleAnalytics puede usarse para incluir Google Analytics 4 en tu página mediante la etiqueta de Google (gtag.js). Por defecto, recupera los scripts originales después de que ocurra la hidratación en la página.

Recomendación: Si Google Tag Manager ya está incluido en tu aplicación, puedes configurar Google Analytics directamente usándolo, en lugar de incluir Google Analytics como un componente separado. Consulta la documentación para aprender más sobre las diferencias entre Tag Manager y gtag.js.

Para cargar Google Analytics en todas las rutas, incluye el componente directamente en tu layout raíz y pasa tu ID de medición:

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

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en">
      <body>{children}</body>
      <GoogleAnalytics gaId="G-XYZ" />
    </html>
  )
}

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

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>{children}</body>
      <GoogleAnalytics gaId="G-XYZ" />
    </html>
  )
}

Para cargar Google Analytics en una sola ruta, incluye el componente en tu archivo de página:

app/page.js

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

export default function Page() {
  return <GoogleAnalytics gaId="G-XYZ" />
}

Envío de eventos

La función sendGAEvent puede usarse para medir interacciones del usuario en tu página enviando eventos usando el objeto dataLayer. Para que esta función funcione, el componente <GoogleAnalytics /> debe estar incluido en un layout padre, página o componente, o directamente en el mismo archivo.

app/page.js

'use client'

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

export function EventButton() {
  return (
    <div>
      <button
        onClick={() => sendGAEvent({ event: 'buttonClicked', value: 'xyz' })}
      >
        Enviar evento
      </button>
    </div>
  )
}

Consulta la documentación para desarrolladores de Google Analytics para aprender más sobre los parámetros de eventos.

Seguimiento de vistas de página

Google Analytics rastrea automáticamente las vistas de página cuando cambia el estado del historial del navegador. Esto significa que las navegaciones del lado del cliente entre rutas de Next.js enviarán datos de vistas de página sin ninguna configuración.

Para asegurarte de que las navegaciones del lado del cliente se miden correctamente, verifica que la propiedad "Medición mejorada" esté habilitada en tu panel de administración y que la casilla "Cambios de página basados en eventos del historial del navegador" esté seleccionada.

Nota: Si decides enviar manualmente eventos de vista de página, asegúrate de deshabilitar la medición predeterminada de vistas de página para evitar tener datos duplicados. Consulta la documentación para desarrolladores de Google Analytics para aprender más.

Opciones

Opciones para pasar al componente <GoogleAnalytics>.

Nombre	Tipo	Descripción
`gaId`	Requerido	Tu ID de medición. Usualmente comienza con `G-`.
`dataLayerName`	Opcional	Nombre de la capa de datos. Por defecto es `dataLayer`.

Google Maps Embed

El componente GoogleMapsEmbed puede usarse para agregar un Google Maps Embed a tu página. Por defecto, usa el atributo loading para cargar diferidamente el embed que esté fuera de la pantalla visible.

app/page.js

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

export default function Page() {
  return (
    <GoogleMapsEmbed
      apiKey="XYZ"
      height={200}
      width="100%"
      mode="place"
      q="Brooklyn+Bridge,New+York,NY"
    />
  )
}

Opciones

Opciones para pasar a Google Maps Embed. Para una lista completa de opciones, lee la documentación de Google Map Embed.

Nombre	Tipo	Descripción
`apiKey`	Requerido	Tu clave API.
`mode`	Requerido	Modo de mapa
`height`	Opcional	Altura del embed. Por defecto es `auto`.
`width`	Opcional	Ancho del embed. Por defecto es `auto`.
`style`	Opcional	Aplica estilos al iframe.
`allowfullscreen`	Opcional	Propiedad para permitir que ciertas partes del mapa entren en pantalla completa.
`loading`	Opcional	Por defecto es lazy. Considera cambiarlo si sabes que tu embed estará visible inicialmente.
`q`	Opcional	Define la ubicación del marcador del mapa. Puede ser requerido dependiendo del modo del mapa.
`center`	Opcional	Define el centro de la vista del mapa.
`zoom`	Opcional	Establece el nivel de zoom inicial del mapa.
`maptype`	Opcional	Define el tipo de mosaicos de mapa a cargar.
`language`	Opcional	Define el idioma a usar para elementos de UI y etiquetas en mosaicos de mapa.
`region`	Opcional	Define los bordes y etiquetas apropiados a mostrar, basados en sensibilidades geopolíticas.

YouTube Embed

El componente YouTubeEmbed puede usarse para cargar y mostrar un embed de YouTube. Este componente carga más rápido usando lite-youtube-embed internamente.

app/page.js

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

export default function Page() {
  return <YouTubeEmbed videoid="ogfYd705cRs" height={400} params="controls=0" />
}

Opciones

Nombre	Tipo	Descripción
`videoid`	Requerido	ID del video de YouTube.
`width`	Opcional	Ancho del contenedor del video. Por defecto es `auto`
`height`	Opcional	Altura del contenedor del video. Por defecto es `auto`
`playlabel`	Opcional	Etiqueta oculta visualmente para el botón de reproducción, para accesibilidad.
`params`	Opcional	Parámetros del reproductor de video definidos aquí. Los parámetros se pasan como una cadena de consulta. Ej: `params="controls=0&start=10&end=30"`
`style`	Opcional	Usado para aplicar estilos al contenedor del video.

On this page