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 Relatório de UX do Chrome (CrUX) representa a experiência de usuários reais do Chrome com destinos populares na Web. Desde 2017, quando o conjunto de dados pesquisáveis foi lançado no BigQuery, os dados de campo do CrUX foram integrados a ferramentas de desenvolvedor, 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 de usuários reais. O que faltava era uma ferramenta que oferecesse acesso sem custo financeiro e RESTful aos dados do CrUX de forma programática. Para ajudar a preencher essa lacuna, anunciamos o lançamento da 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 de campo, diferente da API PageSpeed Insights atual, 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 a Largest Contentful Paint (LCP), a Interaction to Next Paint (INP) e a Cumulative Layout Shift (CLS) na origem e no nível do URL.

Vamos conferir como usá-lo.

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 a API CrUX para dados de experiência do usuário de uma origem usando o 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 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, que indica 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 no 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 com métricas que representam a distribuição das experiências do usuário. As métricas de distribuição são intervalos 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 encontram para a métrica especificada. A propriedade density representa a proporção das experiências do usuário dentro desse intervalo. Nesse exemplo, 79% das experiências do usuário do LCP em todas as páginas do web.dev têm menos de 2.500 milissegundos, que é o limite de LCP bom. O valor percentiles.p75 significa que 75% das experiências dos usuários nessa distribuição são de menos de 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 navegador e compare-a com o URL final após os redirecionamentos. Os problemas comuns incluem a adição ou omissão desnecessária do subdomínio e o uso do 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 tornar os usuários individuais anônimos. 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.

Consultar dados de URL

Você aprendeu a consultar a API CrUX para 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 os dados desse URL existirem no conjunto de dados do 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
        }
      },
      // ...
    }
  }
}

Os resultados mostram que https://web.dev/fast/ tem 85% de experiências de LCP "boas" e um percentil de 75º 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 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 URL na documentação do CrUX.

Consulta por formato

A experiência do usuário pode variar significativamente dependendo das otimizações do site, das condições de rede e dos dispositivos dos usuários. Para entender melhor essas diferenças, acesse 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ícito: 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 em busca de dados específicos do 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);
});

Omitir o parâmetro formFactor é equivalente a solicitar dados de todos os fatores de forma 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, você viu que 85% das experiências dos usuários nessa página tiveram uma LCP "boa". Compare isso com as experiências específicas do smartphone, das quais apenas 78% são consideradas "boas". A 75ª percentil também é mais lenta entre as experiências em smartphones, passando de 1.947 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 de métricas 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 esta 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 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 continuem rápidas. Para mais informações sobre as Core Web Vitals e como medi-las, consulte Web Vitals e Ferramentas para medir as Core Web Vitals.

A seguir

Os recursos incluídos na versão inicial da API CrUX são apenas uma pequena parte 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 as documentações oficiais da API CrUX para adquirir sua chave de API e conferir mais exemplos de aplicativos. Esperamos que você teste e adoraríamos receber suas perguntas ou feedback. Entre em contato conosco 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 da CrUX ou siga nossa conta no Twitter @ChromeUXReport.