Este guia apresenta o endpoint da API History do Chrome UX Report (CrUX), que fornece séries temporais de dados de desempenho da Web. Esses dados são atualizados semanalmente e permitem que você acesse um histórico de cerca de seis meses, com 25 pontos de dados espaçados por uma semana.
Quando usado com as atualizações diárias do endpoint original da API CrUX, agora é possível conferir rapidamente os dados mais recentes e o que aconteceu anteriormente, tornando essa uma ferramenta poderosa para conferir as mudanças na página da Web ao longo do tempo.
Testar a API nesta página
Consultar a API diária do CrUX
Para recapitular um artigo anterior sobre a API CrUX, é possível conferir um resumo dos dados de campo de uma origem específica desta forma:
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"}'
{
"record": {
"key": {
"origin": "https://web.dev"
},
"metrics": {
"largest_contentful_paint": {
"histogram": [{
"start": 0, "end": 2500, "density": 0.9192
}, {
"start": 2500, "end": 4000, "density": 0.0513
}, {
"start": 4000, "density": 0.0294
}],
"percentiles": {
"p75": 1303
}
}
// ...
},
"collectionPeriod": {
"firstDate": { "year": 2022, "month": 12, "day": 27 },
"lastDate": { "year": 2023, "month": 1, "day": 23 }
}
}
}
Esse resumo inclui valores de densidade de histograma e percentis para um período de coleta específico de 28 dias, neste caso, de 27 de dezembro de 2022 a 23 de janeiro de 2023.
Consultar a API History do CrUX
Para chamar o endpoint de histórico, mude queryRecord no URL para queryHistoryRecord no comando curl. Use a mesma chave de API do CRUX da chamada anterior.
API_KEY="[YOUR_API_KEY]"
curl "https://chromeuxreport.googleapis.com/v1/records:queryHistoryRecord?key=$API_KEY" \
--header 'Content-Type: application/json' \
--data '{"origin": "https://web.dev"}'
A forma geral de uma resposta é semelhante, mas há muito mais dados. Em vez de um único ponto de dados, agora há séries temporais para os campos que contêm o 75º percentil (p75) e os valores de densidade do histograma.
{
"record": {
"key": {
"origin": "https://web.dev"
},
"metrics": {
"largest_contentful_paint": {
"histogramTimeseries": [{
"start": 0, "end": 2500, "densities": [
0.9190, 0.9203, 0.9194, 0.9195, 0.9183, 0.9187
]
}, {
"start": 2500, "end": 4000, "densities": [
0.0521, 0.0513, 0.0518, 0.0518, 0.0526, 0.0527
]
}, {
"start": 4000, "densities": [
0.0288, 0.0282, 0.0286, 0.0285, 0.0290, 0.0285
]
}
],
"percentilesTimeseries": {
"p75s": [
1362, 1352, 1344, 1356, 1366, 1377
]
}
}
// ...
},
"collectionPeriods": [{
"firstDate": { "year": 2022, "month": 7, "day": 10 },
"lastDate": { "year": 2022, "month": 8, "day": 6 }
}, {
"firstDate": { "year": 2022, "month": 7, "day": 17 },
"lastDate": { "year": 2022, "month": 8, "day": 13 }
}, {
"firstDate": { "year": 2022, "month": 7, "day": 24 },
"lastDate": { "year": 2022, "month": 8, "day": 20 }
}, {
"firstDate": { "year": 2022, "month": 7, "day": 31 },
"lastDate": { "year": 2022, "month": 8, "day": 27 }
}, {
"firstDate": { "year": 2022, "month": 8, "day": 7 },
"lastDate": { "year": 2022, "month": 9, "day": 3 }
}, {
"firstDate": { "year": 2022, "month": 8, "day": 14 },
"lastDate": { "year": 2022, "month": 9, "day": 10 }
}
]
}
}
Neste exemplo, a série temporal densities do intervalo de 0 a 2.500 ms da métrica Maior exibição de conteúdo (LCP) é [0.9190, 0.9203, 0.9194, 0.9195, 0.9183, 0.9187].. Cada uma dessas densidades foi observada durante a entrada correspondente de collectionPeriods. Por exemplo, a quinta densidade, 0,9183, foi a densidade do quinto período de coleta, que terminou em 3 de setembro de 2022, e 0,9187 foi a densidade do período que terminou na semana seguinte.
Em outras palavras, interpretando as últimas entradas de série temporal no exemplo de https://web.dev, foi descoberto que, de 14 de agosto de 2022 a 10 de setembro de 2022, 91,87% dos carregamentos de página tiveram valores de LCP menores que 2.500 ms, 5,27% tiveram valores entre 2.500 e 4.000 ms e 2,85% tiveram valores maiores que 4.000 ms.
Da mesma forma, há uma série temporal para os valores de p75: o LCP p75 de 14 de agosto de 2022 até 10 de setembro de 2022 foi 1377. Isso significa que, para esse período de coleta, 75% das experiências dos usuários tiveram uma LCP de menos de 1377 ms, e 25% tiveram uma LCP maior que 1377 ms.
Embora o exemplo liste apenas seis entradas de série temporal e períodos de coleta, as respostas da API fornecem 25 entradas de série temporal. Como as datas de término de cada um desses períodos de coleta são sábados com uma diferença de sete dias, isso abrange seis meses.
Em qualquer resposta, o comprimento da série temporal das densidades de bin de histograma e dos valores de p75 será exatamente igual ao comprimento da matriz no campo collectionPeriods: há uma correspondência um a um com base no índice dessas matrizes.
Consultar dados no nível da página
Além dos dados no nível da origem, a API CrUX History permite o acesso a dados históricos no nível da página. Embora os dados de origem estivessem disponíveis anteriormente usando o conjunto de dados do Crux no BigQuery (ou usando o Painel do Crux), os dados históricos no nível da página só estavam disponíveis se os sites coletavam e armazenavam os dados. A nova API agora desbloqueia esses dados históricos no nível da página.
Os dados no nível da página podem ser consultados da mesma maneira, mas usando url em vez de origin no payload:
API_KEY="[YOUR_API_KEY]"
curl "https://chromeuxreport.googleapis.com/v1/records:queryHistoryRecord?key=$API_KEY" \
--header 'Content-Type: application/json' \
--data '{"url": "https://web.dev/blog/"}'
Os dados históricos no nível da página (e da origem) estão sujeitos aos mesmos requisitos de qualificação que o restante do CrUX. Portanto, as páginas em particular podem não ter um registro histórico completo. Nesses casos, os dados "ausentes" serão representados por "NaN" para as densidades histogramTimeseries e null para a percentilesTimeseries. A razão para a diferença é que as densidades de histograma são sempre números, enquanto os percentis podem ser números ou strings (a CLS usa strings, mesmo que pareçam números).
Visualizar os dados
Você pode estar se perguntando por que os dados são moldados dessa maneira. Isso facilita a criação de gráficos. Por exemplo, aqui está um gráfico dos valores de p75 para Interaction To Next Paint (INP) em https://web.dev:
Nesse gráfico de linhas, cada valor no eixo y é um valor de p75 da série temporal p75s, e o eixo x é o tempo, que é configurado como lastDate para cada período de coleta.
Este é um gráfico da série temporal de agrupamento de histogramas, conhecido como gráfico de três agrupamentos, porque esses histogramas têm três agrupamentos.
O eixo x é configurado como lastDate para cada período de coleta. No entanto, desta vez, o eixo y é a porcentagem de carregamentos de página que se enquadram em um intervalo específico para a métrica INP, mostrada em um gráfico de barras empilhadas. O gráfico p75 fornece uma visão geral rápida e, em um único gráfico, é relativamente fácil adicionar várias métricas ou mostrar linhas para PHONE e DESKTOP. O gráfico de três intervalos dá uma ideia da distribuição dos valores de métricas medidos durante cada período de coleta.
Por exemplo, embora o gráfico p75 sugira que https://web.dev teve valores de INP quase aceitáveis durante o período de observação, o gráfico de três intervalos mostra que, para uma pequena fração de carregamentos de página, o INP foi ruim. Em ambos os gráficos, é relativamente fácil inferir que houve uma regressão de desempenho que começou no final de outubro e foi corrigida em meados de novembro.
Para gerar esses gráficos, criamos um exemplo de Colab. O Colab, ou "Colaboratory", permite escrever e executar Python no navegador. O Colab da API History do CRUX (fonte) usa Python para fazer chamadas para a API e representar os dados em um gráfico.
Neste Colab, você pode fazer gráficos p75, tridimensionais, receber dados em formato tabular e conferir o par de solicitação e resposta da API CrUX preenchendo um breve formulário. Você não precisa ser um programador para usar esse recurso, mas pode analisar o código Python e modificá-lo para algo incrível. Aproveite e não deixe de enviar feedback sobre o que você encontrar.
Claro, você não está limitado ao Colab ou ao Python, e este é apenas um exemplo de como usar essa nova API. Como um endpoint HTTP baseado em JSON, a API pode ser consultada em qualquer tecnologia.
Conclusão
Antes da introdução do endpoint da API History do CrUX, os proprietários de sites tinham acesso limitado às informações históricas do CrUX. Os dados mensais no nível da origem estavam disponíveis usando o BigQuery e o painel do CrUX, mas os dados semanais e históricos no nível da página não estavam disponíveis. Os proprietários de sites podiam registrar esses dados usando a API diária, mas, muitas vezes, a necessidade disso só era descoberta após uma regressão nas métricas.
A introdução dessa API de histórico do CrUX permite que os proprietários de sites entendam melhor as métricas do site em mudança e também serve como uma ferramenta de diagnóstico para quando surgirem problemas. Se você estiver usando a nova API, envie seu feedback no grupo do Google Chrome UX Report (Discussões).
Agradecimentos
Imagem principal de Dave Herring no Unsplash