Este guia apresenta o endpoint da API History Report do Chrome UX Report (CrUX), que fornece dados de desempenho de série temporal da Web. Esses dados são atualizados toda semana e permitem que você confira cerca de 6 meses de histórico, com 25 pontos de dados espaçados por 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 anteriormente, o que torna essa uma ferramenta poderosa para acompanhar as mudanças na página da Web ao longo do tempo.
Consultar a API CrUX diária
Recapitulando um artigo anterior sobre a API CrUX, confira um resumo dos dados de campo de uma origem específica da seguinte maneira:
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 snapshot inclui valores de densidade de histograma e valores de percentis para um determinado período de coleta 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, mude queryRecord no URL para queryHistoryRecord no comando curl. Você pode usar a mesma chave da 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 valores de densidade de histograma e 75o percentil (p75).
{
"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 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 collectionPeriods correspondente. Por exemplo, a quinta densidade, 0,9183, era a densidade do quinto período de coleta, terminando em 3 de setembro de 2022, e 0,9187 era a densidade no período que terminava na semana seguinte.
Em outras palavras, ao interpretar as últimas entradas de série temporal no exemplo para https://web.dev (link em inglês), 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 que 2.500 ms, 5,27% tiveram valores entre 2.500 ms e 4.000 ms, e 4.000 ms maiores.
Da mesma forma, há uma série temporal para os valores 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 do usuário tiveram uma LCP inferior a 1.377 ms, e 25% das experiências do usuário tiveram uma LCP maior que 1.377 ms.
Embora o exemplo liste somente 6 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 para cada um desses períodos de coleta são os sábados com 7 dias de intervalo, isso abrange 6 meses.
Em qualquer resposta, o comprimento da série temporal para as densidades de agrupamento do histograma e para os valores p75 será exatamente o mesmo que o 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
Além dos dados no nível da origem, a API CrUX History permite acessar dados históricos no nível da página. Antes, os dados no nível da origem estavam disponíveis com o conjunto de dados CrUX no BigQuery (ou o painel CrUX). No entanto, os dados históricos no nível da página só estavam disponíveis se os sites coletassem e armazenassem 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 podem não ter um registro histórico completo. Nesses casos, os dados "ausentes" serão representados por "NaN" para as densidades de histogramTimeseries e null para a percentilesTimeseries. O motivo da diferença é que as densidades do histograma são sempre números, enquanto os percentis podem ser números ou strings (o CLS usa strings, mesmo que se pareçam com números).
Visualizar os dados
Então, você pode se perguntar: por que os dados são formados dessa maneira? Descobriu-se que isso facilita a criação 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, que é definido como lastDate para cada período de coleta.
Aqui está um gráfico para a série temporal da caixa do histograma, conhecida como gráfico de três barras, porque esses histogramas têm três agrupamentos.
O eixo x é definido como o lastDate para cada período de coleta. No entanto, desta vez, o eixo y é a porcentagem de carregamentos de página em um intervalo específico para a métrica INP, mostrada em 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 de três agrupamentos 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 com três barras mostra que, em uma pequena fração dos carregamentos de página, o INP foi ruim. Nos dois, é relativamente fácil inferir que houve uma regressão de desempenho que começou no fim 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. A API CrUX History Colab (fonte) usa Python para fazer chamadas para a API e criar gráficos com os dados.
O Colab permite que você crie gráficos p75 e tri-bin, receba dados em formato tabular e confira o par de solicitações e respostas da API CrUX preenchendo um breve formulário. Não é necessário ser um programador para usar isso, mas você certamente pode examinar o código Python e modificá-lo para algo incrível! Aproveite e não deixe de enviar feedback sobre o que você encontrar.
Você não precisa usar apenas o Colab ou Python. Este é apenas um exemplo de como usar essa nova API. Como um endpoint HTTP baseado em JSON, a API pode ser consultada por qualquer tecnologia.
Conclusão
Antes da introdução do endpoint da API CrUX History, os proprietários de sites não tinham acesso às informações históricas que conseguiam com o CrUX. Os dados mensais no nível da origem estavam disponíveis usando o BigQuery e o painel CrUX, mas os dados semanais e os dados históricos no nível da página não estavam disponíveis. Os proprietários dos 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.
O objetivo do lançamento dessa API CrUX History é permitir que os proprietários de sites entendam melhor as mudanças nas métricas e como uma ferramenta de diagnóstico para quando surgirem problemas. Se você estiver usando a nova API, deixe seu feedback no grupo do Google sobre o Chrome UX Report (Discussões).
Agradecimentos
Imagem principal de Dave Herring no Unsplash (em inglês)