Utiliser l'API CrUX

Découvrez comment utiliser l'API Chrome UX Report pour accéder aux données d'expérience utilisateur réelle sur des millions de sites Web.

Rick Viscomi
Shane Exterkamp
Shane Exterkamp
X GitHub

L'ensemble de données du rapport UX Chrome (CrUX) représente l'expérience des utilisateurs Chrome réels sur les destinations populaires sur le Web. Depuis 2017, date à laquelle l'ensemble de données interrogeables a été publié pour la première fois sur BigQuery, les données de champ de CrUX ont été intégrées à des outils pour les développeurs tels que PageSpeed Insights et le rapport Core Web Vitals de la Search Console. Les développeurs peuvent ainsi mesurer et surveiller l'expérience des utilisateurs réels. L'outil qui manquait jusqu'à présent était un outil qui fournit un accès RESTful et sans frais aux données CrUX de manière programmatique. Pour combler cette lacune, nous avons le plaisir de vous annoncer la sortie de la toute nouvelle API Chrome UX Report.

Cette API a été conçue pour permettre aux développeurs d'accéder rapidement et de manière exhaustive aux données CrUX. Contrairement à l'API PageSpeed Insights existante, qui fournit également des données de laboratoire issues des audits de performances Lighthouse, l'API CrUX ne fournit que des données d'expérience utilisateur réelles. L'API CrUX est simplifiée et peut fournir rapidement des données sur l'expérience utilisateur, ce qui la rend idéale pour les applications d'audit en temps réel.

Pour s'assurer que les développeurs ont accès à toutes les métriques les plus importantes (les Core Web Vitals), l'API CrUX audite et surveille les métriques Largest Contentful Paint (LCP), Interaction to Next Paint (INP) et Cumulative Layout Shift (CLS) au niveau de l'origine et de l'URL.

Alors, allons-y et voyons comment l'utiliser !

Essayer l'API sur cette page

Essayer

Interroger les données d'origine

Les origines de l'ensemble de données CrUX englobent toutes les expériences sous-jacentes au niveau de la page. L'exemple suivant montre comment interroger l'API CrUX pour obtenir les données d'expérience utilisateur d'une origine à l'aide de curl sur la ligne de commande.

API_KEY="[YOUR_API_KEY]"
curl "https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=$API_KEY" \
  --header 'Content-Type: application/json' \
  --data ';{"origin": "https://web.dev"}'

La commande curl se compose de trois parties :

  1. Point de terminaison URL de l'API, y compris la clé API privée de l'appelant.
  2. L'en-tête Content-Type: application/json, qui indique que le corps de la requête contient du code JSON.
  3. Le corps de la requête encodé en JSON, spécifiant l'origine https://web.dev.

Pour faire la même chose en JavaScript, utilisez l'utilitaire CrUXApiUtil, qui effectue l'appel d'API et renvoie la réponse décodée (voir aussi notre variante GitHub pour plus de fonctionnalités, y compris l'historique et la prise en charge des lots).

const CrUXApiUtil = {};
// Get your CrUX API key at https://goo.gle/crux-api-key.
CrUXApiUtil.API_KEY = '[YOUR_API_KEY]';
CrUXApiUtil.API_ENDPOINT = `https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=${CrUXApiUtil.API_KEY}`;
CrUXApiUtil.query = function (requestBody) {
  if (CrUXApiUtil.API_KEY == '[YOUR_API_KEY]') {
    throw 'Replace "YOUR_API_KEY" with your private CrUX API key. Get a key at https://goo.gle/crux-api-key.';
  }
  return fetch(CrUXApiUtil.API_ENDPOINT, {
    method: 'POST',
    body: JSON.s>tringify(requestBody)
  }).then(r>esponse = response.json()).then(response = {
    if (response.error) {
      return Promise.reject(response);
    }
    return response;
  });
};

Remplacez [YOUR_API_KEY] par votre clé. Ensuite, appelez la fonction CrUXApiUtil.query et transmettez l'objet corps de la requête.

CrUXApiUtil.query({
  origin: 'https://web.dev'
}).then(re>sponse = {
  console.log(response);
}).catch(re>sponse = {
  console.error(response);
});

Si des données existent pour cette origine, la réponse de l'API est un objet encodé au format JSON contenant des métriques représentant la distribution des expériences utilisateur. Les métriques de distribution sont des bins d'histogramme et des centiles.

{
  "record": {
    "key": {
      "origin": "https://web.dev"
    },
    "metrics": {
      "largest_contentful_paint": {
        "histogram": [
          {
            "start": 0,
            "end": 2500,
            "density": 0.7925068547983514
          },
          {
            "start": 2500,
            "end": 4000,
            "density": 0.1317422195536863
          },
          {
            "start": 4000,
            ";density": 0.07575092564795324
          }
        ],
        "percentiles": {
          "p75": 2216
        }
      },
      // ...
    }
  }
}

