Utilisation de l'API Chrome UX Reporting

Les Rapport Chrome UX L'ensemble de données (CrUX) représente la façon dont les utilisateurs de Chrome dans le monde réel découvrent les destinations populaires sur le Web. Depuis 2017, lorsque l'ensemble de données interrogeable a été publié pour la première fois dans BigQuery, les données de champ CrUX ont été intégrées dans des outils de développement tels que PageSpeed ​​Insights, CrUX Dashboard et Search Console. Rapport Core Web Vitals, permettant aux développeurs de mesurer et de surveiller facilement les expériences réelles des utilisateurs. La pièce manquante pendant tout ce temps est un outil qui fournit un accès gratuit et RESTful aux données CrUX par programmation. Pour aider à combler cet écart, nous sommes heureux d'annoncer le lancement du nouveau API Chrome UX Reporting!

Cette API a été créée dans le but de fournir aux développeurs un accès facile, rapide et complet aux données CrUX. L'API CrUX rapporte uniquement Campagne données sur l'expérience utilisateur, par opposition aux données existantes API PageSpeed ​​Insights, qui informe également laboratoire les données des audits de performance de Lighthouse. L'API CrUX est rationalisée et peut rapidement servir les données d'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 qui comptent le plus (les éléments constitutifs de Web Vitals), l'API CrUX audite et surveille la plus grande peinture de contenu (LCP), le délai de première entrée (FID) et le changement de conception cumulatif (CLS) à la fois la source et le niveau d'URL.

Alors plongeons-nous et voyons comment l'utiliser!

Requête de données source

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

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

Exécutez cette requête de manière interactive sur le Explorateur d'API CrUX.

Les boucle La commande 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. Les Type de contenu: application / json en-tête, qui indique que le corps de la demande contient JSON.
3. L'encodage JSON demande de corps, en spécifiant le https://web.dev Origine.

Pour faire de même en JavaScript, utilisez le CrUXApiUtil utilitaire, qui effectue l'appel d'API et renvoie la réponse décodée.

const CrUXApiUtil = { } ;

 CrUXApiUtil . API_KEY = '[VOTRE_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 'Remplacez "YOUR_API_KEY" par votre clé API CrUX privée. Obtenez une clé sur https://goo.gle/crux-api-key. ' ;
 }
 return fetch ( CrUXApiUtil . API_ENDPOINT , {
 méthode : 'POST' ,
 corps : JSON . stringify ( requestBody )
 } ) . alors ( réponse => réponse . json ( ) ) . alors ( réponse => {
 if ( réponse . erreur ) {
 retour Promise . rejeter ( réponse ) ;
 }
 réponse de retour ;
 } ) ;
 } ;

Remplacer [VOTRE_API_KEY] avec ton clé. Puis appelez CrUXApiUtil.query fonction et passer dans le demande de corps objet.

CrUXApiUtil . requête ( {
 origine : 'https://web.dev'
 } ) . alors ( réponse => {
 console . log ( réponse ) ;
 } ) . catch ( réponse => {
 console . erreur ( réponse ) ;
 } ) ;

Si des données existent pour cette source, la réponse de l'API est un objet codé JSON qui contient métrique A représentant la distribution des expériences utilisateur. Les métriques de distribution sont des intervalles 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 démarrer y finir propriétés de histogramme L'objet représente la plage de valeurs que les utilisateurs rencontrent pour la métrique donnée. Les densité La propriété représente la proportion d'expériences utilisateur dans cette plage. Dans cet exemple, les 79% des expériences utilisateur LCP sur toutes les pages web.dev sont inférieures à 2500 millisecondes, ce qui est le «bon» seuil LCP. Les percentiles.p75 La valeur signifie que le 75% des expériences utilisateur dans cette distribution est inférieur à 2216 millisecondes. En savoir plus sur la structure de réponse dans le corps de réponse Documentation.

Erreurs

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

{
 "erreur" : {
 "code" : 404 ,
 "message" : "Données du rapport chrome ux non trouvées" ,
 "status" : "NOT_FOUND"
 }
 }

Pour déboguer ce bogue, vérifiez d'abord que l'origine demandée est accessible publiquement. Vous pouvez tester cela en entrant l'origine dans la barre d'URL de votre navigateur et en la comparant à l'URL finale après toute redirection. Les problèmes courants incluent l'ajout ou l'omission inutilement du sous-domaine et l'utilisation du mauvais protocole HTTP.

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

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

Si l'origine demandée c'est la version navigable, cette erreur peut également se produire si la source a un nombre d'échantillons insuffisant. Toutes les sources et URL incluses dans l'ensemble de données doivent avoir un nombre suffisant d'échantillons pour anonymiser les utilisateurs individuels. En outre, les origines et les URL doivent être publiquement traçable. Se référer à Méthodologie CrUX pour plus d'informations sur la manière dont les sites Web sont inclus dans l'ensemble de données.

Requête de données URL

Vous avez vu comment interroger l'API CrUX pour l'expérience utilisateur globale dans une source. Pour limiter les résultats à une page particulière, utilisez le URL paramètre de demande.

API_KEY = "[VOTRE_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 similaire à l'exemple source, sauf que le corps de la requête utilise le URL paramètre pour spécifier la page à rechercher.

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

