Como usar a API CrUX

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.

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), 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:

  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 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.

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.

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).