API CrUX

A API CrUX oferece acesso de baixa latência a dados agregados de experiência do usuário real em granularidade de página e origem.

Caso de uso comum

A API CrUX permite a consulta de métricas de experiência do usuário para um URI específico, como "Receber métricas da origem https://example.com".

Chave de API do CrUX

Para usar a API CrUX, é preciso ter uma chave de API do Google Cloud. É possível criar uma na página Credenciais e provisioná-la para uso no Chrome UX Report API.

Quando você está com uma chave de API, seu aplicativo pode anexar o parâmetro de consulta key=[YOUR_API_KEY] a todos os URLs das solicitações. Consulte Exemplos de consultas.

A chave de API é segura para ser incorporada a URLs sem precisar de codificação.

Modelo de dados

Esta seção detalha a estrutura de dados em solicitações e respostas.

Gravar

Uma informação discreta sobre uma página ou um site. Um registro pode ter dados específicos para um identificador e para uma combinação específica de dimensões. Um registro pode conter dados para uma ou mais métricas.

Identificadores

Os identificadores especificam quais registros devem ser consultados. No CrUX, esses identificadores são páginas da Web e sites.

Origem

Quando o identificador é uma origem, todos os dados presentes em todas as páginas dessa origem são agregados. Por exemplo, digamos que a origem http://www.example.com tenha páginas conforme disposto por este sitemap:

http://www.example.com/
http://www.example.com/foo.html
http://www.example.com/bar.html

Isso significa que, ao consultar o Chrome UX Report com a origem definida como http://www.example.com, os dados de http://www.example.com/, http://www.example.com/foo.html e http://www.example.com/bar.html seriam retornados agregados, porque essas são todas as páginas dessa origem.

URLs

Quando o identificador for um URL, somente os dados desse URL específico serão retornados. Procurando novamente o sitemap de origem http://www.example.com:

http://www.example.com/
http://www.example.com/foo.html
http://www.example.com/bar.html

Se o identificador estiver definido como um URL com o valor http://www.example.com/foo.html, somente os dados dessa página serão retornados.

Dimensões

As dimensões identificam um grupo específico de dados ao qual um registro está sendo agregado. Por exemplo, um formato PHONE indica que o registro contém informações sobre carregamentos que ocorreram em um dispositivo móvel. Cada dimensão terá um determinado número de valores, e a ausência de especificação faz com que a dimensão seja agregada a todos os valores. Por exemplo, não especificar nenhum formato indica que o registro contém informações sobre carregamentos que ocorreram em qualquer formato.

Formato

A classe de dispositivo que o usuário final utilizou para navegar até a página. Essa é uma classe geral de dispositivo dividida em PHONE, TABLET e DESKTOP.

Tipo de conexão eficaz

O Tipo de conexão efetiva é a qualidade de conexão estimada do dispositivo ao navegar até a página. Essa é uma classe geral dividida em offline, slow-2G, 2G, 3G e 4G.

Métrica

As métricas são relatadas como agregações estatísticas, em histogramas, percentis e frações.

Valores de ponto flutuante são arredondados para quatro casas decimais. Observe que as métricas cumulative_layout_shift são codificadas duas vezes como uma string, portanto, não são consideradas flutuações e são informadas como duas casas decimais na string.

Histograma

Quando as métricas são expressas em um histograma, mostramos as porcentagens de carregamentos de página em intervalos específicos dessa métrica.

Um histograma simples de três barras para uma métrica de exemplo fica assim:

{
  "histogram": [
    {
      "start": 0,
      "end": 1000,
      "density": 0.3818
    },
    {
      "start": 1000,
      "end": 3000,
      "density": 0.4991
    },
    {
      "start": 3000,
      "density": 0.1192
    }
  ]
}

Esses dados indicam que, para 38,18% dos carregamentos de página, a métrica de exemplo foi medida entre 0 ms e 1.000 ms. As unidades da métrica não estão contidas neste histograma. Neste caso, vamos considerar milissegundos.

Além disso, 49,91% dos carregamentos de página tiveram um valor de métrica entre 1.000 ms e 3.000 ms, e 11,92% tiveram um valor maior que 3.000 ms.

Percentis

As métricas também podem conter percentis que podem ser úteis para análises adicionais. Informamos valores específicos de métricas no percentil determinado para essa métrica. Elas se baseiam no conjunto completo de dados disponíveis, e não nos dados agrupados por classes. Portanto, não correspondem necessariamente a um percentil interpolado baseado no histograma final agrupado por classes.

{
  "percentiles": {
    "p75": 2063
  }
}

Neste exemplo, pelo menos 75% dos carregamentos de página foram medidos com um valor de métrica <= 2063.

Frações

As frações indicam as porcentagens de carregamentos de página que podem ser rotulados de uma forma específica. Nesse caso, os valores das métricas são esses rótulos.