CrUXApiUtil . requête ( {
 url : "https://web.dev/fast/"
 } ) . alors ( réponse => {
 console . log ( réponse ) ;
 } ) . catch ( réponse => {
 console . erreur ( réponse ) ;
 } ) ;

Si des données pour cette URL existent dans l'ensemble de données CrUX, l'API renverra une réponse codée JSON comme celle illustrée ci-dessous.

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

Fidèle à sa forme, les résultats montrent que https://web.dev/fast/ il a un 85% de «bonnes» expériences LCP et un 75e percentile de 1 947 millisecondes, ce qui est légèrement meilleur que la distribution source entière.

Normalisation d'URL

L'API CrUX peut normaliser les URL demandées pour mieux correspondre à la liste des URL connues. Par exemple, interrogez l'URL https://web.dev/fast/#measure-performance-in-the-field se traduira par des données pour https://web.dev/fast/ en raison de la normalisation. Lorsque cela se produit, un urlNormalizationDetails L'objet sera inclus dans la réponse.

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

En savoir plus sur Normalisation d'URL dans la documentation CrUX.

Requête par facteur de forme

Les expériences utilisateur peuvent 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 l'origine et les performances de l'URL à l'aide du facteur de forme Dimension de l'API CrUX.

L'API prend en charge trois valeurs de facteur de forme explicites: BUREAU, TÉLÉPHONERy TABLETTE. En plus de l'origine ou de l'URL, spécifiez l'une de ces valeurs dans le demande de corps pour limiter les résultats aux expériences utilisateur uniquement. L'exemple suivant montre comment interroger l'API par facteur de forme à l'aide de cURL.

API_KEY = "[VOTRE_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 pour obtenir des données spécifiques au facteur de forme à l'aide de JavaScript, appelez CrUXApiUtil.query fonction utilisant la URL y facteur de forme paramètres dans le corps de la requête.

CrUXApiUtil . requête ( {
 url : 'https://web.dev/fast/' ,
 formFactor : 'TÉLÉPHONE'
 } ) . alors ( réponse => {
 console . log ( réponse ) ;
 } ) . catch ( réponse => {
 console . erreur ( réponse ) ;
 } ) ;

Sauter le facteur de forme paramètre é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
        }
      },
    
    }
  }
}

Les clé le champ de réponse fera écho au facteur de forme Demandez la configuration pour confirmer que seules les expériences téléphoniques sont incluses.

Rappelez-vous de la section précédente que le 85% des expériences utilisateur sur cette page avait un "bon" LCP. Comparez cela à des expériences téléphoniques spécifiques, dont seul le 78% est considéré comme «bon». Le 75e centile est également le plus lent parmi les expériences téléphoniques, passant de 1 947 millisecondes à 2 366 millisecondes. Le ciblage par facteur de forme a le potentiel de mettre en évidence des disparités plus extrêmes dans les expériences des utilisateurs.

Évaluation des performances de Core Web Vitals

Le programme Core Web Vitals définit des objectifs qui aident à 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 le CrUXApiUtil.query pour évaluer si la distribution des métriques Core Web Vitals (LCP, FID, 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) {
  
  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;
    
    
    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 réussit les évaluations Core Web Vitals pour les trois métriques.

Le 75e percentile (1973) de la plus grande_contentful_paint dépasse le seuil "bon" de Core Web Vitals (2500).
 Le 75e centile (20) de first_input_delay dépasse le seuil "bon" Core Web Vitals (100).
 Le 75e centile (0,05) de cumulative_layout_shift dépasse le seuil de «bon» Core Web Vitals (0,10).

Combinées à un moyen automatisé de surveiller les résultats de l'API, les données CrUX peuvent être utilisées pour garantir que les expériences des utilisateurs aller vite y reste vite. Pour plus d'informations sur Core Web Vitals et comment les mesurer, consultez Web Vitals et Tools for Measuring Core Web Vitals.

Suivant?

Les fonctionnalités incluses dans la version initiale de l'API CrUX ne font qu'effleurer la surface des types d'informations possibles avec CrUX. Les utilisateurs de l'ensemble de données CrUX dans BigQuery connaissent peut-être certaines des fonctionnalités les plus avancées, notamment:

• Métriques supplémentaires
  • first_paint
  • dom_content_loaded
  • en charge
  • time_to_first_byte
  • notification_permissions
• Dimensions supplémentaires
  • mois
  • Pays
  • type de connexion efficace (ECT)
• Granularité supplémentaire
  • histogrammes détaillés
  • plus de centiles

Au fil du temps, nous espérons intégrer davantage de ces fonctionnalités avec la facilité d'utilisation et la tarification gratuite de l'API CrUX pour permettre de nouvelles façons d'explorer les données et de découvrir des informations sur l'état des expériences des utilisateurs sur le Web.

Jetez un oeil à l'officiel Documents de l'API CrUX à acquérir votre clé API et explorez d'autres exemples d'applications. Nous espérons que vous l'essaierez et serions ravis d'entendre vos questions ou commentaires, alors contactez-nous à Forum de discussion CrUX. Et pour rester au courant de tout ce que nous avons prévu pour l'API CrUX, abonnez-vous à Forum d'annonces CrUX ou suivez-nous sur Twitter à @ChromeUXReport.