Como usar a API CrUX

Aprenda a usar a API Chrome UX Report para acessar dados de experiência de usuários reais em milhões de sites.

Rick Viscomi
Shane Exterkamp
Shane Exterkamp
X GitHub

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), Interaction to Next Paint (INP) 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:

  1. O endpoint de 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. 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 sua 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 com métricas que representam 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 de 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.

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

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

Sucesso
{"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.

Consulta 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 o 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 repetir a configuração da solicitação formFactor para confirmar que apenas as experiências de smartphone 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 do smartphone, 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 metas 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, INP, 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',
    'interaction_to_next_paint',
    '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 interaction_to_next_paint passes the Core Web Vitals "good" threshold (200).
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 pequena amostra dos tipos de insights possíveis. 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).