Por exemplo, a métrica form_factors consiste em um objeto fractions que lista o detalhamento dos formatos (ou dispositivos) abrangidos pela consulta especificada:

"form_factors": {
  "fractions": {
    "desktop": 0.0377,
    "tablet": 0.0288,
    "phone": 0.9335
  }
}

Nesse caso, 3,77% dos carregamentos de página foram medidos em um computador, 2,88% em um tablet e 93,35% em um smartphone, totalizando 100%.

Tipos de valor de métrica

Nome da métrica da API CrUX Tipo de dados Unidades métricas Agregações estatísticas Documentação
cumulative_layout_shift duas casas decimais codificadas duas vezes como string sem unidade histograma com três agrupamentos, percentis com p75 cls
first_contentful_paint int milésimos de segundo histograma com três agrupamentos, percentis com p75 fcp (link em inglês)
first_input_delay
(descontinuado)		 int milésimos de segundo histograma com três agrupamentos, percentis com p75 fid
interaction_to_next_paint int milésimos de segundo histograma com três agrupamentos, percentis com p75 inp (link em inglês)
largest_contentful_paint int milésimos de segundo histograma com três agrupamentos, percentis com p75 lcp (link em inglês)
experimental_time_to_first_byte int milésimos de segundo histograma com três agrupamentos, percentis com p75 ttfb (em inglês)
form_factors Casa decimal com quatro casas decimais porcentagem mapeamento do formato para fração formatos
navigation_types Casa decimal com quatro casas decimais porcentagem mapeamento do tipo de navegação para fração tipos de navegação
round_trip_time int milésimos de segundo percentis com p75 rtt

Mapeamento de nomes de métricas do BigQuery

Nome da métrica da API CrUX Nome da métrica do BigQuery
cumulative_layout_shift layout_instability.cumulative_layout_shift
first_contentful_paint first_contentful_paint
first_input_delay first_input.delay
interaction_to_next_paint interaction_to_next_paint
largest_contentful_paint largest_contentful_paint
experimental_time_to_first_byte experimental.time_to_first_byte
navigation_types navigation_types
form_factors N/A
round_trip_time N/A

Período de coleta

Desde outubro de 2022, a API CrUX contém um objeto collectionPeriod com os campos firstDate e endDate que representam as datas de início e término da janela de agregação. Exemplo:

    "collectionPeriod": {
      "firstDate": {
        "year": 2022,
        "month": 9,
        "day": 12
      },
      "lastDate": {
        "year": 2022,
        "month": 10,
        "day": 9
      }
    }

Isso permite uma melhor compreensão dos dados e se eles já foram atualizados para o dia em questão ou se estão retornando os mesmos dados de ontem.

A API CrUX está aproximadamente dois dias atrás da data de hoje, porque espera os dados completos do dia, e há um tempo de processamento envolvido antes de ser disponibilizado na API. O fuso horário usado é o Horário padrão do Pacífico (PST, na sigla em inglês), sem alterações para o horário de verão.

Exemplos de consultas

As consultas são enviadas como objetos JSON usando uma solicitação POST para https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=[YOUR_API_KEY]" com os dados da consulta na forma de um objeto JSON no corpo do POST:

{
  "origin": "https://example.com",
  "formFactor": "PHONE",
  "metrics": [
    "largest_contentful_paint",
    "experimental_time_to_first_byte"
  ]
}

Por exemplo, isso pode ser chamado em curl com a seguinte linha de comando (substituindo API_KEY pela sua chave):

curl -s --request POST 'https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=API_KEY' \
    --header 'Accept: application/json' \
    --header 'Content-Type: application/json' \
    --data '{"formFactor":"PHONE","origin":"https://www.example.com","metrics":["largest_contentful_paint", "experimental_time_to_first_byte"]}'

Os dados no nível da página estão disponíveis pela API transmitindo uma propriedade url na consulta, em vez de origin:

{
  "url": "https://example.com/page",
  "formFactor": "PHONE",
  "metrics": [
    "largest_contentful_paint",
    "experimental_time_to_first_byte"
  ]
}

Se a propriedade metrics não for definida, todas as métricas disponíveis serão retornadas:

  • cumulative_layout_shift
  • first_contentful_paint
  • first_input_delay (descontinuado)
  • interaction_to_next_paint
  • largest_contentful_paint
  • experimental_time_to_first_byte
  • navigation_types
  • form_factors (informado somente se nenhum formFactor for especificado na solicitação)

Se nenhum valor formFactor for fornecido, os valores serão agregados em todos os formatos.

Consulte Como usar a API Chrome UX Report para ver mais exemplos de consulta.

Pipeline de dados

O conjunto de dados CrUX é processado por um pipeline para consolidar, agregar e filtrar os dados antes de serem disponibilizados usando a API.

A média contínua

