Aprenda a usar a API Chrome UX Report para ter acesso a dados de experiência real do usuário em milhões de sites.
O conjunto de dados do Chrome UX Report (CrUX, na sigla em inglês) representa a experiência real dos usuários do Chrome em destinos comuns na Web. Desde 2017, quando o conjunto de dados consultáveis foi lançado pela primeira vez no BigQuery, os dados de campo do CrUX foram integrados às ferramentas para desenvolvedores, como o PageSpeed Insights, o Painel do CrUX e o Relatório de Core Web Vitals do Search Console, permitindo que os desenvolvedores meçam e monitorem as experiências dos usuários reais. A parte que estava faltando todo esse tempo foi uma ferramenta que fornece acesso sem custo financeiro e RESTful aos dados CrUX de forma programática. Para ajudar a preencher essa lacuna, estamos felizes em anunciar o lançamento de uma nova API Chrome UX Report.
Essa API foi criada com o objetivo de oferecer aos desenvolvedores acesso simples, rápido e abrangente aos dados do CrUX. A API CrUX só informa dados de experiência do usuário em campo, ao contrário da API PageSpeed Insights atual, que também informa dados do laboratório das auditorias de desempenho do Lighthouse. A API CrUX é simplificada e pode exibir rapidamente os dados de experiência do usuário, o que a torna ideal para aplicativos de auditoria em tempo real.
Para garantir que os desenvolvedores tenham acesso a todas as métricas mais importantes, as Core Web Vitals, a API CrUX audita e monitora Largest Contentful Paint (LCP), First Input Delay (FID) e Cumulative Layout Shift (CLS) no nível da origem e do URL.
Vamos conferir como usá-lo.
Consultar dados de origem
As origens no conjunto de dados CrUX abrangem todas as experiências no nível da página. O exemplo a seguir demonstra como consultar a API CrUX para dados de experiência do usuário de uma origem usando cURL na linha de comando.
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"}'
O comando curl
é composto de três partes:
- O endpoint de URL da API, incluindo a chave de API privada do autor da chamada.
- O cabeçalho
Content-Type: application/json
, indicando que o corpo da solicitação contém JSON. - O corpo da solicitação codificado em JSON, especificando a origem
https://web.dev
.
Para fazer o mesmo em JavaScript, use o utilitário CrUXApiUtil
,
que faz a chamada de API e retorna a resposta decodificada. Confira também nossa variante do GitHub
para mais recursos, incluindo histórico e suporte em lote).
const CrUXApiUtil = {};
// Get your CrUX API key at https://goo.gle/crux-api-key.
CrUXApiUtil.API_KEY = '[YOUR_API_KEY]';
CrUXApiUtil.API_ENDPOINT = `https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=${CrUXApiUtil.API_KEY}`;
CrUXApiUtil.query = function (requestBody) {
if (CrUXApiUtil.API_KEY == '[YOUR_API_KEY]') {
throw 'Replace "YOUR_API_KEY" with your private CrUX API key. Get a key at https://goo.gle/crux-api-key.';
}
return fetch(CrUXApiUtil.API_ENDPOINT, {
method: 'POST',
body: JSON.stringify(requestBody)
}).then(response => response.json()).then(response => {
if (response.error) {
return Promise.reject(response);
}
return response;
});
};
Substitua [YOUR_API_KEY]
pela chave. Em seguida, chame a função CrUXApiUtil.query
e transmita o objeto do corpo da solicitação.
CrUXApiUtil.query({
origin: 'https://web.dev'
}).then(response => {
console.log(response);
}).catch(response => {
console.error(response);
});
Se houver dados para essa origem, a resposta da API será um objeto codificado em JSON contendo metrics que representa a distribuição das experiências do usuário. As métricas de distribuição são barras e percentis de histograma.
{
"record": {
"key": {
"origin": "https://web.dev"
},
"metrics": {
"largest_contentful_paint": {
"histogram": [
{
"start": 0,
"end": 2500,
"density": 0.7925068547983514
},
{
"start": 2500,
"end": 4000,
"density": 0.1317422195536863
},
{
"start": 4000,
"density": 0.07575092564795324
}
],
"percentiles": {
"p75": 2216
}
},
// ...
}
}
}
As propriedades start
e end
do objeto histogram
representam o intervalo de valores que os usuários veem em determinada métrica. A propriedade density
representa a proporção de experiências do usuário nesse intervalo. Neste exemplo, 79% das experiências do usuário de LCP em todas as páginas web.dev ficam abaixo de 2.500 milissegundos, que é o nível "bom" Limite de LCP. O valor percentiles.p75
significa que 75% das experiências do usuário nesta distribuição são inferiores a 2.216 milissegundos. Saiba mais sobre a estrutura da resposta na documentação do corpo da resposta.
Erros
Quando a API CrUX não tem dados para uma determinada origem, ela responde com uma mensagem de erro codificada em JSON:
{
"error": {
"code": 404,
"message": "chrome ux report data not found",
"status": "NOT_FOUND"
}
}
Para depurar esse erro, primeiro verifique se a origem solicitada é publicamente navegável. Para testar isso, insira a origem na barra de endereço do seu navegador e compare-a com o URL final após os redirecionamentos. Problemas comuns incluem adicionar ou omitir desnecessariamente o subdomínio e usar o protocolo HTTP errado.
{"origin": "http://www.web.dev"}
Essa origem inclui incorretamente o protocolo http://
e o subdomínio www.
.
{"origin": "https://web.dev"}
Esta origem é publicamente navegável.
Se a origem solicitada for a versão navegável, esse erro também poderá ocorrer se a origem tiver um número insuficiente de amostras. Todas as origens e URLs incluídos no conjunto de dados precisam ter um número suficiente de amostras para anonimizar usuários individuais. Além disso, as origens e os URLs precisam ser indexáveis publicamente. Consulte a metodologia CrUX para saber mais sobre como os sites são incluídos no conjunto de dados.
Dados do URL de consulta
Você aprendeu a consultar a API CrUX para saber a experiência geral do usuário em uma origem. Para restringir os resultados a uma página específica, use o parâmetro de solicitação url
.
API_KEY="[YOUR_API_KEY]"
curl "https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=$API_KEY" \
--header 'Content-Type: application/json' \
--data '{"url": "https://web.dev/fast/"}'
Esse comando cURL é semelhante ao exemplo de origem, mas o corpo da solicitação usa o parâmetro url
para especificar a página a ser pesquisada.
Para consultar dados de URL da API CrUX em JavaScript, chame a função CrUXApiUtil.query
usando o parâmetro url
no corpo da solicitação.
CrUXApiUtil.query({
url: 'https://web.dev/fast/'
}).then(response => {
console.log(response);
}).catch(response => {
console.error(response);
});
Se os dados desse URL existirem no conjunto de dados CrUX, a API retornará uma resposta codificada em JSON. Por exemplo:
{
"record": {
"key": {
"url": "https://web.dev/fast/"
},
"metrics": {
"largest_contentful_paint": {
"histogram": [
{
"start": 0,
"end": 2500,
"density": 0.8477304539092148
},
{
"start": 2500,
"end": 4000,
"density": 0.08988202359528057
},
{
"start": 4000,
"density": 0.062387522495501155
}
],
"percentiles": {
"p75": 1947
}
},
// ...
}
}
}
De acordo com a condição, os resultados mostram que https://web.dev/fast/
tem 85% de "bom" Experiências de LCP e um 75o percentil de 1.947 milissegundos, um pouco melhor do que a distribuição na origem.
Normalização de URL
A API CrUX pode normalizar os URLs solicitados para corresponder melhor à lista de URLs conhecidos. Por exemplo, consultar o URL https://web.dev/fast/#measure-performance-in-the-field
resultará em dados de https://web.dev/fast/
devido à normalização. Quando isso acontece, um objeto urlNormalizationDetails
é incluído na resposta.
{
"record": {
"key": {
"url": "https://web.dev/fast/"
},
"metrics": { ... }
},
"urlNormalizationDetails": {
"normalizedUrl": "https://web.dev/fast/",
"originalUrl": "https://web.dev/fast/#measure-performance-in-the-field"
}
}
Saiba mais sobre a normalização de URLs na documentação do CrUX.
Consultar por formato
As experiências do usuário podem variar significativamente dependendo das otimizações do site, das condições da rede e das necessidades dispositivos. Para entender melhor essas diferenças, detalhe a origem e o desempenho do URL usando a dimensão formFactor
da API CrUX.
A API oferece suporte a três valores de formato explícitos: DESKTOP
, PHONE
e TABLET
. Além da origem ou do URL, especifique um desses valores no corpo da solicitação para restringir os resultados apenas a essas experiências do usuário. Este exemplo demonstra como consultar a API por formato usando cURL.
API_KEY="[YOUR_API_KEY]"
curl "https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=$API_KEY" \
--header 'Content-Type: application/json' \
--data '{"url": "https://web.dev/fast/", "formFactor": "PHONE"}'
Para consultar a API CrUX para dados específicos de formatos usando JavaScript, chame a função CrUXApiUtil.query
usando os parâmetros url
e formFactor
no corpo da solicitação.
CrUXApiUtil.query({
url: 'https://web.dev/fast/',
formFactor: 'PHONE'
}).then(response => {
console.log(response);
}).catch(response => {
console.error(response);
});
A omissão do parâmetro formFactor
equivale a solicitar dados de todos os formatos combinados.
{
"record": {
"key": {
"url": "https://web.dev/fast/",
"formFactor": "PHONE"
},
"metrics": {
"largest_contentful_paint": {
"histogram": [
{
"start": 0,
"end": 2500,
"density": 0.778631284916204
},
{
"start": 2500,
"end": 4000,
"density": 0.13943202979515887
},
{
"start": 4000,
"density": 0.08193668528864119
}
],
"percentiles": {
"p75": 2366
}
},
// ...
}
}
}
O campo key
da resposta vai retornar a configuração da solicitação formFactor
para confirmar que apenas experiências em smartphones estão incluídas.
Na seção anterior, 85% das experiências do usuário nessa página tiveram "boas" ou LCP. Compare isso com as experiências específicas em smartphones, das quais apenas 78% são consideradas "boas". O 75o percentil também é mais lento entre as experiências em smartphones, de 1.947 milissegundos para 2.366 milissegundos. A segmentação por formato tem o potencial de destacar disparidades mais extremas nas experiências do usuário.
Avaliar o desempenho das Core Web Vitals
O programa Core Web Vitals define objetivos que ajudam a determinar se uma experiência do usuário ou uma distribuição de experiências pode ser considerada "boa". No exemplo a seguir, usamos a API CrUX e a função CrUXApiUtil.query
para avaliar se a distribuição das Core Web Vitals (LCP, FID, CLS) de uma página da Web é "boa".
CrUXApiUtil.query({
url: 'https://web.dev/fast/'
}).then(response => {
assessCoreWebVitals(response);
}).catch(response => {
console.error(response);
});
function assessCoreWebVitals(response) {
// See https://web.dev/vitals/#core-web-vitals.
const CORE_WEB_VITALS = [
'largest_contentful_paint',
'first_input_delay',
'cumulative_layout_shift'
];
CORE_WEB_VITALS.forEach(metric => {
const data = response.record.metrics[metric];
if (!data) {
console.log('No data for', metric);
return;
}
const p75 = data.percentiles.p75;
const threshold = data.histogram[0].end;
// A Core Web Vitals metric passes the assessment if
// its 75th percentile is under the "good" threshold.
const passes = p75 < threshold;
console.log(`The 75th percentile (${p75}) of ${metric} ` +
`${passes ? 'passes' : 'does not pass'} ` +
`the Core Web Vitals "good" threshold (${threshold}).`)
});
}
Os resultados mostram que a página é aprovada nas avaliações das Core Web Vitals para as três métricas.
The 75th percentile (1973) of largest_contentful_paint passes the Core Web Vitals "good" threshold (2500).
The 75th percentile (20) of first_input_delay passes the Core Web Vitals "good" threshold (100).
The 75th percentile (0.05) of cumulative_layout_shift passes the Core Web Vitals "good" threshold (0.10).
Combinados a uma maneira automatizada de monitorar os resultados da API, os dados do CrUX podem ser usados para garantir que as experiências do usuário real sejam rápidas e permaneçam rápidas. Para mais informações sobre as Core Web Vitals e como medi-las, consulte as páginas Métricas da Web e Ferramentas para avaliar as Core Web Vitals.
A seguir
Os recursos incluídos na versão inicial da API CrUX são apenas uma amostra superficial dos tipos de insights possíveis com o CrUX. Os usuários do conjunto de dados CrUX no BigQuery podem conhecer alguns dos recursos mais avançados, incluindo:
- Outras métricas
first_paint
dom_content_loaded
onload
time_to_first_byte
notification_permissions
- Dimensões adicionais
month
country
effective connection type
(ECT)
- Granularidade adicional
- Histogramas detalhados
- mais percentis
Confira a documentação oficial da API CrUX para adquirir sua chave de API e conhecer mais aplicativos de exemplo. Esperamos que você teste o recurso. Queremos receber feedback e dúvidas sobre sua experiência com a gente, então entre em contato no fórum de discussão do CrUX. Para ficar por dentro de tudo o que planejamos para a API CrUX, inscreva-se no fórum de anúncios do CrUX ou siga nosso perfil no Twitter (@ChromeUXReport).