Utiliser l'API CrUX

Découvrez comment utiliser l'API Chrome UX Report pour accéder à des données sur l'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 d'expérience utilisateur Chrome (CrUX) représente la façon dont des utilisateurs réels de Chrome accèdent à des destinations populaires sur le Web. Depuis 2017, lorsque l'ensemble de données interrogeable a été publié sur BigQuery, les données réelles issues de CrUX sont 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. Les développeurs peuvent ainsi mesurer et surveiller les expériences utilisateur réelles. Ce qui nous manquait depuis le début, c'est un outil qui fournit un accès sans frais et RESTful aux données CrUX de manière programmatique. Pour combler cette lacune, 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 communique que les données sur l'expérience utilisateur field, contrairement à l'API PageSpeed Insights existante, qui génère également des rapports sur les données d'atelier des audits de performances Lighthouse. L'API CrUX est simplifiée et permet de diffuser 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 la métrique Largest Contentful Paint (LCP), First Input Delay (FID) 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.

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 de l'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 JSON.
  3. Corps de la requête encodé au format JSON, qui spécifie 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 (consultez également 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.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 request body.

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é au format JSON et contient des metrics représentant la distribution des expériences utilisateur. Les métriques de distribution sont des classes et des centiles d'histogramme.

{
  "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 rencontrée par les utilisateurs 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 durent moins de 2 500 millisecondes, ce qui correspond au bon seuil 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 répond par 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, commencez par vérifier que l'origine demandée est accessible publiquement. Pour cela, saisissez l'origine dans la barre d'adresse de votre navigateur et comparez-la à l'URL finale après toute redirection. L'ajout ou l'omission inutile du sous-domaine, ou l'utilisation d'un protocole HTTP incorrect sont des problèmes courants.

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 le nombre d'échantillons de l'origine est insuffisant. Toutes les origines et URL incluses dans l'ensemble de données doivent comporter un nombre d'échantillons suffisant pour anonymiser les utilisateurs individuels. En outre, les origines et les URL doivent être indexables 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.

Interroger les données de l'URL

Vous avez vu comment interroger l'API CrUX pour connaître 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 sur l'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 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
        }
      },
      // ...
    }
  }
}

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

Normalisation des URL

L'API CrUX peut normaliser les URL demandées afin qu'elles correspondent mieux à 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. Lorsque cela se produit, 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

L'expérience utilisateur peut varier considérablement en fonction des optimisations de site Web, de l'état du réseau et des appareils des utilisateurs. Pour mieux comprendre ces différences, analysez 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 sur des données spécifiques à un 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);
});

L'omission du 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 renverra la configuration de la requête formFactor pour confirmer que seules les expériences téléphoniques sont incluses.

Comme nous l'avons vu dans la section précédente, 85% des expériences utilisateur sur cette page avaient un "bon" LCP. Comparez cela aux expériences spécifiques au téléphone, pour lesquelles seulement 78% d'entre elles sont considérées comme de "bonnes". Le 75e centile est également plus lent entre les expériences 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 Core Web Vitals

Le programme Core Web Vitals définit des cibles qui aident à déterminer si une expérience utilisateur ou une répartition 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, FID, 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',
    'first_input_delay',
    '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}).`)
  });
}

Les résultats montrent que cette page a réussi les évaluations des 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 first_input_delay passes the Core Web Vitals "good" threshold (100).
The 75th percentile (0.05) of cumulative_layout_shift passes the Core Web Vitals "good" threshold (0.10).

Combinés à un moyen automatisé de surveillance des résultats des API, les données CrUX peuvent être utilisées pour garantir que les expériences utilisateur réelles deviennent rapides et restent rapides. Pour en savoir plus sur les métriques Core Web Vitals et la façon de les mesurer, consultez les pages Signaux Web et Outils de mesure des Core Web Vitals.

Étape suivante

Les fonctionnalités incluses dans la version initiale de l'API CrUX ne font qu'effleurer les types d'insights possibles avec CrUX. Les utilisateurs de l'ensemble de données CrUX sur BigQuery connaissent peut-être certaines des fonctionnalités 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)
  • Niveau de précision supplémentaire
    • des histogrammes détaillés ;
    • de 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 allez l'essayer et nous serions ravis de recevoir vos questions et commentaires. N'hésitez pas à nous contacter sur le forum de discussion CrUX. Et pour vous tenir informé de tout ce que nous avons prévu concernant l'API CrUX, abonnez-vous au forum d'annonces CrUX ou suivez-nous sur Twitter à l'adresse @ChromeUXReport.