Analytics

Next.js Speed Insights vous permet d'analyser et de mesurer les performances des pages à l'aide de différentes métriques.

Vous pouvez commencer à collecter votre Score d'Expérience Réelle sans configuration sur les déploiements Vercel.

Le reste de cette documentation décrit le relais intégré utilisé par Next.js Speed Insights.

Créez votre propre solution

D'abord, vous devrez créer un composant App personnalisé et définir une fonction reportWebVitals :

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

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

export default MyApp

Cette fonction est déclenchée lorsque les valeurs finales pour l'une des métriques ont fini d'être calculées sur la page. Vous pouvez l'utiliser pour enregistrer les résultats dans la console ou les envoyer vers un endpoint spécifique.

L'objet metric retourné par la fonction contient plusieurs propriétés :

• id : Identifiant unique pour la métrique dans le contexte du chargement de page actuel
• name : Nom de la métrique
• startTime : Premier timestamp enregistré de l'entrée de performance en millisecondes (si applicable)
• value : Valeur ou durée en millisecondes de l'entrée de performance
• label : Type de métrique (web-vital ou custom)

Il existe deux types de métriques suivis :

• Web Vitals
• Métriques personnalisées

Web Vitals

Les Web Vitals sont un ensemble de métriques utiles qui visent à capturer l'expérience utilisateur d'une page web. Les Web Vitals suivants sont inclus :

• 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) (expérimental)

Vous pouvez gérer tous les résultats de ces métriques en utilisant le label web-vital :

export function reportWebVitals(metric) {
  if (metric.label === 'web-vital') {
    console.log(metric) // L'objet métrique ({ id, name, startTime, value, label }) est enregistré dans la console
  }
}

Il existe également l'option de gérer chaque métrique séparément :

export function reportWebVitals(metric) {
  switch (metric.name) {
    case 'FCP':
      // traiter les résultats FCP
      break
    case 'LCP':
      // traiter les résultats LCP
      break
    case 'CLS':
      // traiter les résultats CLS
      break
    case 'FID':
      // traiter les résultats FID
      break
    case 'TTFB':
      // traiter les résultats TTFB
      break
    case 'INP':
      // traiter les résultats INP (note : INP est encore une métrique expérimentale)
      break
    default:
      break
  }
}

Une bibliothèque tierce, web-vitals, est utilisée pour mesurer ces métriques. La compatibilité avec les navigateurs dépend de la métrique spécifique, consultez la section Support des navigateurs pour savoir quels navigateurs sont pris en charge.

Métriques personnalisées

En plus des métriques principales listées ci-dessus, il existe des métriques personnalisées supplémentaires qui mesurent le temps nécessaire pour que la page s'hydrate et s'affiche :

• Next.js-hydration : Durée nécessaire pour que la page commence et termine son hydratation (en ms)
• Next.js-route-change-to-render : Durée nécessaire pour qu'une page commence à s'afficher après un changement de route (en ms)
• Next.js-render : Durée nécessaire pour qu'une page termine de s'afficher après un changement de route (en ms)

Vous pouvez gérer tous les résultats de ces métriques en utilisant le label custom :

export function reportWebVitals(metric) {
  if (metric.label === 'custom') {
    console.log(metric) // L'objet métrique ({ id, name, startTime, value, label }) est enregistré dans la console
  }
}

Il existe également l'option de gérer chaque métrique séparément :

export function reportWebVitals(metric) {
  switch (metric.name) {
    case 'Next.js-hydration':
      // traiter les résultats d'hydratation
      break
    case 'Next.js-route-change-to-render':
      // traiter les résultats de changement de route vers affichage
      break
    case 'Next.js-render':
      // traiter les résultats d'affichage
      break
    default:
      break
  }
}

Ces métriques fonctionnent dans tous les navigateurs qui prennent en charge l'API User Timing.

Envoi des résultats vers des systèmes externes

Avec la fonction de relais, vous pouvez envoyer les résultats vers n'importe quel endpoint pour mesurer et suivre les performances réelles des utilisateurs sur votre site. Par exemple :

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

  // Utilisez `navigator.sendBeacon()` si disponible, sinon utilisez `fetch()`.
  if (navigator.sendBeacon) {
    navigator.sendBeacon(url, body)
  } else {
    fetch(url, { body, method: 'POST', keepalive: true })
  }
}

Bon à savoir : Si vous utilisez Google Analytics, l'utilisation de la valeur id peut vous permettre de construire manuellement des distributions de métriques (pour calculer des percentiles, etc.)

export function reportWebVitals({ id, name, label, value }) {
  // Utilisez `window.gtag` si vous avez initialisé Google Analytics comme dans cet exemple :
  // 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), // les valeurs doivent être des entiers
    event_label: id, // id unique au chargement de page actuel
    non_interaction: true, // évite d'affecter le taux de rebond.
  })
}

En savoir plus sur l'envoi de résultats à Google Analytics.

TypeScript

Si vous utilisez TypeScript, vous pouvez utiliser le type intégré NextWebVitalsMetric :

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