Drittanbieter-Bibliotheken

@next/third-parties ist eine Bibliothek, die eine Sammlung von Komponenten und Hilfsmitteln bereitstellt, welche die Leistung und Entwicklererfahrung beim Laden beliebter Drittanbieter-Bibliotheken in Ihrer Next.js-Anwendung verbessern.

Alle von @next/third-parties bereitgestellten Drittanbieter-Integrationen wurden hinsichtlich Leistung und Benutzerfreundlichkeit optimiert.

Erste Schritte

Um zu beginnen, installieren Sie die @next/third-parties-Bibliothek:

Terminal

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

@next/third-parties ist derzeit eine experimentelle Bibliothek in aktiver Entwicklung. Wir empfehlen, sie mit den Flags latest oder canary zu installieren, während wir daran arbeiten, weitere Drittanbieter-Integrationen hinzuzufügen.

Google Drittanbieter

Alle unterstützten Drittanbieter-Bibliotheken von Google können aus @next/third-parties/google importiert werden.

Google Tag Manager

Die GoogleTagManager-Komponente kann verwendet werden, um einen Google Tag Manager-Container auf Ihrer Seite zu instanziieren. Standardmäßig ruft sie das ursprüngliche Inline-Skript nach der Hydration der Seite ab.

Um Google Tag Manager für alle Routen zu laden, fügen Sie die Komponente direkt in Ihrem Root-Layout ein und übergeben Sie Ihre GTM-Container-ID:

app/layout.tsx

TypeScript

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

Um Google Tag Manager für eine einzelne Route zu laden, fügen Sie die Komponente in Ihrer Seitendatei ein:

app/page.js

import { GoogleTagManager } from '@next/third-parties/google'
 
export default function Page() {
  return <GoogleTagManager gtmId="GTM-XYZ" />
}

Ereignisse senden

Die Funktion sendGTMEvent kann verwendet werden, um Benutzerinteraktionen auf Ihrer Seite zu verfolgen, indem Ereignisse mit dem dataLayer-Objekt gesendet werden. Damit diese Funktion funktioniert, muss die <GoogleTagManager />-Komponente in einem übergeordneten Layout, einer Seite, Komponente oder direkt in derselben Datei enthalten sein.

app/page.js

'use client'
 
import { sendGTMEvent } from '@next/third-parties/google'
 
export function EventButton() {
  return (
    <div>
      <button
        onClick={() => sendGTMEvent({ event: 'buttonClicked', value: 'xyz' })}
      >
        Ereignis senden
      </button>
    </div>
  )
}

Lesen Sie die Tag Manager Entwicklerdokumentation, um mehr über die verschiedenen Variablen und Ereignisse zu erfahren, die in die Funktion übergeben werden können.

Server-seitiges Tagging

Wenn Sie einen serverseitigen Tag-Manager verwenden und gtm.js-Skripte von Ihrem Tagging-Server bereitstellen, können Sie die Option gtmScriptUrl verwenden, um die URL des Skripts anzugeben.

Optionen

Optionen für den Google Tag Manager. Eine vollständige Liste der Optionen finden Sie in den Google Tag Manager-Dokumenten.

Name	Typ	Beschreibung
`gtmId`	Erforderlich	Ihre GTM-Container-ID. Beginnt normalerweise mit `GTM-`.
`gtmScriptUrl`	Optional	GTM-Skript-URL. Standard ist `https://www.googletagmanager.com/gtm.js`.
`dataLayer`	Optional	Data Layer-Objekt zum Instanziieren des Containers.
`dataLayerName`	Optional	Name des Data Layers. Standard ist `dataLayer`.
`auth`	Optional	Wert des Authentifizierungsparameters (`gtm_auth`) für Umgebungs-Snippets.
`preview`	Optional	Wert des Preview-Parameters (`gtm_preview`) für Umgebungs-Snippets.

Google Analytics

Die GoogleAnalytics-Komponente kann verwendet werden, um Google Analytics 4 auf Ihre Seite über den Google-Tag (gtag.js) einzubinden. Standardmäßig ruft sie die ursprünglichen Skripte nach der Hydration der Seite ab.

Empfehlung: Wenn Google Tag Manager bereits in Ihrer Anwendung enthalten ist, können Sie Google Analytics direkt damit konfigurieren, anstatt Google Analytics als separate Komponente einzubinden. Lesen Sie die Dokumentation, um mehr über die Unterschiede zwischen Tag Manager und gtag.js zu erfahren.

Um Google Analytics für alle Routen zu laden, fügen Sie die Komponente direkt in Ihrem Root-Layout ein und übergeben Sie Ihre Messung-ID:

app/layout.tsx

TypeScript

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

Um Google Analytics für eine einzelne Route zu laden, fügen Sie die Komponente in Ihrer Seitendatei ein:

app/page.js

import { GoogleAnalytics } from '@next/third-parties/google'
 
export default function Page() {
  return <GoogleAnalytics gaId="G-XYZ" />
}

Ereignisse senden