Os dados do Chrome UX Report são uma média contínua de 28 dias de métricas agregadas. Isso significa que os dados apresentados no Chrome UX Report são, na verdade, os dados dos últimos 28 dias agregados.

Esse processo é parecido com a forma como o conjunto de dados do CrUX no BigQuery agrega relatórios mensais.

Atualizações diárias

Os dados são atualizados diariamente por volta das 4h UTC. Não há contrato de nível de serviço para horários de atualização. Ele é executado na medida do possível todos os dias.

Esquema

Há um único endpoint para a API CrUX que aceita solicitações HTTP POST. A API retorna um record que contém um ou mais metrics correspondentes aos dados de desempenho sobre a origem ou página solicitada.

Solicitação HTTP

POST https://chromeuxreport.googleapis.com/v1/records:queryRecord

O URL usa a sintaxe de transcodificação gRPC.

Corpo da solicitação

O corpo da solicitação precisa conter dados com a seguinte estrutura:

{
  "effectiveConnectionType": string,
  "formFactor": enum (FormFactor),
  "metrics": [
    string
  ],

  // Union field url_pattern can be only one of the following:
  "origin": string,
  "url": string
  // End of list of possible types for union field url_pattern.
}
Campos
effectiveConnectionType

string

O tipo de conexão efetiva é uma dimensão de consulta que especifica a classe de rede efetiva a que os dados do registro devem pertencer.

Esse campo usa os valores ["offline", "slow-2G", "2G", "3G", "4G"] conforme definido na especificação da API Network Information

Observação: se nenhum tipo de conexão efetiva for especificado, será retornado um registro especial com dados agregados em todos os tipos de conexão vigentes.
formFactor

enum (FormFactor)

O formato é uma dimensão de consulta que especifica a classe de dispositivo a que os dados do registro devem pertencer.

Esse campo usa os valores DESKTOP, PHONE ou TABLET.

Observação: se nenhum formato for especificado, será retornado um registro especial com dados agregados de todos os formatos.
metrics[]

string

As métricas que devem ser incluídas na resposta. Se nenhuma for especificada, todas as métricas encontradas serão retornadas.

Valores permitidos: ["cumulative_layout_shift", "first_contentful_paint", "first_input_delay", "interaction_to_next_paint", "largest_contentful_paint", "experimental_time_to_first_byte"]
Campo de união url_pattern. O url_pattern é o identificador principal de uma pesquisa de registro. Pode ser apenas uma das seguintes opções:
origin

string

A "origem" do url_pattern se refere a um padrão do URL que é a origem de um site.

Por exemplo: "https://example.com", "https://cloud.google.com"
url

string

O url_pattern url refere-se a um padrão de URL que é qualquer URL arbitrário.

Por exemplo: "https://example.com/, https://cloud.google.com/why-google-cloud/"

Por exemplo, para solicitar os maiores valores de Contentful Paint para computador para a página inicial da documentação do desenvolvedor do Chrome:

{
  "url": "https://developer.chrome.com/docs/",
  "formFactor": "DESKTOP",
  "metrics": [
    "largest_contentful_paint"
  ]
}

Corpo da resposta

As solicitações bem-sucedidas retornam respostas com um objeto record e urlNormalizationDetails na seguinte estrutura:

{
  "record": {
    "key": {
      object (Key)
    },
    "metrics": [
      string: {
        object (Metric)
      }
    ]
  },
  "urlNormalizationDetails": {
    object (UrlNormalization)
  }
}

Por exemplo, a resposta para o corpo da solicitação na solicitação anterior poderia ser:

{
  "record": {
    "key": {
      "formFactor": "DESKTOP",
      "url": "https://developer.chrome.com/docs/"
    },
    "metrics": {
      "largest_contentful_paint": {
        "histogram": [
          {
            "start": 0,
            "end": 2500,
            "density": 0.9815
          },
          {
            "start": 2500,
            "end": 4000,
            "density": 0.0108
          },
          {
            "start": 4000,
            "density": 0.0077
          }
        ],
        "percentiles": {
          "p75": 651
        }
      }
    },
    "collectionPeriod": {
      "firstDate": {
        "year": 2022,
        "month": 9,
        "day": 12
      },
      "lastDate": {
        "year": 2022,
        "month": 10,
        "day": 9
      }
    }
  }
}

Chave

Key define todas as dimensões que identificam esse registro como exclusivo.

{
  "effectiveConnectionType": string,
  "formFactor": enum (FormFactor),

  // Union field url_pattern can be only one of the following:
  "origin": string,
  "url": string
  // End of list of possible types for union field url_pattern.
}
Campos
formFactor

enum (FormFactor)

O formato é a classe de dispositivo que todos os usuários usaram para acessar o site nesse registro.

Se o formato não for especificado, os dados agregados de todos os formatos serão retornados.
effectiveConnectionType

