L'API CrUX offre un accès à faible latence à des données agrégées sur l'expérience utilisateur au niveau de la page et de l'origine.
Cas d'utilisation courant
L'API CrUX permet d'interroger les métriques d'expérience utilisateur pour un URI spécifique, par exemple "Obtenir des métriques pour l'origine https://example.com
".
Clé API CrUX
L'utilisation de l'API CrUX nécessite une clé API Google Cloud provisionnée pour Chrome UX Report API
.
Obtenir et utiliser une clé API
Obtenir une cléVous pouvez également en créer un sur la page Identifiants.
Une fois la clé API obtenue, votre application peut ajouter le paramètre de requête key=yourAPIKey
à toutes les URL de requête.
La clé API peut s'intégrer aux URL en toute sécurité et ne nécessite pas d'encodage.
Consultez les exemples de requêtes.
Modèle de données
Cette section détaille la structure des données dans les requêtes et les réponses.
Enregistrement
Informations discrètes relatives à une page ou à un site. Un enregistrement peut contenir des données spécifiques à un identifiant et à une combinaison spécifique de dimensions. Un enregistrement peut contenir des données pour une ou plusieurs métriques.
Identifiants
Les identifiants spécifient les enregistrements à rechercher. Dans CrUX, ces identifiants sont des pages Web et des sites Web.
Origine
Lorsque l'identifiant est une origine, toutes les données présentes pour toutes les pages de cette origine sont regroupées. Par exemple, supposons que l'origine http://www.example.com
comportait des pages telles que décrites dans ce sitemap:
http://www.example.com/
http://www.example.com/foo.html
http://www.example.com/bar.html
Cela signifie que lorsque vous interrogez le rapport d'expérience utilisateur Chrome avec l'origine définie sur http://www.example.com
, les données pour http://www.example.com/
, http://www.example.com/foo.html
et http://www.example.com/bar.html
seront renvoyées, regroupées, car il s'agit de toutes les pages sous cette origine.
URL
Lorsque l'identifiant est une URL, seules les données de cette URL spécifique sont renvoyées. Revenons au sitemap d'origine http://www.example.com
:
http://www.example.com/
http://www.example.com/foo.html
http://www.example.com/bar.html
Si l'identifiant est défini sur URL avec la valeur http://www.example.com/foo.html
, seules les données de la page sont renvoyées.
Dimensions
Les dimensions identifient un groupe spécifique de données avec lesquelles un enregistrement est agrégé. Par exemple, un facteur de forme PHONE
indique que l'enregistrement contient des informations sur les chargements effectués sur un appareil mobile. Chaque dimension sera associée à un certain nombre de valeurs et, implicitement, si vous ne la spécifiez pas, elle sera cumulée avec toutes les valeurs. Par exemple, si vous spécifiez "aucun facteur de forme", cela signifie que l'enregistrement contient des informations sur les chargements effectués sur n'importe quel facteur de forme.
Facteur de forme
Classe d'appareil utilisée par l'utilisateur final pour accéder à la page. Il s'agit d'une classe générale d'appareils divisé en PHONE
, TABLET
et DESKTOP
.
Type de connexion effectif
Effective Connection Type (Type de connexion effectif) : estimation de la qualité de connexion de l'appareil lorsqu'il accède à la page. Il s'agit d'une classe générale divisée en offline
, slow-2G
, 2G
, 3G
et 4G
.
Métrique
Les métriques sont présentées sous forme d'agrégations statistiques sous forme d'histogrammes, de centiles et de fractions.
Les valeurs à virgule flottante sont arrondies à quatre chiffres après la virgule. Notez que les métriques cumulative_layout_shift
sont encodées en double sous la forme d'une chaîne. Elles ne sont donc pas considérées comme des nombres à virgule flottante et sont signalées à deux décimales dans la chaîne.
Histogramme
Lorsque les métriques sont exprimées dans un histogramme, nous indiquons les pourcentages de chargements de page compris dans des plages spécifiques pour cette métrique.
Un histogramme à trois bins pour un exemple de métrique se présente comme suit:
{
"histogram": [
{
"start": 0,
"end": 1000,
"density": 0.3818
},
{
"start": 1000,
"end": 3000,
"density": 0.4991
},
{
"start": 3000,
"density": 0.1192
}
]
}
Ces données indiquent que pour 38,18% des chargements de page, l'exemple de métrique a été mesuré entre 0 ms et 1 000 ms. Les unités de la métrique ne sont pas contenues dans cet histogramme. Dans ce cas, nous allons partir du principe qu'il s'agit de millisecondes.
En outre, 49,91% des chargements de page ont généré une valeur de métrique comprise entre 1 000 ms et 3 000 ms,et que 11, 92% une valeur supérieure à 3 000 ms.
Centiles
Les métriques peuvent également contenir des centiles qui peuvent être utiles pour des analyses supplémentaires. Nous indiquons des valeurs de métriques spécifiques au centile donné pour cette métrique. Ils se basent sur l'ensemble complet des données disponibles et non sur les données binaires finales. Elles ne correspondent donc pas nécessairement à un centile interpolé basé sur le l'histogramme binaire final.
{
"percentiles": {
"p75": 2063
}
}
Dans cet exemple, au moins 75% des chargements de page ont été mesurés avec la valeur de métrique <= 2063
.
Fractions
Les fractions indiquent les pourcentages de chargements de page auxquels il est possible d'attribuer un libellé d'une certaine manière. Dans ce cas, les valeurs des métriques sont ces étiquettes.
Par exemple, la métrique form_factors
est constituée d'un objet fractions
qui liste la répartition des facteurs de forme (ou appareils) couverts par la requête donnée:
"form_factors": {
"fractions": {
"desktop": 0.0377,
"tablet": 0.0288,
"phone": 0.9335
}
}
Dans ce cas, 3,77% des chargements de page ont été mesurés sur un ordinateur, 2,88% sur une tablette et 93,35% sur un téléphone, soit un total de 100 %.
Types de valeurs de métriques
Nom de métrique de l'API CrUX | Type de données | Unités métriques | Agrégations statistiques | Documentation |
---|---|---|---|---|
cumulative_layout_shift |
Deux décimales à double encodage sous forme de chaîne | sans unité | histogramme avec trois bins, centiles avec p75 | cls |
first_contentful_paint |
int | millisecondes | histogramme avec trois bins, centiles avec p75 | FCP |
first_input_delay (obsolète) |
int | millisecondes | histogramme avec trois bins, centiles avec p75 | fid |
interaction_to_next_paint |
int | millisecondes | histogramme avec trois bins, centiles avec p75 | inp |
largest_contentful_paint |
int | millisecondes | histogramme avec trois bins, centiles avec p75 | lcp |
experimental_time_to_first_byte |
int | millisecondes | histogramme avec trois bins, centiles avec p75 | ttfb |
form_factors |
Double décimale avec 4 chiffres | pourcentage | Mappage d'un facteur de forme à une fraction | facteurs de forme |
navigation_types |
Double décimale avec 4 chiffres | pourcentage | Mise en correspondance du type de navigation avec la fraction | types de navigation |
round_trip_time |
int | millisecondes | centiles avec p75 | rtt |
Mappage des noms des métriques BigQuery
Nom de métrique de l'API CrUX | Nom de la métrique BigQuery |
---|---|
cumulative_layout_shift |
layout_instability.cumulative_layout_shift |
first_contentful_paint |
first_contentful_paint |
first_input_delay |
first_input.delay |
interaction_to_next_paint |
interaction_to_next_paint |
largest_contentful_paint |
largest_contentful_paint |
experimental_time_to_first_byte |
experimental.time_to_first_byte |
navigation_types |
navigation_types |
form_factors |
n/a |
round_trip_time |
n/a |
Période de collecte
Depuis octobre 2022, l'API CrUX contient un objet collectionPeriod
avec des champs firstDate
et endDate
représentant les dates de début et de fin de la période d'agrégation. Exemple :
"collectionPeriod": {
"firstDate": {
"year": 2022,
"month": 9,
"day": 12
},
"lastDate": {
"year": 2022,
"month": 10,
"day": 9
}
}
Cela permet de mieux comprendre les données et de savoir si elles ont déjà été mises à jour pour le jour concerné ou si elles renvoient les mêmes données qu'hier.
Notez que l'API CrUX a environ deux jours de retard par rapport à la date d'aujourd'hui, car elle attend les données complètes pour la journée et un certain temps de traitement est nécessaire avant qu'elles ne soient disponibles dans l'API. Le fuseau horaire utilisé est celui de l'heure normale du Pacifique (PST), qui ne change pas pour l'heure d'été.
Exemples de requêtes
Les requêtes sont envoyées en tant qu'objets JSON à l'aide d'une requête POST envoyée à https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=[YOUR_API_KEY]"
. Le corps de la requête POST utilise les données de requête sous la forme d'un objet JSON:
{
"origin": "https://example.com",
"formFactor": "PHONE",
"metrics": [
"largest_contentful_paint",
"experimental_time_to_first_byte"
]
}
Par exemple, vous pouvez l'appeler depuis curl
à l'aide de la ligne de commande suivante (en remplaçant API_KEY
par votre clé):
curl -s --request POST 'https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=API_KEY' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{"formFactor":"PHONE","origin":"https://www.example.com","metrics":["largest_contentful_paint", "experimental_time_to_first_byte"]}'
Pour accéder aux données au niveau de la page via l'API, transmettez une propriété url
dans la requête, au lieu de origin
:
{
"url": "https://example.com/page",
"formFactor": "PHONE",
"metrics": [
"largest_contentful_paint",
"experimental_time_to_first_byte"
]
}
Si la propriété metrics
n'est pas définie, toutes les métriques disponibles sont renvoyées:
cumulative_layout_shift
first_contentful_paint
first_input_delay
(obsolète)interaction_to_next_paint
largest_contentful_paint
experimental_time_to_first_byte
navigation_types
form_factors
(indiqué uniquement si aucunformFactor
n'est spécifié dans la requête)
Si aucune valeur formFactor
n'est fournie, les valeurs seront agrégées pour tous les facteurs de forme.
Pour découvrir d'autres exemples de requêtes, consultez Utiliser l'API Chrome UX Report.
Pipeline de données
L'ensemble de données CrUX est traité par un pipeline afin de consolider, d'agréger et de filtrer les données avant d'être disponibles à l'aide de l'API.
La moyenne glissante
Les données du rapport d'expérience utilisateur Chrome correspondent à une moyenne glissante des métriques agrégées sur 28 jours. Cela signifie que les données présentées à un moment donné dans le rapport d'expérience utilisateur Chrome correspondent en réalité aux données des 28 derniers jours regroupées.
Cette approche est semblable à celle utilisée pour regrouper les rapports mensuels dans l'ensemble de données CrUX sur BigQuery.
Mises à jour quotidiennes
Les données sont mises à jour quotidiennement vers 04h00 UTC. Il n'existe pas de contrat de niveau de service concernant les heures de mise à jour. il est exécuté du mieux possible chaque jour.
Schéma
Il existe un seul point de terminaison pour l'API CrUX qui accepte les requêtes HTTP POST
. L'API renvoie un record
qui contient un ou plusieurs metrics
correspondant aux données de performances sur l'origine ou la page demandée.
Requête HTTP
POST https://chromeuxreport.googleapis.com/v1/records:queryRecord
L'URL utilise la syntaxe de transcodage gRPC.
Corps de la requête
Le corps de la requête doit contenir des données présentant la structure suivante:
{
"effectiveConnectionType": string,
"formFactor": enum (FormFactor),
"metrics": [
string
],
// Union field url_pattern can be only one of the following:
"origin": string,
"url": string
// End of list of possible types for union field url_pattern.
}
Champs | |
---|---|
effectiveConnectionType |
Le type de connexion effective est une dimension de requête qui spécifie la classe réseau effective à laquelle les données de l'enregistrement doivent appartenir. Ce champ utilise les valeurs Remarque: Si aucun type de connexion effectif n'est spécifié, un enregistrement spécial contenant des données globales sur tous les types de connexion effectifs est renvoyé. |
formFactor |
Le facteur de forme est une dimension de requête qui spécifie la classe d'appareil à laquelle les données de l'enregistrement doivent appartenir. Ce champ utilise les valeurs Remarque: Si aucun facteur de forme n'est spécifié, un enregistrement spécial contenant des données globales sur tous les facteurs de forme est renvoyé. |
metrics[] |
Métriques à inclure dans la réponse. Si aucune métrique n'est spécifiée, toutes les métriques trouvées sont renvoyées. Valeurs autorisées: |
Champ d'union url_ . url_pattern est l'identifiant principal d'une recherche d'enregistrement. Il ne peut s'agir que de l'un des éléments suivants: |
|
origin |
L'"origine" Exemples : |
url |
Le Exemples : |
Par exemple, pour demander les plus grandes valeurs Contentful Paint pour la page d'accueil de la documentation pour les développeurs Chrome:
{
"url": "https://developer.chrome.com/docs/",
"formFactor": "DESKTOP",
"metrics": [
"largest_contentful_paint"
]
}
Corps de la réponse
Les requêtes réussies renvoient des réponses avec un objet record
et un urlNormalizationDetails
dans la structure suivante:
{
"record": {
"key": {
object (Key)
},
"metrics": [
string: {
object (Metric)
}
]
},
"urlNormalizationDetails": {
object (UrlNormalization)
}
}
Par exemple, la réponse au corps de la requête dans la requête précédente peut être:
{
"record": {
"key": {
"formFactor": "DESKTOP",
"url": "https://developer.chrome.com/docs/"
},
"metrics": {
"largest_contentful_paint": {
"histogram": [
{
"start": 0,
"end": 2500,
"density": 0.9815
},
{
"start": 2500,
"end": 4000,
"density": 0.0108
},
{
"start": 4000,
"density": 0.0077
}
],
"percentiles": {
"p75": 651
}
}
},
"collectionPeriod": {
"firstDate": {
"year": 2022,
"month": 9,
"day": 12
},
"lastDate": {
"year": 2022,
"month": 10,
"day": 9
}
}
}
}
Clé
Key
définit toutes les dimensions qui identifient cet enregistrement comme unique.
{
"effectiveConnectionType": string,
"formFactor": enum (FormFactor),
// Union field url_pattern can be only one of the following:
"origin": string,
"url": string
// End of list of possible types for union field url_pattern.
}
Champs | |
---|---|
formFactor |
Le facteur de forme correspond à la classe de l'appareil que tous les utilisateurs ont utilisé pour accéder au site pour cet enregistrement. Si le facteur de forme n'est pas spécifié, les données globales sont renvoyées pour tous les facteurs de forme. |
effectiveConnectionType |
Le type de connexion effective correspond à la classe de connexion générale que tous les utilisateurs ont rencontrée pour cet enregistrement. Ce champ utilise les valeurs ["offline", "slow-2G", "2G", "3G", "4G"], telles que spécifiées dans: https://wicg.github.io/netinfo/#effective-connection-types Si le type de connexion effective n'est pas spécifié, les données globales sont renvoyées pour tous les types de connexions effectives. |
Champ d'union url_ . Le format d'URL correspond à l'URL à laquelle s'applique l'enregistrement. url_ ne peut être qu'un des éléments suivants : |
|
origin |
Remarque: Lorsque vous spécifiez un |
url |
Remarque: Lorsque vous spécifiez une |
Métriques
Un metric
est un ensemble de données agrégées sur l'expérience utilisateur pour une métrique de performances Web unique, telle que First Contentful Paint.
Il peut contenir un histogramme récapitulatif de l'utilisation réelle de Chrome, sous la forme d'une série de données de centiles bins
spécifiques.
(p.75, par exemple) ou contenir des fractions étiquetées.
{
"histogram": [
{
object (Bin)
}
],
"percentiles": {
object (Percentiles)
}
}
ou
{
"fractions": {
object (Fractions)
}
}
Champs | |
---|---|
histogram[] |
Histogramme des expériences utilisateur pour une métrique. L'histogramme comportera au moins un bin et les densités de tous les bins s'additionnent pour atteindre ~1. |
percentiles |
Centiles utiles courants de la métrique. Le type de valeur pour les centiles est identique à celui fourni pour les bins d'histogramme. |
fractions |
Cet objet contient des fractions étiquetées, dont la somme est égale à ~1. Les fractions sont arrondies à quatre décimales. |
Bin
Une bin
est une partie discrète de données s'étendant du début à la fin, ou si aucune fin n'est donnée du début à l'infini positif.
Les valeurs de début et de fin d'un bin sont indiquées dans le type de valeur de la métrique qu'il représente. Par exemple, le First Contentful Paint est mesuré en millisecondes et exposé en tant qu'ents. Par conséquent, ses bins de métriques utiliseront des int32s pour ses types de début et de fin. Toutefois, le décalage de mise en page cumulé est mesuré en nombres décimaux sans unité et est exposé sous la forme d'un encodage décimal sous forme de chaîne. Par conséquent, ses bins de métriques utilisent des chaînes pour son type de valeur.
{
"start": value,
"end": value,
"density": number
}
Champs | |
---|---|
start |
"Start" correspond au début du bin de données. |
end |
"Fin" correspond à la fin du bin de données. Si la valeur end n'est pas renseignée, alors le bin n'a pas de fin et est valide du début à +inf. |
density |
Proportion d'utilisateurs ayant constaté la valeur de cette classe pour la métrique donnée. Les densités sont arrondies à quatre décimales. |
Centiles
Percentiles
contient les valeurs synthétiques d'une métrique à un centile statistique donné. Ils permettent d'estimer la valeur d'une métrique telle qu'elle est vécue par un pourcentage d'utilisateurs par rapport au nombre total d'utilisateurs.
{
"P75": value
}
Champs | |
---|---|
p75 |
75% des chargements de pages ont enregistré une valeur inférieure ou égale à cette valeur pour la métrique donnée. |
Fractions
Fractions
contient des fractions étiquetées dont la somme est égale à ~1. Chaque étiquette décrit un
chargement d'une page d'une manière ou d'une autre. Les métriques représentées de cette manière peuvent donc être considérées
produit des valeurs distinctes au lieu de valeurs numériques, et les fractions expriment
la fréquence de mesure d'une valeur distincte spécifique.
{
"label_1": fraction,
"label_2": fraction,
...
"label_n": fraction
}
Tout comme les valeurs de densité dans les bins d'histogramme, chaque fraction
est un nombre.
0.0 <= value <= 1.0
.Leur somme est donc égale à ~1, 0.
UrlNormalization
Objet représentant les actions de normalisation effectuées pour normaliser une URL afin d'augmenter les chances de réussite de la recherche. Il s'agit de simples modifications automatiques qui sont effectuées lors de la recherche de l'url_pattern
fourni comme ayant échoué. Les actions complexes telles que le suivi de redirections ne sont pas gérées.
{
"originalUrl": string,
"normalizedUrl": string
}
Champs | |
---|---|
originalUrl |
URL demandée à l'origine avant toute action de normalisation |
normalizedUrl |
URL après toute action de normalisation. Il s'agit d'une URL d'expérience utilisateur valide qui pourrait raisonnablement être recherchée. |
Limites de débit
L'API CrUX est limitée à 150 requêtes par minute et par projet Google Cloud, ce qui est sans frais. Vous pouvez consulter cette limite et votre utilisation actuelle dans la console Google Cloud. Ce quota généreux devrait suffire pour la grande majorité des cas d'utilisation. Il n'est pas possible de payer pour augmenter le quota.