Como usar a API CrUX

Aprenda a usar a API Chrome UX Report para ter acesso a dados de experiência do usuário real em milhões de sites.

Rick Viscomi

Shane Exterkamp

O conjunto de dados do Chrome UX Report (CrUX, na sigla em inglês) representa como os usuários reais do Chrome utilizam destinos comuns na Web. Desde 2017, quando o conjunto de dados para consulta foi lançado no BigQuery, os dados de campo do CrUX foram integrados a ferramentas para desenvolvedores, como o PageSpeed Insights, o Painel do CrUX e o relatório Core Web Vitals do Search Console. Assim, os desenvolvedores podem medir e monitorar as experiências dos usuários. A peça que faltava todo esse tempo é uma ferramenta que fornece acesso sem custo financeiro e RESTful aos dados do CrUX de maneira programática. Para ajudar a preencher essa lacuna, temos o prazer de anunciar o lançamento da nova API Chrome UX Report.

Essa API foi criada com o objetivo de fornecer aos desenvolvedores acesso simples, rápido e abrangente aos dados do CrUX. A API CrUX só informa dados de experiência do usuário de campo, ao contrário da API PageSpeed Insights atual, que também registra dados de laboratório das auditorias de desempenho do Lighthouse. A API CrUX é simplificada e pode exibir rapidamente dados de experiência do usuário. Por isso, ela é 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 Maior exibição de conteúdo (LCP), Latência na primeira entrada (FID) e Mudança de layout cumulativa (CLS) no nível da origem e do URL.

Vamos aprender a usá-la.

Consultar dados de origem

As origens no conjunto de dados CrUX abrangem todas as experiências subjacentes 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"}'

Observação:todas as solicitações de API precisam fornecer um valor para o parâmetro key. [YOUR_API_KEY] no exemplo anterior é deixado como um marcador. Receba sua própria chave da API CrUX privada, conforme descrito na documentação da API CrUX.

O comando curl é composto por três partes:

1. O endpoint do URL da API, incluindo a chave de API privada do autor da chamada.
2. O cabeçalho Content-Type: application/json, indicando que o corpo da solicitação contém JSON.
3. 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. Consulte 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 corpo da solicitação.

CrUXApiUtil.query({
  origin: 'https://web.dev'
}).then(response => {
  console.log(response);
}).catch(response => {
  console.error(response);
});

Se existirem dados para essa origem, a resposta da API será um objeto codificado em JSON que contém metrics que representam a distribuição de experiências do usuário. As métricas de distribuição são agrupamentos 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 para a métrica especificada. A propriedade density representa a proporção de experiências do usuário nesse intervalo. Neste exemplo, 79% das experiências do usuário com LCP em todas as páginas web.dev ficam em menos de 2.500 milissegundos, que é o limite de LCP "bom". O valor de percentiles.p75 significa que 75% das experiências do usuário nessa 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 é navegável publicamente. Para testar isso, insira a origem na barra de endereço do seu navegador e compare-a com o URL final após redirecionamentos. Problemas comuns incluem adicionar ou omitir desnecessariamente o subdomínio e usar o protocolo HTTP errado.

Erro

{"origin": "http://www.web.dev"}

Esta origem inclui incorretamente o protocolo http:// e o subdomínio www..

Concluído

{"origin": "https://web.dev"}

Esta origem é navegável publicamente.

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 tornar anônimos os usuários. 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ê já aprendeu a consultar a API CrUX para ter 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 do 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 houver dados para esse URL no conjunto de dados do 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 realidade, os resultados mostram que https://web.dev/fast/ tem 85% de experiências "boas" de LCP e um 75o percentil de 1.947 milissegundos, o que é um pouco melhor do que a distribuição em toda a 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 vai 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

Termo-chave:um formato é o tipo de dispositivo que um usuário acessa um site. Os tipos de dispositivos comuns incluem computador, smartphone e tablet.

As experiências do usuário podem variar significativamente, dependendo das otimizações do site, das condições da rede e dos dispositivos dos usuários. Para entender melhor essas diferenças, detalhe a performance da origem e 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 somente 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 formato 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 para 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 as experiências de smartphone foram incluídas.

Atenção:quanto mais detalhada for a solicitação (por exemplo, uma combinação específica de URL e formato), menos experiências do usuário ela vai incluir. Isso pode levar a erros do tipo "não encontrado" mais frequentes, especialmente ao consultar URLs menos acessados ou o tipo de tablet menos comum.

Lembre-se de que, na seção anterior, 85% das experiências do usuário nessa página tiveram uma LCP "boa". Compare isso com experiências específicas para smartphones, sendo que apenas 78% delas são consideradas "boas". O 75o percentil também é mais lento entre as experiências com smartphones, passando 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 segmentações 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}).`)
  });
}

Importante:a API só pode ser chamada com uma origem ou URL por vez. Para avaliar vários sites ou páginas, faça chamadas separadas para a API.

Os resultados mostram que a página foi 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 com 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 fazer a medição delas, consulte Métricas da Web e Ferramentas para avaliar as Core Web Vitals.

Qual é a próxima etapa?

Os recursos incluídos na versão inicial da API CrUX são apenas os primeiros tipos de insights possíveis com ele. Os usuários do conjunto de dados CrUX no BigQuery podem estar familiarizados com 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 os documentos oficiais da API CrUX para adquirir sua chave de API e veja outros aplicativos de exemplo. Esperamos que você experimente a ferramenta. Adoraríamos ouvir qualquer dúvida ou feedback que você tiver. Entre em contato pelo fórum de discussão 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 em @ChromeUXReport.