Utiliser l'API CrUX

Découvrez comment utiliser l'API Chrome UX Report pour accéder à des données sur l'expérience utilisateur 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 interrogeable sur BigQuery, les données 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, ce qui permet aux développeurs de mesurer et de surveiller l'expérience utilisateur en conditions réelles. L'élément qui manquait pendant toute cette période, c'est un outil offrant un accès libre et RESTful aux données CrUX de manière programmatique. Pour combler ce manque, nous sommes heureux d'annoncer le lancement 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 génère des rapports que sur les données sur l'expérience utilisateur en conditions réelles, contrairement à l'API PageSpeed Insights existante, qui présente également des données de test issues des audits de performances Lighthouse. L'API CrUX est optimisée et peut rapidement diffuser 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 effectue des audits 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.

Entrons dans le vif du sujet et voyons comment l'utiliser.

Données d'origine de la requête

Les origines dans 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 dans 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. Dans l'exemple précédent, [YOUR_API_KEY] est un espace réservé. 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. Le 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é au format 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);
});

S'il existe des données pour cette origine, la réponse de l'API est un objet encodé au format JSON contenant des métriques représentant la répartition 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 voient 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 l'ensemble des pages web.dev sont inférieures à 2 500 millisecondes, ce qui correspond à la bonne expérience. Seuil de LCP. La valeur percentiles.p75 signifie que 75% des expériences utilisateur dans cette distribution durent moins de 2 216 millisecondes. Pour en savoir plus sur la structure des réponses, 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é 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 publiquement. Pour ce faire, 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 sont l'ajout ou l'omission inutile du sous-domaine et l'utilisation d'un protocole HTTP incorrect.

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

Ce point de départ est public.

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

Données d'URL de requête

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 en particulier, 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 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 les données de 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/ 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 d'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é:un facteur de forme désigne le type d'appareil sur lequel un utilisateur consulte un site Web. Les types d'appareils les plus courants incluent les ordinateurs, 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 de l'expérience utilisateur appareils. Pour mieux comprendre ces différences, affichez le détail des 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 à la recherche de 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);
});

Si vous omettez le paramètre formFactor, cela 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 renvoie la configuration de requête formFactor pour confirmer que seules les expériences téléphoniques 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 comprendra d'expériences utilisateur. Cela peut entraîner une fréquence de recherche "introuvable" plus fréquente d'erreurs, en particulier lorsque vous interrogez des URL les moins populaires ou le type de tablette le moins populaire.

Comme nous l'avons vu dans la section précédente, 85% des expériences utilisateur sur cette page étaient bonnes. LCP. Comparez ce résultat aux expériences spécifiques aux téléphones, dont seulement 78% sont considérées comme de bonnes performances. Le 75e centile est également plus lent sur les téléphones, passant de 1 947 à 2 366 millisecondes. La segmentation par facteur de forme peut mettre en évidence des disparités plus extrêmes dans l'expérience utilisateur.

Évaluer les performances des Core Web Vitals

Le programme Core Web Vitals définit des cibles qui aident à déterminer si une expérience utilisateur ou une distribution d'expériences peut être considérée comme "satisfaisante". 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 "satisfaisante".

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

function assessCoreWebVitals(response) {
  // See https://web.dev/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}).`)
  });
}

Important: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 réussit 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).

Associées à une méthode automatisée de surveillance des résultats de l'API, les données CrUX permettent de garantir que l'expérience utilisateur réelle augmente et reste rapide. Pour en savoir plus sur les métriques Core Web Vitals et découvrir comment les mesurer, consultez les pages Web Vitals et Outils permettant de mesurer les métriques 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 sur BigQuery connaissent peut-être certaines des fonctionnalités les plus avancées, parmi lesquelles:

• 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)
• Niveau de précision supplémentaire
  • des histogrammes détaillés
  • centiles supplémentaires

Consultez la documentation officielle sur l'API CrUX pour obtenir votre clé API et découvrir d'autres exemples d'applications. Nous espérons que vous l'essayerez et nous serions ravis de recevoir vos questions et commentaires. N'hésitez donc pas à nous contacter sur le forum de discussion CrUX. Pour vous tenir informé de tout ce que nous avons prévu concernant l'API CrUX, abonnez-vous au forum d'annonce CrUX ou suivez-nous sur Twitter : @ChromeUXReport.