Die sendGAEvent-Funktion kann verwendet werden, um Benutzerinteraktionen auf Ihrer Seite zu messen, indem Ereignisse mit dem dataLayer-Objekt gesendet werden. Damit diese Funktion funktioniert, muss die <GoogleAnalytics />-Komponente das dataLayer-Objekt verwenden. Die <GoogleAnalytics />-Komponente muss in einem übergeordneten Layout, einer Seite, Komponente oder direkt in derselben Datei enthalten sein.

app/page.js

'use client'
 
import { sendGAEvent } from '@next/third-parties/google'
 
export function EventButton() {
  return (
    <div>
      <button
        onClick={() => sendGAEvent('event', 'buttonClicked', { value: 'xyz' })}
      >
        Ereignis senden
      </button>
    </div>
  )
}

Weitere Informationen zu Ereignisparametern finden Sie in der Google Analytics Entwicklerdokumentation.

Seitenaufrufe verfolgen

Google Analytics verfolgt Seitenaufrufe automatisch, wenn sich der Browser-Verlaufszustand ändert. Das bedeutet, dass clientseitige Navigationen zwischen Next.js-Routen Seitenaufruf-Daten ohne zusätzliche Konfiguration senden.

Um sicherzustellen, dass clientseitige Navigationen korrekt gemessen werden, überprüfen Sie, dass die "Erweiterte Messung"-Eigenschaft in Ihrem Admin-Panel aktiviert ist und das Kontrollkästchen "Seitenänderungen basierend auf Browser-Verlaufsereignissen" ausgewählt ist.

Hinweis: Wenn Sie sich entscheiden, Seitenaufruf-Ereignisse manuell zu senden, stellen Sie sicher, die standardmäßige Seitenaufruf-Messung zu deaktivieren, um Doppelzählungen zu vermeiden. Weitere Informationen finden Sie in der Google Analytics Entwicklerdokumentation.

Optionen

Optionen, die an die <GoogleAnalytics>-Komponente übergeben werden können.

Name	Typ	Beschreibung
`gaId`	Erforderlich	Ihre Messung-ID. Beginnt normalerweise mit `G-`.
`dataLayerName`	Optional	Name der Datenschicht. Standard ist `dataLayer`.
`nonce`	Optional	Ein Nonce.

Google Maps Embed

Die GoogleMapsEmbed-Komponente kann verwendet werden, um eine Google Maps Einbettung auf Ihrer Seite hinzuzufügen. Standardmäßig verwendet sie das loading-Attribut, um die Einbettung unter dem Seitenumbruch verzögert zu laden.

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

Optionen

Optionen für die Google Maps Einbettung. Eine vollständige Liste der Optionen finden Sie in den Google Maps Embed-Dokumenten.

Name	Typ	Beschreibung
`apiKey`	Erforderlich	Ihr API-Schlüssel.
`mode`	Erforderlich	Kartenmodus
`height`	Optional	Höhe der Einbettung. Standard ist `auto`.
`width`	Optional	Breite der Einbettung. Standard ist `auto`.
`style`	Optional	Übergibt Stile an den Iframe.
`allowfullscreen`	Optional	Eigenschaft zum Vollbildmodus bestimmter Kartenteile.
`loading`	Optional	Standard ist verzögert. Bei Bedarf ändern, wenn die Einbettung über dem Seitenumbruch ist.
`q`	Optional	Definiert den Kartenmarker-Standort. Kann je nach Kartenmodus erforderlich sein.
`center`	Optional	Definiert die Mitte der Kartenansicht.
`zoom`	Optional	Legt die anfängliche Zoomstufe der Karte fest.
`maptype`	Optional	Definiert den Typ der zu ladenden Kartenkacheln.
`language`	Optional	Definiert die Sprache für UI-Elemente und die Anzeige von Beschriftungen auf Kartenkacheln.
`region`	Optional	Definiert die anzuzeigenden Grenzen und Beschriftungen basierend auf geopolitischen Sensibilitäten.

YouTube Embed

Die YouTubeEmbed-Komponente kann verwendet werden, um eine YouTube-Einbettung zu laden und anzuzeigen. Diese Komponente lädt schneller, indem sie lite-youtube-embed intern verwendet.

app/page.js

import { YouTubeEmbed } from '@next/third-parties/google'
 
export default function Page() {
  return <YouTubeEmbed videoid="ogfYd705cRs" height={400} params="controls=0" />
}

Optionen

Name	Typ	Beschreibung
`videoid`	Erforderlich	YouTube-Video-ID.
`width`	Optional	Breite des Videocontainers. Standard ist `auto`
`height`	Optional	Höhe des Videocontainers. Standard ist `auto`
`playlabel`	Optional	Ein visuell ausgeblendetes Label für den Abspielen-Button zur Barrierefreiheit.
`params`	Optional	Die Video-Player-Parameter wie hier definiert. Parameter werden als Abfragezeichenfolge übergeben. Z.B.: `params="controls=0&start=10&end=30"`
`style`	Optional	Wird verwendet, um Stile auf den Videocontainer anzuwenden.