Como usar a API CrUX

Saiba como 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) representa a experiência de usuários reais do Chrome em destinos populares na Web. Desde 2017, quando o conjunto de dados consultáveis foi lançado no BigQuery, os dados de campo do CrUX foram integrados a ferramentas para desenvolvedores, como o PageSpeed Insights e o relatório Core Web Vitals do Search Console, permitindo que os desenvolvedores medam e monitorem as experiências de usuários reais. O que faltava até agora era uma ferramenta que oferecesse acesso sem custo financeiro e RESTful aos dados do CrUX de forma programática. Para ajudar a diminuir essa diferença, temos o prazer de anunciar o lançamento da nova API Chrome UX Report.

Ela foi criada para oferecer aos desenvolvedores acesso rápido e abrangente aos dados do CrUX. A API CrUX informa apenas dados de experiência do usuário de campo, ao contrário da API PageSpeed Insights, que também informa dados de laboratório das auditorias de desempenho do Lighthouse. A API CrUX é simplificada e pode fornecer dados de experiência do usuário rapidamente, 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 o Largest Contentful Paint (LCP), a Interaction to Next Paint (INP) e o Cumulative Layout Shift (CLS) no nível da origem e do URL.

Vamos entender melhor como ela funciona.

Testar a API nesta página

Faça um teste

Consultar dados de origem

As origens no conjunto de dados do CrUX abrangem todas as experiências subjacentes no nível da página. O exemplo a seguir demonstra como consultar os dados de experiência do usuário de uma origem usando a API CrUX com 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 chamador.
  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 sua 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 houver dados para essa origem, a resposta da API será um objeto codificado em JSON que contém métricas representando a distribuição das experiências do usuário. As métricas de distribuição são classes de histograma e percentis.

{
  "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 têm 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 de LCP em todas as páginas do web.dev estão abaixo de 2.500 milissegundos, que é o limite "bom" de LCP. O valor percentiles.p75 significa que 75% das experiências do usuário nessa distribuição são menores que 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 pode ser acessada publicamente. Para testar, insira a origem na barra de endereços do navegador e compare 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"}

Essa origem pode ser acessada 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 anonimizar usuários individuais. Além disso, as origens e os URLs precisam ser indexáveis publicamente. Consulte a metodologia do CrUX para saber mais sobre como os sites são incluídos no conjunto de dados.

Dados de URL de consulta

Você já viu como 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, exceto que 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 houver dados para esse URL no conjunto de dados da CrUX, a API vai 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
        }
      },
      // ...
    }
  }
}

Como esperado, os resultados mostram que https://web.dev/fast/ tem 85% de experiências de LCP "boas" e um 75º 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, a consulta do URL https://web.dev/fast/#measure-performance-in-the-field vai resultar em dados para 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 URL na documentação do CrUX.

Consultar por formato

As experiências dos usuários podem variar muito 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 origem e o desempenho do URL usando a dimensão formFactor da API CrUX.

A API é compatível com três valores explícitos de formato: DESKTOP, PHONE e TABLET. Além da origem ou do URL, especifique um destes 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 em busca de dados específicos do fator de forma 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);
});

Omitir o parâmetro formFactor é equivalente 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 repetir a configuração da solicitação formFactor para confirmar que apenas experiências em smartphones estão incluídas.

Na seção anterior, vimos que 85% das experiências do usuário nessa página tiveram uma LCP "boa". Compare isso com as experiências específicas para smartphones, das quais apenas 78% são consideradas "boas". O 75º percentil também é mais lento em experiências com smartphones, passando de 1.947 milissegundos para 2.366 milissegundos. A segmentação por formato pode destacar disparidades mais extremas nas experiências dos usuários.

Avaliar a performance 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 métricas de 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/articles/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 esta página passa nas avaliações das Core Web Vitals para todas 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 com uma maneira automatizada de monitorar os resultados da API, os dados do CrUX podem ser usados para garantir que as experiências de usuários reais sejam rápidas e permaneçam rápidas. Para mais informações sobre as Core Web Vitals e como medi-las, confira Web Vitals e Ferramentas para medir as Core Web Vitals.

A seguir

Os recursos incluídos na versão inicial da API CrUX apenas mostram um pouco dos insights possíveis com o CrUX. Os usuários do conjunto de dados da 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
  • Granularidade adicional
    • histogramas detalhados
    • mais percentis

Confira a documentação oficial da API CrUX para adquirir sua chave de API e conhecer mais exemplos de aplicativos. Esperamos que você teste o recurso e envie suas dúvidas ou feedback no fórum de discussão da CrUX. Para ficar por dentro de tudo o que planejamos para a API CrUX, inscreva-se no fórum de anúncios da CrUX ou siga nosso perfil no Twitter @ChromeUXReport.