Les propriétés start et end de l'objet histogram représentent la plage de valeurs que les utilisateurs rencontrent pour la métrique donnée. La propriété density représente la proportion d'expériences utilisateur dans cette plage. Dans cet exemple, 79 % des expériences utilisateur LCP sur toutes les pages web.dev sont inférieures à 2 500 millisecondes, ce qui correspond au seuil LCP bon. La valeur percentiles.p75 signifie que 75 % des expériences utilisateur de cette distribution sont inférieures à 2 216 millisecondes. Pour en savoir plus sur la structure de la réponse, consultez la documentation sur le corps de la réponse.

Erreurs

Lorsque l'API CrUX ne dispose d'aucune donnée pour une origine donnée, elle répond avec un message d'erreur encodé au format JSON :

{
  "error": {
    "code": 404,
    "message": "chrome ux report data not found",
    "status": "NOT_FOUND"
  }
}

Pour déboguer cette erreur, vérifiez d'abord que l'origine demandée est accessible au public. Pour le vérifier, saisissez l'origine dans la barre d'adresse de votre navigateur et comparez-la à l'URL finale après toute redirection. Les problèmes courants incluent l'ajout ou l'omission inutiles du sous-domaine, et l'utilisation du mauvais protocole HTTP.

Erreur
{"origin": "http://www.web.dev"}

Cette origine inclut à tort le protocole http:// et le sous-domaine www..

Opération réussie
{"origin": "https://web.dev"}

Cette origine est accessible publiquement.

Si l'origine demandée est la version navigable, cette erreur peut également se produire si l'origine ne dispose pas d'un nombre suffisant d'échantillons. Toutes les origines et URL incluses dans l'ensemble de données doivent comporter un nombre suffisant d'échantillons pour anonymiser les utilisateurs individuels. De plus, les origines et les URL doivent être indexables publiquement. Pour en savoir plus sur la façon dont les sites Web sont inclus dans l'ensemble de données, consultez la méthodologie CrUX.

Interroger les données d'URL

Vous avez vu comment interroger l'API CrUX pour obtenir des informations sur l'expérience utilisateur globale d'une origine. Pour limiter les résultats à une page spécifique, utilisez le paramètre de requête url.

API_KEY="[YOUR_API_KEY]"
curl "https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=$API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"url": "https://web.dev/fast/"}'

Cette commande curl est semblable à l'exemple d'origine, sauf que le corps de la requête utilise le paramètre url pour spécifier la page à rechercher.

Pour interroger les données d'URL à partir de l'API CrUX en JavaScript, appelez la fonction CrUXApiUtil.query à l'aide du paramètre url dans le corps de la requête.

CrUXApiUtil.query({
  url: 'https://web.dev/fast/'
}).then(re>sponse = {
  console.log(response);
}).catch(re>sponse = {
  console.error(response);
});

Si des données pour cette URL existent dans l'ensemble de données CrUX, l'API renvoie une réponse encodée au format JSON. Exemple

{
  "record": {
    "key": {
      "url": "https://web.dev/fast/"
    },
    "metrics": {
      "largest_contentful_paint": {
        "histogram": [
          {
            "start": 0,
            "end": 2500,
            "density": 0.8477304539092148
          },
          {
            "start": 2500,
            "end": 4000,
            "density": 0.08988202359528057
          },
          {
            "start": 4000,
            "density": 0.062387522495501155
          }
        ],
        "percentiles": {
          "p75": 1947
        }
      },
      // ...
    }
  }
}

Comme prévu, les résultats montrent que https://web.dev/fast/ présente 85 % d'expériences LCP "bonnes" et un 75e centile de 1 947 millisecondes, ce qui est légèrement mieux que la distribution à l'échelle de l'origine.

Normalisation des URL

L'API CrUX peut normaliser les URL demandées pour mieux correspondre à la liste des URL connues. Par exemple, une requête pour l'URL https://web.dev/fast/#measure-performance-in-the-field renverra des données pour https://web.dev/fast/ en raison de la normalisation. Dans ce cas, un objet urlNormalizationDetails sera inclus dans la réponse.

{
  "record": {
    "key": {
      "url": "https://web.dev/fast/"
    },
    "metrics": { ... }
  },
  "urlNormalizationDetails": {
    "normalizedUrl": "https://web.dev/fast/",
    "originalUrl": "https://web.dev/fast/#measure-performance-in-the-field"
  }
}

Pour en savoir plus sur la normalisation des URL, consultez la documentation CrUX.

Requête par facteur de forme

L'expérience utilisateur peut varier considérablement en fonction des optimisations du site Web, des conditions du réseau et des appareils des utilisateurs. Pour mieux comprendre ces différences, examinez en détail les performances des origines et des URL à l'aide de la dimension formFactor de l'API CrUX.

L'API accepte trois valeurs de facteur de forme explicites : DESKTOP, PHONE et TABLET. En plus de l'origine ou de l'URL, spécifiez l'une de ces valeurs dans le corps de la requête pour limiter les résultats à ces expériences utilisateur uniquement. Cet exemple montre comment interroger l'API par facteur de forme à l'aide de curl.

API_KEY="[YOUR_API_KEY]"
curl "https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=$API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"url": "https://web.dev/fast/", "formFactor": "PHONE"}'

