Utilisation de l'API Chrome UX Reporting

Les Rapport Chrome UX El conjunto de datos (CrUX) representa cómo los usuarios de Chrome en el mundo real experimentan los destinos populares en la web. Desde 2017, cuando el conjunto de datos consultables se lanzó por primera vez en BigQuery, los datos de campo de CrUX se han integrado en herramientas para desarrolladores como PageSpeed ​​Insights, CrUX Tableau de bord y Search Console. Rapport Core Web Vitals, lo que permite a los desarrolladores medir y monitorear fácilmente las experiencias de los usuarios reales. La pieza que ha faltado todo este tiempo ha sido una herramienta que proporciona acceso gratuito y RESTful a los datos de CrUX mediante programmation. Para ayudar a cerrar esa brecha, nos complace anunciar el lanzamiento de las nuevas API Chrome UX Reporting!

Esta API se ha creado con el objectif de proporcionar a los desarrolladores un acceso sencillo, rápido y completo a los datos de CrUX. La API de CrUX solo informa 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.

Para garantizar que los desarrolladores tengan acceso a todas las métricas que más importan (los elementos básicos de Web Vitals), la API de CrUX audita y supervisa la pintura de Contenu más grande (LCP), el retraso de la primera entrada (FID) y el cambio de diseño acumulativo (CLS) en ambos el origen y el nivel de 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="[YOUR_API_KEY]"
boucle "https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=$API_KEY" 
  --header 'Content-Type: application/json' 
  --data '{"origin": "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.

Para hacer lo mismo en JavaScript, use el CrUXApiUtil utilitaire, qui effectue l'appel d'API et renvoie la réponse décodée.

const CrUXApiUtil = {};

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;
  });
};

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

CrUXApiUtil.mettre en doute({
  origin: 'https://web.dev'
}).then(response => {
  console.Journal(response);
}).catch(response => {
  console.Erreur(response);
});

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:

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

Para depurar este error, primero verifique que el origen solicitado être navegable públicamente. Puede probar esto ingresando el origen en la barra de URL de su le navigateur y comparándolo con la URL final después de cualquier réorienter. Los problemas comunes incluyen agregar u omitir innecesariamente el sous-domaine y usar el protocolo HTTP incorrecto.

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

{"origin": "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="[YOUR_API_KEY]"
boucle "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.mettre en doute({
  URL: 'https://web.dev/fast/'
}).then(response => {
  console.Journal(response);
}).catch(response => {
  console.Erreur(response);
});

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": {
    "key": {
      "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="[YOUR_API_KEY]"
boucle "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.mettre en doute({
  URL: 'https://web.dev/fast/',
  facteur de forme: 'PHONE'
}).then(response => {
  console.Journal(response);
}).catch(response => {
  console.Erreur(response);
});

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.

Recuerde de la sección anterior que el 85% de las experiencias de los usuarios en esta página tenían un LCP «bueno». Compare eso con las experiencias específicas del teléfono, de las cuales solo el 78% se consideran «buenas». El percentil 75 también es más lento entre las experiencias telefónicas, pasando de 1.947 milisegundos a 2.366 milisegundos. La segmentation por factor de forma tiene el potencial de resaltar disparidades más extremas en las experiencias de los usuarios.

É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.mettre en doute({
  URL: 'https://web.dev/fast/'
}).then(response => {
  assessCoreWebVitals(response);
}).catch(response => {
  console.Erreur(response);
});

une fonction assessCoreWebVitals(response) {
  
  const CORE_WEB_VITALS = [
    'largest_contentful_paint',
    'first_input_delay',
    'cumulative_layout_shift'
  ];
  CORE_WEB_VITALS.forEach(metric => {
    const Les données = response.enregistrer.metrics[metric];
    si (!Les données) {
      console.Journal('No data for', metric);
      revenir;
    }
    const p75 = Les données.percentiles.p75;
    const au seuil = Les données.histogramme[0].finir;
    
    
    const passes = p75 < au seuil;
    console.Journal(`The 75th percentile (${p75}) of ${metric} ` +
        `${passes ? 'passes' : 'does not pass'} ` +
        `the Core Web Vitals "good" threshold (${au seuil}).`)
  });
}

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 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é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 o síguenos en Twitter au @ChromeUXReport.