Analytics

Next.js Speed Insights ermöglicht es Ihnen, die Leistung von Seiten anhand verschiedener Metriken zu analysieren und zu messen.

Sie können mit der Erfassung Ihres Real Experience Score ohne Konfiguration auf Vercel-Deployments beginnen.

Der Rest dieser Dokumentation beschreibt den integrierten Relayer, den Next.js Speed Insights verwendet.

Eigenen Relayer erstellen

Zuerst müssen Sie eine benutzerdefinierte App-Komponente erstellen und eine reportWebVitals-Funktion definieren:

export function reportWebVitals(metric) {
  console.log(metric)
}

function MyApp({ Component, pageProps }) {
  return <Component {...pageProps} />
}

export default MyApp

Diese Funktion wird ausgelöst, wenn die endgültigen Werte für eine der Metriken auf der Seite berechnet wurden. Sie können damit die Ergebnisse in der Konsole protokollieren oder an einen bestimmten Endpunkt senden.

Das metric-Objekt, das an die Funktion übergeben wird, besteht aus mehreren Eigenschaften:

• id: Eindeutiger Identifikator für die Metrik im Kontext des aktuellen Seitenladevorgangs
• name: Name der Metrik
• startTime: Erster aufgezeichneter Zeitstempel des Performance-Eintrags in Millisekunden (falls zutreffend)
• value: Wert oder Dauer in Millisekunden des Performance-Eintrags
• label: Typ der Metrik (web-vital oder custom)

Es werden zwei Arten von Metriken verfolgt:

• Web Vitals
• Benutzerdefinierte Metriken

Web Vitals

Web Vitals sind eine Reihe nützlicher Metriken, die das Nutzererlebnis einer Webseite erfassen sollen. Folgende Web Vitals sind enthalten:

• Time to First Byte (TTFB)
• First Contentful Paint (FCP)
• Largest Contentful Paint (LCP)
• First Input Delay (FID)
• Cumulative Layout Shift (CLS)
• Interaction to Next Paint (INP) (experimentell)

Sie können alle Ergebnisse dieser Metriken mit dem Label web-vital verarbeiten:

export function reportWebVitals(metric) {
  if (metric.label === 'web-vital') {
    console.log(metric) // Das Metrik-Objekt ({ id, name, startTime, value, label }) wird in der Konsole protokolliert
  }
}

Es besteht auch die Möglichkeit, jede Metrik separat zu verarbeiten:

export function reportWebVitals(metric) {
  switch (metric.name) {
    case 'FCP':
      // FCP-Ergebnisse verarbeiten
      break
    case 'LCP':
      // LCP-Ergebnisse verarbeiten
      break
    case 'CLS':
      // CLS-Ergebnisse verarbeiten
      break
    case 'FID':
      // FID-Ergebnisse verarbeiten
      break
    case 'TTFB':
      // TTFB-Ergebnisse verarbeiten
      break
    case 'INP':
      // INP-Ergebnisse verarbeiten (Hinweis: INP ist noch eine experimentelle Metrik)
      break
    default:
      break
  }
}

Für die Messung dieser Metriken wird eine Drittanbieter-Bibliothek namens web-vitals verwendet. Die Browserkompatibilität hängt von der jeweiligen Metrik ab. Informationen zu unterstützten Browsern finden Sie im Abschnitt Browser Support.

Benutzerdefinierte Metriken

Zusätzlich zu den oben aufgeführten Kernmetriken gibt es einige benutzerdefinierte Metriken, die die Zeit für die Hydratation und das Rendering der Seite messen:

• Next.js-hydration: Dauer der Hydratation der Seite (in ms)
• Next.js-route-change-to-render: Dauer bis zum Beginn des Renderings nach einer Routenänderung (in ms)
• Next.js-render: Dauer des Renderings nach einer Routenänderung (in ms)

Sie können alle Ergebnisse dieser Metriken mit dem Label custom verarbeiten:

export function reportWebVitals(metric) {
  if (metric.label === 'custom') {
    console.log(metric) // Das Metrik-Objekt ({ id, name, startTime, value, label }) wird in der Konsole protokolliert
  }
}

Alternativ können Sie jede Metrik separat verarbeiten:

export function reportWebVitals(metric) {
  switch (metric.name) {
    case 'Next.js-hydration':
      // Hydratationsergebnisse verarbeiten
      break
    case 'Next.js-route-change-to-render':
      // Ergebnisse für Routenwechsel zu Rendering verarbeiten
      break
    case 'Next.js-render':
      // Rendering-Ergebnisse verarbeiten
      break
    default:
      break
  }
}

Diese Metriken funktionieren in allen Browsern, die die User Timing API unterstützen.

Ergebnisse an externe Systeme senden

Mit der Relayer-Funktion können Sie Ergebnisse an beliebige Endpunkte senden, um die Leistung Ihrer Seite bei echten Nutzern zu messen und zu verfolgen. Beispiel:

export function reportWebVitals(metric) {
  const body = JSON.stringify(metric)
  const url = 'https://example.com/analytics'

  // `navigator.sendBeacon()` verwenden, falls verfügbar, sonst auf `fetch()` zurückgreifen.
  if (navigator.sendBeacon) {
    navigator.sendBeacon(url, body)
  } else {
    fetch(url, { body, method: 'POST', keepalive: true })
  }
}

Gut zu wissen: Wenn Sie Google Analytics verwenden, können Sie mit dem id-Wert manuell Metrikverteilungen erstellen (um Perzentile etc. zu berechnen).

export function reportWebVitals({ id, name, label, value }) {
  // `window.gtag` verwenden, wenn Sie Google Analytics wie in diesem Beispiel initialisiert haben:
  // https://github.com/vercel/next.js/blob/canary/examples/with-google-analytics/pages/_app.js
  window.gtag('event', name, {
    event_category:
      label === 'web-vital' ? 'Web Vitals' : 'Next.js custom metric',
    value: Math.round(name === 'CLS' ? value * 1000 : value), // Werte müssen Ganzzahlen sein
    event_label: id, // Eindeutige ID für aktuellen Seitenladevorgang
    non_interaction: true, // Beeinflusst die Absprungrate nicht.
  })
}

Lesen Sie mehr über das Senden von Ergebnissen an Google Analytics.

TypeScript

Wenn Sie TypeScript verwenden, können Sie den integrierten Typ NextWebVitalsMetric nutzen:

import type { AppProps, NextWebVitalsMetric } from 'next/app'

function MyApp({ Component, pageProps }: AppProps) {
  return <Component {...pageProps} />
}

export function reportWebVitals(metric: NextWebVitalsMetric) {
  console.log(metric)
}

export default MyApp

function MyApp({ Component, pageProps }) {
  return <Component {...pageProps} />
}

export function reportWebVitals(metric) {
  console.log(metric)
}

export default MyApp