Cómo optimizar 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.

Comenzando

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 los flags latest o canary mientras trabajamos en agregar más integraciones de terceros.

Bibliotecas de Google

Todas las bibliotecas de terceros de Google soportadas 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, obtiene el script inline original después de que ocurre 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>
  )
}

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 de usuarios en tu página enviando eventos usando el objeto dataLayer. Para que esta función funcione, el componente <GoogleTagManager /> debe estar incluido ya sea en un layout padre, página, 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.

Etiquetado del Lado del Servidor

Si estás usando un administrador de etiquetas del lado del servidor y sirviendo scripts gtm.js desde tu servidor de etiquetado, puedes usar la opción gtmScriptUrl para especificar la URL del script.

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-`.
`gtmScriptUrl`	Opcional	URL del script GTM. Por defecto es `https://www.googletagmanager.com/gtm.js`.
`dataLayer`	Opcional	Objeto data layer para instanciar el contenedor.
`dataLayerName`	Opcional	Nombre del data layer. 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, obtiene los scripts originales después de que ocurre 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>
  )
}

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 de usuarios en tu página enviando eventos usando el objeto dataLayer. Para que esta función funcione, el componente <GoogleAnalytics /> debe estar incluido ya sea en un layout padre, página, 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 parámetros de eventos.

Rastreo 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 están midiendo correctamente, verifica que la propiedad "Medición Mejorada" esté habilitada en tu panel de Admin 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 del data layer. Por defecto es `dataLayer`.
`nonce`	Opcional	Un nonce.

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 debajo del pliegue.

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	Pasa 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á arriba del pliegue.
`q`	Opcional	Define la ubicación del marcador del mapa. Esto puede ser requerido dependiendo del modo de 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 para mostrar 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, destinada a 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	Se utiliza para aplicar estilos al contenedor del video.

Cómo optimizar bibliotecas de terceros

On this page