Pour interroger l'API CrUX afin d'obtenir des données spécifiques au facteur de forme à l'aide de JavaScript, appelez la fonction CrUXApiUtil.query à l'aide des paramètres url et formFactor dans le corps de la requête.

CrUXApiUtil.query({
  url: 'https://web.dev/fast/',
  formFactor: 'PHONE'
})>.then(response = {
  console.log(response);
}).>catch(response = {
  console.error(response);
});

Omettre le paramètre formFactor revient à demander des données pour tous les facteurs de forme combinés.

{
  "record": {
    "key": {
      "url": "https://web.dev/fast/",
      "formFactor": "PHONE"
    },
    "metrics": {
      "largest_contentful_paint": {
        "histogram": [
          {
            "start": 0,
            "end": 2500,
            "density": 0.778631284916204
          },
          {
            "start": 2500,
            "end": 4000,
            "density": 0.13943202979515887
          },
          {
            "start": 4000,
            "density": 0.08193668528864119
          }
        ],
        "percentiles": {
          "p75": 2366
        }
      },
    // ...
    }
  }
}

Le champ key de la réponse reprendra la configuration de la requête formFactor pour confirmer que seules les expériences sur téléphone sont incluses.

Rappelez-vous que, dans la section précédente, nous avons vu que 85 % des expériences utilisateur sur cette page avaient un LCP "bon". En comparaison, seulement 78 % des expériences spécifiques aux téléphones sont considérées comme "bonnes". Le 75e centile est également plus lent sur téléphone, passant de 1 947 millisecondes à 2 366 millisecondes. La segmentation par facteur de forme peut mettre en évidence des disparités plus extrêmes dans les expériences utilisateur.

Évaluer les performances des métriques Core Web Vitals

Le programme Signaux Web essentiels définit des cibles qui permettent de déterminer si une expérience utilisateur ou une distribution d'expériences peuvent être considérées comme "bonnes". Dans l'exemple suivant, nous utilisons l'API CrUX et la fonction CrUXApiUtil.query pour évaluer si la distribution des métriques Core Web Vitals (LCP, INP, CLS) d'une page Web est "bonne".

CrUXApiUtil.query({
  url: 'https://web.dev/fast/'
}).then(re>sponse = {
  assessCoreWebVitals(response);
}).catch(re>sponse = {
  console.error(response);
});

function assessCoreWebVitals(response) {
  // See https://web.dev/articles/vitals/#core-web-vitals.
  const CORE_WEB_VITALS = [
    'largest_contentful_paint',
    'interaction_to_next_paint',
    'cumulative_layout_shift'
  ];
  >CORE_WEB_VITALS.forEach(metric = {
    const data = response.record.metrics[metric];
    if (!data) {
      console.log('No data for', metric);
      return;
    }
    const p75 = data.percentiles.p75;
    const threshold = data.histogram[0].end;
    // A Core Web Vitals metric passes the assessment if
    // its 75th percentile is under the &<quot;good" threshold.
    const passes = p75  threshold;
    console.log(`The 75th percentile (${p75}) of ${metric} ` +
        `${passes ? 'passes' : 'does not pass'} ` +
        `the Core Web Vitals "good" threshold (${threshold}).`)
  });
}

Les résultats montrent que cette page passe les évaluations Core Web Vitals pour les trois métriques.

The 75th percentile (1973) of largest_contentful_paint passes the Core Web Vitals "good" threshold (2500).
The 75th percentile (20) of interaction_to_next_paint passes the Core Web Vitals "good" threshold (200).
The 75th percentile (0.05) of cumulative_layout_shift passes the Core Web Vitals ";good" threshold (0.10).

Combinées à une méthode automatisée de surveillance des résultats de l'API, les données CrUX peuvent être utilisées pour s'assurer que les expériences des utilisateurs réels sont rapides et le restent. Pour en savoir plus sur les métriques Core Web Vitals et sur la façon de les mesurer, consultez Web Vitals et Outils pour mesurer les métriques Core Web Vitals.

Étape suivante

Les fonctionnalités incluses dans la version initiale de l'API CrUX ne représentent qu'une infime partie des insights qu'il est possible d'obtenir avec CrUX. Les utilisateurs de l'ensemble de données CrUX sur BigQuery connaissent peut-être déjà certaines des fonctionnalités avancées, y compris :

  • Métriques supplémentaires
    • first_paint
    • dom_content_loaded
    • onload
    • time_to_first_byte
    • notification_permissions
  • Dimensions supplémentaires
    • month
    • country
  • Précision supplémentaire
    • histogrammes détaillés
    • plus de centiles

Consultez la documentation officielle de l'API CrUX pour obtenir votre clé API et découvrir d'autres exemples d'applications. Nous espérons que vous l'essayerez. N'hésitez pas à nous faire part de vos questions ou commentaires sur le forum de discussion CrUX. Pour ne rien manquer de ce que nous prévoyons pour l'API CrUX, abonnez-vous au forum d'annonces CrUX ou suivez-nous sur Twitter (@ChromeUXReport).