string

O tipo de conexão efetiva é a classe de conexão geral que todos os usuários tiveram neste registro. Esse campo usa os valores ["offline", "slow-2G", "2G", "3G", "4G"] conforme especificado em: https://wicg.github.io/netinfo/#effective-connection-types

Se o tipo de conexão efetiva não for especificado, serão retornados os dados agregados de todos os tipos de conexão efetiva.
Campo de união url_pattern. O padrão de URL é o URL ao qual o registro se aplica. url_pattern só pode ser de um dos seguintes tipos:
origin

string

origin especifica a origem deste registro.

Observação: ao especificar um origin, os dados dos carregamentos nessa origem em todas as páginas são agregados aos dados de experiência do usuário no nível da origem.
url

string

url especifica um URL específico a que esse registro se destina.

Observação: ao especificar um url, somente os dados desse URL específico serão agregados.

Métricas

Um metric é um conjunto de dados agregados de experiência do usuário para uma única métrica de desempenho da Web, como a First Contentful Paint. Ele pode conter um histograma de resumo do uso do Chrome no mundo real como uma série de bins, dados de percentis específicos (como o p75) ou frações rotuladas.

{
  "histogram": [
    {
      object (Bin)
    }
  ],
  "percentiles": {
    object (Percentiles)
  }
}

ou

{
  "fractions": {
    object (Fractions)
  }
}
Campos
histogram[]

object (Bin)

O histograma das experiências do usuário de uma métrica. O histograma terá pelo menos um agrupamento e as densidades de todas as barras serão somadas a ~1.
percentiles

object (Percentiles)

Percentis úteis comuns da métrica. O tipo de valor para os percentis será o mesmo que os tipos de valor fornecidos para os agrupamentos do histograma.
fractions

object (Fractions)

Esse objeto contém frações rotuladas, que somam ~1.

As frações são arredondadas para quatro casas decimais.

Agrupamento

Um bin é uma parte discreta de dados que abrange do início ao fim, ou se nenhuma extremidade for informada do início ao infinito positivo.

Os valores inicial e final de um agrupamento são fornecidos no tipo de valor da métrica que ele representa. Por exemplo, a First Contentful Paint é medida em milissegundos e exposta como ints. Portanto, os agrupamentos de métricas vão usar int32s para os tipos inicial e final. No entanto, a mudança cumulativa de layout é medida em decimais sem unidade e exposta como um decimal codificado como uma string. Portanto, os agrupamentos de métricas vão usar strings para o tipo de valor.

{
  "start": value,
  "end": value,
  "density": number
}
Campos
start

(integer | string)

Start é o início do compartimento de dados.
end

(integer | string)

Fim é o fim do compartimento de dados. Se end não for preenchido, o agrupamento não terá fim e será válido do início até +inf.
density

number

A proporção de usuários que experimentou o valor desse agrupamento para a métrica especificada.

As densidades são arredondadas para quatro casas decimais.

Percentis

Percentiles contém valores sintéticos de uma métrica em um determinado percentil estatístico. Elas são usadas para estimar o valor de uma métrica conforme a experiência por uma porcentagem de usuários em relação ao número total de usuários.

{
  "P75": value
}
Campos
p75

(integer | string)

75% dos carregamentos de página tiveram a métrica especificada igual ou menor que esse valor.

Frações

Fractions contém frações rotuladas que somam aproximadamente 1. Cada rótulo descreve um carregamento de página de alguma forma. Assim, as métricas representadas dessa maneira podem ser consideradas como produtoras de valores distintos em vez de valores numéricos, e as frações expressam a frequência com que um determinado valor distinto foi medido.

{
  "label_1": fraction,
  "label_2": fraction,
  ...
  "label_n": fraction
}

Assim como os valores de densidade nas barras do histograma, cada fraction é um número 0.0 <= value <= 1.0 e somam aproximadamente 1, 0.

UrlNormalization

Objeto que representa as ações de normalização realizadas para normalizar um URL e aumentar as chances de uma pesquisa bem-sucedida. Essas são simples mudanças automatizadas que são realizadas na pesquisa do url_pattern fornecido e falhariam. Ações complexas, como seguir redirecionamentos, não são tratadas.

{
  "originalUrl": string,
  "normalizedUrl": string
}
Campos
originalUrl

string

O URL original solicitado antes de qualquer ação de normalização.
normalizedUrl

string

O URL após qualquer ação de normalização. Esse é um URL de experiência do usuário válido que poderia ser procurado.

Limitações de taxa

A API CrUX é limitada a 150 consultas por minuto por projeto do Google Cloud, oferecida sem custo financeiro. Esse limite e seu uso atual podem ser consultados no Console do Google Cloud. Essa cota generosa deve ser suficiente para a grande maioria dos casos de uso e não é possível pagar por uma cota maior.