useReportWebVitals

Der useReportWebVitals-Hook ermöglicht es Ihnen, Core Web Vitals zu melden und kann in Kombination mit Ihrem Analysedienst verwendet werden.

Neue Funktionen, die an useReportWebVitals übergeben werden, werden mit den bis dahin verfügbaren Metriken aufgerufen. Um die Meldung doppelter Daten zu verhindern, stellen Sie sicher, dass die Referenz der Callback-Funktion sich nicht ändert (wie in den folgenden Codebeispielen gezeigt).

pages/_app.js

import { useReportWebVitals } from 'next/web-vitals'

const logWebVitals = (metric) => {
  console.log(metric)
}

function MyApp({ Component, pageProps }) {
  useReportWebVitals(logWebVitals)

  return <Component {...pageProps} />
}

Das metric-Objekt, das als Argument des Hooks übergeben wird, besteht aus mehreren Eigenschaften:

id: Eindeutige Kennung für die Metrik im Kontext des aktuellen Seitenladevorgangs
name: Der Name der Leistungsmetrik. Mögliche Werte umfassen Namen von Web Vitals-Metriken (TTFB, FCP, LCP, FID, CLS), die spezifisch für eine Webanwendung sind.
delta: Die Differenz zwischen dem aktuellen und dem vorherigen Wert der Metrik. Der Wert ist typischerweise in Millisekunden und stellt die Änderung des Metrikwerts über die Zeit dar.
entries: Ein Array von Performance Entries, die mit der Metrik verknüpft sind. Diese Einträge liefern detaillierte Informationen über die Leistungsereignisse, die mit der Metrik zusammenhängen.
navigationType: Gibt den Typ der Navigation an, der die Metrikdatenerfassung ausgelöst hat. Mögliche Werte sind "navigate", "reload", "back_forward" und "prerender".
rating: Eine qualitative Bewertung des Metrikwerts, die eine Einschätzung der Leistung liefert. Mögliche Werte sind "good", "needs-improvement" und "poor". Die Bewertung wird typischerweise durch den Vergleich des Metrikwerts mit vordefinierten Schwellenwerten bestimmt, die akzeptable oder suboptimale Leistung anzeigen.
value: Der tatsächliche Wert oder die Dauer des Performance-Eintrags, typischerweise in Millisekunden. Der Wert liefert ein quantitatives Maß für den Leistungsaspekt, der von der Metrik verfolgt wird. Die Quelle des Werts hängt von der spezifischen gemessenen Metrik ab und kann aus verschiedenen Performance APIs stammen.

Web Vitals

Web Vitals sind eine Reihe nützlicher Metriken, die die Nutzererfahrung einer Webseite erfassen sollen. Die folgenden Web Vitals sind alle enthalten:

Sie können alle Ergebnisse dieser Metriken mithilfe der Eigenschaft name verarbeiten.

pages/_app.js

import { useReportWebVitals } from 'next/web-vitals'

const handleWebVitals = (metric) => {
  switch (metric.name) {
    case 'FCP': {
      // FCP-Ergebnisse verarbeiten
    }
    case 'LCP': {
      // LCP-Ergebnisse verarbeiten
    }
    // ...
  }
}

function MyApp({ Component, pageProps }) {
  useReportWebVitals(handleWebVitals)

  return <Component {...pageProps} />
}

Benutzerdefinierte Metriken

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

Next.js-hydration: Dauer, die die Seite für den Start und den Abschluss der Hydratation benötigt (in ms)
Next.js-route-change-to-render: Dauer, die eine Seite nach einer Routenänderung für den Renderstart benötigt (in ms)
Next.js-render: Dauer, die eine Seite nach einer Routenänderung für den Abschluss des Renderings benötigt (in ms)

Sie können alle Ergebnisse dieser Metriken separat verarbeiten:

pages/_app.js

import { useReportWebVitals } from 'next/web-vitals'

function handleCustomMetrics(metrics) {
  switch (metric.name) {
    case 'Next.js-hydration':
      // Hydratationsergebnisse verarbeiten
      break
    case 'Next.js-route-change-to-render':
      // Route-Change-zu-Render-Ergebnisse verarbeiten
      break
    case 'Next.js-render':
      // Renderergebnisse verarbeiten
      break
    default:
      break
  }
}

function MyApp({ Component, pageProps }) {
  useReportWebVitals(handleCustomMetrics)

  return <Component {...pageProps} />
}

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

Ergebnisse an externe Systeme senden

Sie können Ergebnisse an beliebige Endpunkte senden, um die Leistung echter Nutzer auf Ihrer Website zu messen und zu verfolgen. Zum Beispiel:

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

  // Verwenden Sie `navigator.sendBeacon()`, falls verfügbar, andernfalls `fetch()`.
  if (navigator.sendBeacon) {
    navigator.sendBeacon(url, body)
  } else {
    fetch(url, { body, method: 'POST', keepalive: true })
  }
}

useReportWebVitals(postWebVitals)

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

useReportWebVitals(metric => {
  // Verwenden Sie `window.gtag`, wenn Sie Google Analytics wie in diesem Beispiel initialisiert haben:
  // https://github.com/vercel/next.js/blob/canary/examples/with-google-analytics
  window.gtag('event', metric.name, {
    value: Math.round(metric.name === 'CLS' ? metric.value * 1000 : metric.value), // Werte müssen Ganzzahlen sein
    event_label: metric.id, // ID eindeutig für aktuellen Seitenladevorgang
    non_interaction: true, // vermeidet Auswirkungen auf die Absprungrate.
  });
}

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

useReportWebVitals