Utiliser l'API CrUX

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

Rick Viscomi

Shane Exterkamp

L'ensemble de données du rapport UX Chrome (CrUX) représente l'expérience utilisateur Chrome réelle sur des destinations populaires sur le Web. Depuis 2017, date de la première publication de l'ensemble de données interrogeables sur BigQuery, les données d'utilisation réelles de CrUX ont été intégrées à des outils pour les développeurs tels que PageSpeed Insights, le tableau de bord CrUX et le rapport Core Web Vitals de la Search Console. Cela permet aux développeurs de mesurer et de surveiller l'expérience des utilisateurs réels. L'élément manquant depuis tout ce temps était un outil qui fournit un accès sans frais et RESTful 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 dans le but de fournir aux développeurs un accès simple, rapide et complet aux données CrUX. L'API CrUX ne fournit que des données d'expérience utilisateur sur le terrain, contrairement à l'API PageSpeed Insights existante, qui fournit également des données en laboratoire issues des audits de performances Lighthouse. L'API CrUX est simplifiée et peut fournir rapidement des données sur l'expérience utilisateur. Elle est donc 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 le Largest Contentful Paint (LCP), l'Interaction to Next Paint (INP) et le Cumulative Layout Shift (CLS) au niveau de l'origine et de l'URL.

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"}'

Remarque:Toutes les requêtes API doivent fournir une valeur pour le paramètre key. [YOUR_API_KEY] dans l'exemple précédent est laissé en tant que remplissage. Obtenez votre propre clé API CrUX privée, comme décrit dans la documentation de l'API CrUX.

La commande curl se compose de trois parties:

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

Pour effectuer la même opération en JavaScript, utilisez l'utilitaire CrUXApiUtil, qui effectue l'appel d'API et renvoie la réponse décodée (voir également notre variante GitHub pour en savoir plus sur les 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.stringify(requestBody)
  }).then(response => response.json()).then(response => {
    if (response.error) {
      return Promise.reject(response);
    }
    return response;
  });
};

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

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

Si des données existent pour cette origine, la réponse de l'API est un objet encodé en JSON contenant des métriques représentant la distribution des expériences utilisateur. Les métriques de distribution sont les buckets d'histogramme et les 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 du LCP sur toutes les pages web.dev sont inférieures à 2 500 millisecondes, ce qui correspond au seuil de LCP acceptable. 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 renvoie un message d'erreur encodé en 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 tester ce comportement, saisissez l'origine dans la barre d'adresse de votre navigateur, puis comparez-la à l'URL finale après toute redirection. Les problèmes courants incluent l'ajout ou l'omission inutile du sous-domaine, ainsi que l'utilisation du mauvais protocole HTTP.

Erreur

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

Cette origine inclut de manière incorrecte le protocole http:// et le sous-domaine www..

Opération réussie

{"origin": "https://web.dev"}

Cette origine est accessible au public.

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 de l'URL

Vous avez vu comment interroger l'API CrUX pour obtenir l'expérience utilisateur globale sur 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, à l'exception du fait 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(response => {
  console.log(response);
}).catch(response => {
  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 en 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/ enregistre 85 % d'expériences LCP "bonnes" et un 75e centile de 1 947 millisecondes, ce qui est légèrement supérieur à la distribution à l'échelle de l'origine.

Normalisation des URL

L'API CrUX peut normaliser les URL demandées pour mieux les faire correspondre à la liste des URL connues. Par exemple, si vous interrogez l'URL https://web.dev/fast/#measure-performance-in-the-field, vous obtiendrez des données pour https://web.dev/fast/ en raison de la normalisation. Dans ce cas, un objet urlNormalizationDetails est 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

Terme clé:le facteur de forme est le type d'appareil sur lequel un utilisateur consulte un site Web. Les types d'appareils courants incluent les ordinateurs de bureau, les téléphones et les tablettes.

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, explorez les performances de l'origine 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. 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 équivaut à 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 renvoie la configuration de la requête formFactor pour confirmer que seules les expériences sur téléphone sont incluses.

Attention:Plus la requête est précise (par exemple, une combinaison spécifique d'URL et de facteur de forme), moins elle inclut d'expériences utilisateur. Cela peut entraîner des erreurs "Introuvable" plus fréquentes, en particulier lors de l'interrogation d'URL moins populaires ou du type d'appareil de tablette moins populaire.

Dans la section précédente, vous avez vu que 85% des expériences utilisateur sur cette page ont un LCP "bon". À comparer aux expériences spécifiques au téléphone, dont seulement 78% sont considérées comme "bonnes". Le 75e percentile est également plus lent pour les expériences sur téléphone, passant de 1 947 millisecondes à 2 366 millisecondes. Le segmentage 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 Core Web Vitals définit des cibles qui permettent de déterminer si une expérience utilisateur ou une distribution d'expériences peut être considérée comme "bonne". 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 et CLS) d'une page Web est "bonne".

CrUXApiUtil.query({
  url: 'https://web.dev/fast/'
}).then(response => {
  assessCoreWebVitals(response);
}).catch(response => {
  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 "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}).`)
  });
}

Principe clé:L'API ne peut être appelée qu'avec une seule origine ou URL à la fois. Pour évaluer plusieurs sites Web ou pages, effectuez des appels distincts à l'API.

Les résultats montrent que cette page a réussi 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 à un moyen automatisé de surveiller les résultats de l'API, les données du rapport d'expérience utilisateur Chrome peuvent être utilisées pour s'assurer que les expériences des utilisateurs réels sont rapides et restent rapides. Pour en savoir plus sur les Core Web Vitals et découvrir comment les mesurer, consultez Web Vitals et Outils pour mesurer les Core Web Vitals.

Étape suivante

Les fonctionnalités incluses dans la version initiale de l'API CrUX ne sont qu'un aperçu des types d'insights possibles avec CrUX. Les utilisateurs de l'ensemble de données CRUX dans BigQuery peuvent être familiarisés avec certaines des fonctionnalités les plus avancées, y compris les suivantes:

• Métriques supplémentaires
  • first_paint
  • dom_content_loaded
  • onload
  • time_to_first_byte
  • notification_permissions
• Dimensions supplémentaires
  • month
  • country
  • effective connection type (ECT)
• Précision supplémentaire
  • histogrammes détaillés
  • plus de percentiles

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'essaierez. N'hésitez pas à nous contacter sur le forum de discussion CRUX si vous avez des questions ou des commentaires. Pour vous tenir informé de tout ce que nous avons prévu pour l'API CrUX, abonnez-vous au forum d'annonces CrUX ou suivez-nous sur Twitter à l'adresse @ChromeUXReport.