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": "/proxy/http://www.web.dev"}

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

Sucesso
{"origin": "/proxy/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).