A API CrUX oferece acesso de baixa latência a dados agregados de experiência do usuário real em granularidade de página e origem.
Caso de uso comum
A API CrUX permite a consulta de métricas de experiência do usuário para um URI específico, como "Receber métricas da origem https://example.com
".
Chave de API do CrUX
O uso da API CrUX requer uma chave de API do Google Cloud provisionada para uso do Chrome UX Report API
.
Como receber e usar uma chave de API
Acessar uma chaveOu crie uma na página Credenciais.
Depois que você tiver uma chave de API, seu aplicativo poderá anexar o parâmetro de consulta key=yourAPIKey
a todos os URLs de solicitação.
É seguro incorporar a chave de API a URLs. Não é necessário codificá-la.
Confira Exemplos de consultas.
Modelo de dados
Esta seção detalha a estrutura de dados em solicitações e respostas.
Gravar
Uma informação discreta sobre uma página ou um site. Um registro pode ter dados específicos para um identificador e para uma combinação específica de dimensões. Um registro pode conter dados para uma ou mais métricas.
Identificadores
Os identificadores especificam quais registros devem ser consultados. No CrUX, esses identificadores são páginas da Web e sites.
Origem
Quando o identificador é uma origem, todos os dados presentes em todas as páginas dessa origem são agregados. Por exemplo, digamos que a origem http://www.example.com
tenha páginas conforme disposto por este sitemap:
http://www.example.com/
http://www.example.com/foo.html
http://www.example.com/bar.html
Isso significa que, ao consultar o Chrome UX Report com a origem definida como http://www.example.com
, os dados de http://www.example.com/
, http://www.example.com/foo.html
e http://www.example.com/bar.html
seriam retornados, agregados, porque essas são todas as páginas dessa origem.
URLs
Quando o identificador for um URL, somente os dados desse URL específico serão retornados. Procurando novamente o sitemap de origem http://www.example.com
:
http://www.example.com/
http://www.example.com/foo.html
http://www.example.com/bar.html
Se o identificador for definido como URL com o valor de http://www.example.com/foo.html
, apenas os dados dessa página serão retornados.
Dimensões
As dimensões identificam um grupo específico de dados ao qual um registro está sendo agregado. Por exemplo, um formato PHONE
indica que o registro contém informações sobre carregamentos que ocorreram em um dispositivo móvel. Cada dimensão terá um determinado número de valores, e a ausência de especificação faz com que a dimensão seja agregada a todos os valores. Por exemplo, não especificar nenhum formato indica que o registro contém informações sobre carregamentos que ocorreram em qualquer formato.
Formato
A classe de dispositivo que o usuário final utilizou para navegar até a página. Essa é uma classe geral de dispositivo dividida em PHONE
, TABLET
e DESKTOP
.
Tipo de conexão eficaz
O Tipo de conexão efetiva é a qualidade de conexão estimada do dispositivo ao navegar até a página. Essa é uma classe geral dividida em offline
, slow-2G
, 2G
, 3G
e 4G
.
Métrica
Informamos métricas como agregações estatísticas, em histogramas, percentis e frações.
Valores de ponto flutuante são arredondados para quatro casas decimais. Observe que as métricas cumulative_layout_shift
são codificadas duplas como uma string, portanto, não são consideradas flutuações e são informadas como duas casas decimais na string.
Histograma
Quando as métricas são expressas em um histograma, mostramos as porcentagens de carregamentos de página que se enquadram intervalos específicos dessa métrica.
Um histograma de três barras para uma métrica de exemplo fica assim:
{
"histogram": [
{
"start": 0,
"end": 1000,
"density": 0.3818
},
{
"start": 1000,
"end": 3000,
"density": 0.4991
},
{
"start": 3000,
"density": 0.1192
}
]
}
Esses dados indicam que, para 38,18% dos carregamentos de página, a métrica de exemplo foi medida entre 0 ms e 1.000 ms. As unidades da métrica não estão contidas neste histograma, Neste caso, vamos considerar milissegundos.
Além disso, 49,91% dos carregamentos de página tiveram um valor de métrica entre 1.000 ms e 3.000 ms e 11,92% teve um valor maior que 3.000 ms.
Percentis
As métricas também podem conter percentis que podem ser úteis para análises adicionais. Informamos valores específicos de métricas no percentil determinado para essa métrica. Eles são baseados no conjunto completo de dados disponíveis e não nos dados agrupados em classes. portanto, não correspondem necessariamente a um percentil interpolado que é baseado no histograma final por classes.
{
"percentiles": {
"p75": 2063
}
}
Neste exemplo, pelo menos 75% dos carregamentos de página foram medidos com um valor de métrica <= 2063
.
Frações
As frações indicam as porcentagens de carregamentos de página que podem ser marcadas de uma maneira específica. Nesse caso, os valores das métricas são esses rótulos.
Por exemplo, a métrica form_factors
consiste em um objeto fractions
que lista o detalhamento dos formatos (ou dispositivos) abrangidos pela consulta especificada:
"form_factors": {
"fractions": {
"desktop": 0.0377,
"tablet": 0.0288,
"phone": 0.9335
}
}
Nesse caso, 3,77% dos carregamentos de página foram medidos em um computador, 2,88% em um tablet e 93,35% em um smartphone, totalizando 100%.
Tipos de valor de métrica
Nome da métrica da API CrUX | Tipo de dados | Unidades métricas | Agregações estatísticas | Documentação |
---|---|---|---|---|
cumulative_layout_shift |
duas casas decimais codificadas duas vezes como string | sem unidade | histograma com três agrupamentos, percentis com p75 | cls |
first_contentful_paint |
int | milésimos de segundo | histograma com três agrupamentos, percentis com p75 | fcp |
interaction_to_next_paint |
int | milésimos de segundo | histograma com três agrupamentos, percentis com p75 | inp |
largest_contentful_paint |
int | milésimos de segundo | histograma com três agrupamentos, percentis com p75 | lcp |
experimental_time_to_first_byte |
int | milésimos de segundo | histograma com três agrupamentos, percentis com p75 | ttfb |
form_factors |
Casa decimal com quatro casas decimais | porcentagem | mapeamento do formato para fração | formatos |
navigation_types |
Número decimais de quatro casas | porcentagem | mapeamento do tipo de navegação para fração | tipos de navegação |
round_trip_time |
int | milésimos de segundo | percentis com p75 | rtt |
Mapeamento de nomes de métricas do BigQuery
Nome da métrica da API CrUX | Nome da métrica do 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 |
Período de coleta
Desde outubro de 2022, a API CrUX contém um objeto collectionPeriod
com os campos firstDate
e endDate
que representam as datas de início e término da janela de agregação. Exemplo:
"collectionPeriod": {
"firstDate": {
"year": 2022,
"month": 9,
"day": 12
},
"lastDate": {
"year": 2022,
"month": 10,
"day": 9
}
}
Isso permite uma melhor compreensão dos dados e se eles já foram atualizados para o dia em questão ou se estão retornando os mesmos dados de ontem.
A API CrUX está aproximadamente dois dias atrás da data de hoje, porque espera os dados completos do dia, e há um tempo de processamento envolvido antes de ser disponibilizado na API. O fuso horário usado é o Horário padrão do Pacífico (PST, na sigla em inglês), sem alterações para o horário de verão.
Exemplos de consultas
As consultas são enviadas como objetos JSON usando uma solicitação POST para https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=[YOUR_API_KEY]"
com os dados da consulta na forma de um objeto JSON no corpo do POST:
{
"origin": "https://example.com",
"formFactor": "PHONE",
"metrics": [
"largest_contentful_paint",
"experimental_time_to_first_byte"
]
}
Por exemplo, isso pode ser chamado em curl
com a seguinte linha de comando (substituindo API_KEY
pela sua chave):
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"]}'
Os dados no nível da página estão disponíveis pela API transmitindo uma propriedade url
na consulta, em vez de origin
:
{
"url": "https://example.com/page",
"formFactor": "PHONE",
"metrics": [
"largest_contentful_paint",
"experimental_time_to_first_byte"
]
}
Se a propriedade metrics
não for definida, todas as métricas disponíveis serão retornadas:
cumulative_layout_shift
first_contentful_paint
first_input_delay
(descontinuado)interaction_to_next_paint
largest_contentful_paint
experimental_time_to_first_byte
navigation_types
form_factors
(somente informado se nenhumformFactor
for especificado na solicitação)
Se nenhum valor formFactor
for fornecido, os valores serão agregados em todos os formatos.
Consulte Como usar a API Chrome UX Report para ver mais exemplos de consulta.
Pipeline de dados
O conjunto de dados CrUX é processado por um pipeline para consolidar, agregar e filtrar os dados antes de serem disponibilizados usando a API.
A média contínua
Os dados do Chrome UX Report são uma média contínua de 28 dias de métricas agregadas. Isso significa que os dados apresentados no Chrome UX Report são, na verdade, os dados dos últimos 28 dias agregados.
Esse processo é parecido com a forma como o conjunto de dados do CrUX no BigQuery agrega relatórios mensais.
Atualizações diárias
Os dados são atualizados diariamente por volta das 04h UTC. Não há contrato de nível de serviço para horários de atualização. ele é executado todos os dias da melhor maneira possível.
Esquema
Há um único endpoint para a API CrUX que aceita solicitações HTTP POST
. A API retorna um record
que contém um ou mais metrics
correspondentes aos dados de desempenho sobre a origem ou página solicitada.
Solicitação HTTP
POST https://chromeuxreport.googleapis.com/v1/records:queryRecord
O URL usa a sintaxe de transcodificação gRPC.
Corpo da solicitação
O corpo da solicitação precisa conter dados com a seguinte estrutura:
{
"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.
}
Campos | |
---|---|
effectiveConnectionType |
O tipo de conexão vigente é uma dimensão de consulta que especifica a classe de rede vigente a que os dados do registro devem pertencer. Esse campo usa os valores Observação: se nenhum tipo de conexão efetiva for especificado, será retornado um registro especial com dados agregados em todos os tipos de conexão efetivas. |
formFactor |
O formato é uma dimensão de consulta que especifica a classe do dispositivo a que os dados do registro devem pertencer. Esse campo usa os valores Observação: se nenhum formato for especificado, será retornado um registro especial com dados agregados de todos os formatos. |
metrics[] |
As métricas que devem ser incluídas na resposta. Se nenhuma for especificada, todas as métricas encontradas serão retornadas. Valores permitidos: |
Campo de união url_ . O url_pattern é o identificador principal de uma pesquisa de registro. Pode ser apenas uma das seguintes opções: |
|
origin |
A "origem" do Por exemplo: |
url |
O Por exemplo: |
Por exemplo, para solicitar os maiores valores de Contentful Paint para computador para a página inicial da documentação do desenvolvedor do Chrome:
{
"url": "https://developer.chrome.com/docs/",
"formFactor": "DESKTOP",
"metrics": [
"largest_contentful_paint"
]
}
Corpo da resposta
As solicitações bem-sucedidas retornam respostas com um objeto record
e urlNormalizationDetails
na seguinte estrutura:
{
"record": {
"key": {
object (Key)
},
"metrics": [
string: {
object (Metric)
}
]
},
"urlNormalizationDetails": {
object (UrlNormalization)
}
}
Por exemplo, a resposta para o corpo da solicitação na solicitação anterior poderia ser:
{
"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
}
}
}
}
Chave
Key
define todas as dimensões que identificam esse registro como exclusivo.
{
"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.
}
Campos | |
---|---|
formFactor |
O formato é a classe de dispositivo que todos os usuários usaram para acessar o site nesse registro. Se o formato não for especificado, os dados agregados de todos os formatos serão retornados. |
effectiveConnectionType |
O tipo de conexão efetiva é a classe de conexão geral que todos os usuários tiveram neste registro. Esse campo usa os valores ["offline", "slow-2G", "2G", "3G", "4G"] conforme especificado em: https://wicg.github.io/netinfo/#effective-connection-types Se o tipo de conexão efetiva não for especificado, serão retornados os dados agregados de todos os tipos de conexão efetiva. |
Campo de união url_ . O padrão de URL é o URL ao qual o registro se aplica. url_ pode ser apenas de um dos tipos a seguir: |
|
origin |
Observação: ao especificar um |
url |
Observação: ao especificar um |
Métricas
Um metric
é um conjunto de dados agregados de experiência do usuário para uma única métrica de desempenho da Web, como a First Contentful Paint.
Ela pode conter um histograma resumido do uso real do Chrome como uma série de bins
, dados de percentis específicos.
(como o p75) ou pode conter frações rotuladas.
{
"histogram": [
{
object (Bin)
}
],
"percentiles": {
object (Percentiles)
}
}
ou
{
"fractions": {
object (Fractions)
}
}
Campos | |
---|---|
histogram[] |
O histograma das experiências do usuário de uma métrica. O histograma terá pelo menos um agrupamento e as densidades de todas as barras serão somadas a ~1. |
percentiles |
Percentis úteis comuns da métrica. O tipo de valor para os percentis será o mesmo que os tipos de valor fornecidos para os agrupamentos do histograma. |
fractions |
Esse objeto contém frações rotuladas, que somam ~1. As frações são arredondadas para quatro casas decimais. |
Agrupamento
Um bin
é uma parte discreta de dados que se estende do início ao fim ou, se nenhum fim for fornecido, do início ao infinito positivo.
Os valores inicial e final de um agrupamento são fornecidos no tipo de valor da métrica que ele representa. Por exemplo, a First Contentful Paint é medida em milissegundos e exposta como ints. Portanto, os agrupamentos de métricas vão usar int32s para os tipos inicial e final. No entanto, a mudança cumulativa do layout é medida em decimais sem unidade e é exposta como um decimal codificado como uma string. Portanto, os intervalos de métricas usam strings para o tipo de valor.
{
"start": value,
"end": value,
"density": number
}
Campos | |
---|---|
start |
Start é o início do compartimento de dados. |
end |
Fim é o fim do compartimento de dados. Se "end" não for preenchido, o intervalo não terá fim e será válido do início até +inf. |
density |
A proporção de usuários que experimentou o valor desse agrupamento para a métrica especificada. As densidades são arredondadas para quatro casas decimais. |
Percentis
Percentiles
contém valores sintéticos de uma métrica em um determinado percentil estatístico. Elas são usadas para estimar o valor de uma métrica conforme a experiência por uma porcentagem de usuários em relação ao número total de usuários.
{
"P75": value
}
Campos | |
---|---|
p75 |
75% dos carregamentos de página tiveram a métrica especificada igual ou menor que esse valor. |
Frações
Fractions
contém frações rotuladas que somam aproximadamente 1. Cada rótulo descreve um
carregamento da página de alguma forma. Assim, as métricas representadas dessa maneira podem ser consideradas como
produzir valores distintos em vez de numéricos, e as frações expressam
a frequência com que um determinado valor
distinto foi medido.
{
"label_1": fraction,
"label_2": fraction,
...
"label_n": fraction
}
Assim como os valores de densidade nas barras do histograma, cada fraction
é um número
0.0 <= value <= 1.0
, e o total deles é aproximadamente 1,0.
UrlNormalization
Objeto que representa as ações de normalização realizadas para normalizar um URL e aumentar as chances de uma pesquisa bem-sucedida. Essas são mudanças automatizadas simples que são feitas quando a pesquisa do url_pattern
fornecido falha. Ações complexas, como seguir redirecionamentos, não são tratadas.
{
"originalUrl": string,
"normalizedUrl": string
}
Campos | |
---|---|
originalUrl |
O URL original solicitado antes de qualquer ação de normalização. |
normalizedUrl |
O URL após qualquer ação de normalização. Esse é um URL de experiência do usuário válido que poderia ser procurado. |
Limites de taxas
A API CrUX é limitada a 150 consultas por minuto por projeto do Google Cloud, oferecida sem custo financeiro. Esse limite e seu uso atual podem ser consultados no Console do Google Cloud. Essa cota generosa deve ser suficiente para a grande maioria dos casos de uso e não é possível pagar por uma cota maior.