Este guia apresenta o endpoint da API History Report (CrUX) do Chrome UX Report, que mostra uma série temporal de dados de desempenho na Web. Esses dados são atualizados semanalmente e mostram cerca de seis meses de histórico, 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 você pode conferir rapidamente os dados mais recentes e o que aconteceu antes, o que torna essa ferramenta uma ferramenta poderosa para acompanhar as mudanças na página da Web ao longo do tempo.
Consultar a API CrUX diária
Para recapitular um artigo anterior sobre a API CrUX, você pode acessar 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 }
}
}
}
Este resumo inclui valores de densidade do histograma e valores percentuais 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 CrUX History
Para chamar o endpoint do histórico, altere queryRecord no URL para queryHistoryRecord no comando curl. Use a mesma chave de API 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"}'
O formato 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 75o 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 para o bucket de 0 a 2.500 ms da métrica Largest Contentful Paint (LCP) é [0.9190, 0.9203, 0.9194, 0.9195, 0.9183, 0.9187].. Cada uma dessas densidades foi observada durante a entrada collectionPeriods correspondente. 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 no período que termina na semana seguinte.
Em outras palavras, interpretando as últimas entradas de série temporal no exemplo https://web.dev, descobrimos que de 14 de agosto de 2022 a 10 de setembro de 2022, 91,87% dos carregamentos de página tinham valores de LCP menores do que 2.500 ms, 5,27% tinham valores entre 2.500 ms e 4.000 ms e 4.000 ms
Da mesma forma, há uma série temporal para os valores p75: a LCP p75 de 14 de agosto de 2022 a 10 de setembro de 2022 era 1377. Isso significa que, nesse período de coleta, 75% das experiências do usuário tiveram uma LCP de menos de 1.377 ms, e 25% das experiências do usuário tiveram uma LCP maior que 1.377 ms.
Embora o exemplo liste apenas 6 entradas de série temporal e períodos de coleta, as respostas da API fornecem 25 entradas de série temporal; já que as datas de término para cada um desses períodos de coleta são aos sábados, com sete dias de intervalo, isso abrange seis meses.
Em qualquer resposta, o tamanho da série temporal para as densidades de agrupamento do histograma e para os valores p75 será exatamente igual ao comprimento da matriz no campo collectionPeriods: há uma correspondência de um para um com base no índice dessas matrizes.
Consultar dados no nível da página
Assim como os dados da origem, a API CrUX History permite o acesso a dados históricos no nível da página. Antes, os dados no nível da origem estavam disponíveis usando o conjunto de dados CrUX no BigQuery (ou o painel CrUX), mas os dados históricos no nível da página só estavam disponíveis se os sites coletassem e armazenassem os dados por conta própria. 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 do restante do CrUX. Portanto, é possível que as páginas em particular não tenham um registro histórico completo. Nesses casos, os elementos "ausentes" os dados serão representados por "NaN" para as densidades de histogramTimeseries e null para as percentilesTimeseries. A razão para a diferença é que as densidades do 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 têm esse formato? Descobrimos que isso facilita a plotagem de gráficos. Por exemplo, este é um gráfico para os valores p75 de Interaction To Next Paint (INP) para https://web.dev:
Neste gráfico de linhas, cada valor no eixo y é um valor p75 da série temporal p75s, e o eixo x é o tempo, configurado como lastDate para cada período de coleta.
Aqui está um gráfico para a série temporal de agrupamentos de histogramas, conhecida como gráfico tri-bin, porque esses histogramas têm três agrupamentos.
O eixo X é definido como lastDate para cada período de coleta. Desta vez, porém, o eixo y é a porcentagem de carregamentos de página em um intervalo específico da métrica INP, mostrada por um gráfico de barras empilhadas. O gráfico p75 oferece 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 tri-bin 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 tinha valores de INP quase aceitáveis durante o período de observação, o gráfico tri-bin mostra que, para uma pequena fração dos 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 por conta própria, criamos o Colab de exemplo. Um Colab, ou "Colaboratory", permite escrever e executar Python em seu navegador. O CrUX History API Colab (fonte) usa Python para fazer chamadas à API e criar gráficos dos dados.
Com este Colab, é possível criar gráficos P75 e gráficos tri-bin, receber dados em tabelas e conferir o par de solicitação e resposta da API CrUX ao preencher um breve formulário. Não é necessário ser um programador para usar isso, mas você certamente pode analisar o código Python e transformá-lo em algo incrível! Aproveite e não hesite em enviar feedback sobre o que você encontrar!
Claro que você não está limitado ao Colab ou Python, e esse é apenas um exemplo de como usar a nova API. Por ser um endpoint HTTP baseado em JSON, a API pode ser consultada em qualquer tecnologia.
Conclusão
Antes da introdução do endpoint da API CrUX History, os proprietários de sites tinham acesso limitado às informações históricas que podiam receber do CrUX. Os dados mensais no nível da origem estavam disponíveis no BigQuery e no painel do CrUX, mas os dados semanais e os históricos no nível da página não estavam disponíveis. Os proprietários dos sites podiam registrar esses dados por conta própria usando a API diária, mas muitas vezes isso só era necessário após uma regressão nas métricas.
Com o lançamento dessa API CrUX History, esperamos que os proprietários de sites entendam melhor as mudanças nas métricas do site e como uma ferramenta de diagnóstico para quando surgirem problemas. Se você estiver usando a nova API, envie seu feedback no Grupo do Google do Chrome UX Report (Discussões) no Google.
Agradecimentos
Imagem principal de Dave Herring no Unsplash