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 consultar métricas de experiência do usuário para um URI específico, como "Receber métricas para a origem do https://example.com".

Chave da API CrUX

Para usar a API CrUX, você precisa de uma chave de API do Google Cloud. Você pode criar uma na página Credenciais e provisioná-la para uso do Chrome UX Report API.

Depois que você estiver com uma chave de API, seu aplicativo poderá anexar o parâmetro de consulta key=[YOUR_API_KEY] a todos os URLs de solicitação. 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 de uma ou mais métricas.

Identificadores

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

Origem

Quando o identificador é uma origem, todos os dados presentes para todas as páginas nessa 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 sob essa origem.

URLs

Quando o identificador é um URL, apenas os dados desse URL específico são retornados. Analisando 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 de 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 para o qual um registro está sendo agregado. Por exemplo, um formato de 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, implicitamente, a falta de especificar essa dimensão significa que ela será agregada em todos os valores. Por exemplo, a especificação de nenhum formato indica que o registro contém informações sobre os carregamentos que ocorreram em qualquer formato.

Formato

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

Tipo de conexão efetiva

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

Métrica

Registramos métricas como agregações estatísticas em histogramas, percentis e frações.

Valores de ponto flutuante são arredondados para quatro casas decimais. As métricas cumulative_layout_shift são duplas codificadas como uma string. Por isso, não são consideradas flutuações e são informadas para duas casas decimais na string.

Histograma

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

Um histograma simples de três bin 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 de métricas específicos no percentil determinado para essa métrica. Elas são baseadas no conjunto completo de dados disponíveis, e não nos dados finais agrupados por classes. Portanto, elas não correspondem necessariamente a um percentil interpolado baseado no histograma agrupado final.

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

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

Observação:os valores de cada percentil são derivados de forma sintética. Isso não significa que algum usuário realmente viu o valor indicado, somente que parte dos carregamentos de página teve um valor de métrica menor que o valor fornecido.

Frações

As frações indicam as porcentagens de carregamentos de página que podem ser rotulados de uma maneira 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) que a consulta abrange:

"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 valores de métricas

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	milissegundos	histograma com três agrupamentos, percentis com p75	FTP
first_input_delay (descontinuado)	int	milissegundos	histograma com três agrupamentos, percentis com p75	fid
interaction_to_next_paint	int	milissegundos	histograma com três agrupamentos, percentis com p75	inp (link em inglês)
largest_contentful_paint	int	milissegundos	histograma com três agrupamentos, percentis com p75	lcp (link em inglês)
experimental_time_to_first_byte	int	milissegundos	histograma com três agrupamentos, percentis com p75	ttfb (em inglês)
form_factors	Duplo de quatro casas decimais	porcentagem	mapeamento de formato para fração	formatos
navigation_types	Duplo de quatro casas decimais	porcentagem	mapeamento do tipo de navegação para fração	tipos de navegação

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

Observação:no BigQuery CrUX, as densidades de histograma adicionam até 100% por origem em formatos. Portanto, a métrica form_factors aceita na API é expressa como as densidades de histograma para first_contentful_paint.

Período de coleta

Desde outubro de 2022, a API CrUX contém um objeto collectionPeriod com os campos firstDate e endDate representando 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 aquele dia ou se estão retornando os mesmos dados de ontem.

Observe que a API CrUX está aproximadamente dois dias atrasada em relação à data de hoje, já que ela aguarda os dados completos do dia, e há um tempo de processamento envolvido antes que eles sejam disponibilizados na API. O fuso horário usado é o horário padrão do Pacífico (PST, na sigla em inglês), sem mudanças no 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 dados de consulta como 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"]}'

Observação:o exemplo anterior é para sistemas baseados em macOS ou Linux, incluindo o shell do Git BASH para Windows. Outros sistemas podem exigir pequenas modificações. Por exemplo, a linha de comando cmd.exe não permite aspas simples para os parâmetros nem as continuações de linha (\). Portanto, ela exige o uso de aspas duplas (com o escape de aspas internas conforme apropriado com \") e de uma única linha.

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 apenas se nenhum formFactor for especificado na solicitação)

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

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

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 das métricas agregadas. Isso significa que os dados apresentados no Chrome UX Report a qualquer momento são, na verdade, dados dos últimos 28 dias agregados.

O processo é parecido com a forma como o conjunto de dados 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 com base no melhor esforço todos os dias.

Atenção: os dados não serão diferentes no mesmo dia após a atualização por volta das 4h UTC. As chamadas repetidas vão gerar os mesmos resultados.

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 performance da 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 precisam pertencer. Esse campo usa os valores ["offline", "slow-2G", "2G", "3G", "4G"], conforme especificado 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 efetivas.
formFactor	enum (FormFactor) O formato é uma dimensão de consulta que especifica a classe de dispositivo a que os dados do registro precisam 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 precisam 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" de url_pattern refere-se a um padrão de 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 exibição de conteúdo da área de trabalho 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 estrutura a seguir:

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

Por exemplo, a resposta ao 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 único.

{
  "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 do dispositivo que todos os usuários usaram para acessar o site para esse 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 experimentaram para esse registro. Esse campo usa os valores ["off-line", "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, os dados agregados de todos os tipos de conexão efetivas serão retornados.
Campo de união url_pattern. O padrão de URL é o URL ao qual o registro se aplica. url_pattern pode ser apenas de um dos tipos a seguir:
origin	string origin especifica a origem desse 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 para o qual este registro é direcionado. Observação: quando você especifica um url, apenas os dados desse URL são agregados.

Métricas

Uma metric é um conjunto de dados agregados de experiência do usuário para uma única métrica de desempenho na Web, como a primeira exibição de conteúdo. Ele pode conter um histograma de resumo do uso real do Chrome como uma série de bins, dados de percentil específicos (como o p75) ou pode conter 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 para uma métrica. O histograma terá pelo menos um agrupamento e as densidades de todos os agrupamentos serão somados em torno de um.
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 de histograma.
fractions	object (Fractions) Este objeto contém frações rotuladas, que somam aproximadamente 1. As frações são arredondadas para quatro casas decimais.

Agrupamento

Um bin é uma parte discreta dos dados que abrange do início ao fim ou se nenhum fim é fornecido 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 primeira exibição de conteúdo é medida em milissegundos e exposta como ints. Portanto, os agrupamentos de métricas vão usar int32s para os tipos de início e fim. No entanto, a mudança de layout cumulativa é medida em decimais sem unidade e exposta como um decimal codificado como uma string. Portanto, os agrupamentos de métricas usarão strings para o tipo de valor.

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

Campos
start	(integer | string) O início é o início do agrupamento de dados.
end	(integer | string) O fim é o fim do agrupamento de dados. Se end não for preenchido, o agrupamento não terá fim e será válido do início a +inf.
density	number A proporção de usuários que experimentaram 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. Eles são usados para estimar o valor de uma métrica conforme observado por uma porcentagem de usuários do número total.

{
  "P75": value
}

Campos
p75	(integer | string) 75% dos carregamentos de página apresentaram a métrica especificada com um valor igual ou menor que esse.

Frações

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

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

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

UrlNormalization

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

{
  "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 válido de experiência do usuário que poderia ser razoavelmente pesquisado.

Limitações de taxa

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