Interfejs API CrUX

Interfejs CrUX API zapewnia z małym opóźnieniem dostęp do zagregowanych danych o wrażeniach użytkowników na poziomie strony i źródła.

Typowe zastosowanie

Interfejs CrUX API umożliwia wysyłanie zapytań o dane o wrażeniach użytkowników związanych z określonym identyfikatorem URI, np. „Pobierz dane dotyczące źródła https://example.com”.

Klucz interfejsu API CrUX

Korzystanie z interfejsu CrUX API wymaga klucza interfejsu API Google Cloud. Możesz je utworzyć na stronie Dane logowania i udostępnić je na potrzeby Chrome UX Report API.

Gdy uzyskasz klucz interfejsu API, Twoja aplikacja może dołączać parametr zapytania key=[YOUR_API_KEY] do wszystkich adresów URL żądań. Zobacz Przykładowe zapytania.

Klucz interfejsu API można bezpiecznie umieszczać w adresach URL, więc nie trzeba go kodować.

Model danych

Ta sekcja zawiera szczegółowe informacje o strukturze danych w żądaniach i odpowiedziach.

Rekord

Wyjątkowa informacja o stronie lub witrynie. Rekord może zawierać dane specyficzne dla identyfikatora i konkretnej kombinacji wymiarów. Rekord może zawierać informacje dotyczące jednego lub wielu wskaźników.

Identyfikatory

Identyfikatory określają, jakie rekordy należy przeszukać. W CrUX identyfikatory te to strony internetowe i witryny.

Punkt początkowy

Jeśli identyfikatorem jest pochodzenie, wszystkie dane dotyczące wszystkich stron w tym źródle są łączone razem. Załóżmy na przykład, że w źródle http://www.example.com znajdowały się strony wymienione w tej mapie witryny:

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

Oznacza to, że podczas wysyłania zapytania do Raportu na temat użytkowania Chrome, którego źródło jest ustawione na http://www.example.com, zwracane będą dane zagregowane w celach http://www.example.com/, http://www.example.com/foo.html i http://www.example.com/bar.html, ponieważ wszystkie te strony należą do tego źródła.

Adresy URL

Jeśli identyfikatorem jest adres URL, zwracane są tylko dane dotyczące tego konkretnego adresu URL. Jeszcze raz przeanalizujemy mapę witryny http://www.example.com:

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

Jeśli identyfikator jest ustawiony na URL z wartością http://www.example.com/foo.html, zwracane będą tylko dane dotyczące tej strony.

Wymiary

Wymiary identyfikują konkretną grupę danych, na podstawie których agregujemy rekord. Na przykład format PHONE wskazuje, że rekord zawiera informacje o wczytywaniach, które miały miejsce na urządzeniu mobilnym. Każdy wymiar będzie miał pewną liczbę wartości, a jego brak domyślnie oznacza, że wymiar będzie agregowany względem wszystkich wartości. Na przykład brak formatu oznacza, że rekord zawiera informacje o obciążeniach, które miały miejsce na dowolnym formacie.

Rodzaj obudowy

Klasa urządzenia, której użytkownik użył, aby przejść na stronę. To jest ogólna klasa urządzeń podzielona na PHONE, TABLET i DESKTOP.

Efektywny typ połączenia

Efektywny typ połączenia to szacowana jakość połączenia na urządzeniu podczas otwierania strony. To są zajęcia ogólne podzielone na offline, slow-2G, 2G, 3G i 4G.

Wskaźnik

Dane rejestrujemy jako agregacje statystyczne w postaci histogramów, percentyli i ułamków.

Wartości zmiennoprzecinkowe są zaokrąglane do 4 miejsc po przecinku (pamiętaj, że dane cumulative_layout_shift są podwójnie kodowane jako ciąg znaków, więc nie są uznawane za liczby zmiennoprzecinkowe – podawane w ciągu do 2 miejsc po przecinku).

Histogram

Histogram przedstawia wartości procentowe wczytań stron należących do określonych zakresów.

Prosty histogram binarny przykładowych danych wygląda tak:

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

Te dane wskazują, że w przypadku 38,18% wczytań strony przykładowe dane zostały zmierzone w okresie od 0 ms do 1000 ms. Jednostki metryczne nie są ujęte na tym histogramie, w tym przypadku przyjmujemy milisekundy.

Ponadto w przypadku 49,91% wczytań stron wartość danych wynosiła od 1000 ms do 3000 ms, a w 11,92% przypadków ta wartość przekroczyła 3000 ms.

Centyle

Wskaźniki mogą też zawierać centyle przydatne do dodatkowej analizy. Raportujemy wartości konkretnych danych przy wybranym percentylu dla tych danych. Opierają się one na pełnym zbiorze dostępnych danych, a nie na ostatecznych zakresach danych, więc niekoniecznie muszą odpowiadać interpolowanemu percentylu, który opiera się na końcowym histogramie binarnym.

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

W tym przykładzie co najmniej 75% wczytań strony zostało zmierzonych przy użyciu wartości <= 2063.

Ułamki

Ułamki wskazują odsetek wczytań strony, które można oznaczyć w określony sposób. W tym przypadku wartości wskaźników są tymi etykietami.

Na przykład dane form_factors składają się z obiektu fractions z listą formatów (lub urządzeń), których dotyczy dane zapytanie:

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

W tym przypadku 3,77% wczytań stron odnotowano na komputerze, 2,88% na tablecie i 93,35% na telefonie, co daje 100% w sumie.

Typy wartości danych

Nazwa danych interfejsu CrUX API Typ danych Jednostki metryczne Agregacje statystyczne Dokumentacja
cumulative_layout_shift 2 miejsca po przecinku podwójnie zakodowane jako ciąg znaków bez jednostek histogram z 3 przedziałami, percentylu z p75 cls
first_contentful_paint int milisek. histogram z 3 przedziałami, percentylu z p75 FCP
first_input_delay
(wycofano)		 int milisek. histogram z 3 przedziałami, percentylu z p75 fid
interaction_to_next_paint int milisek. histogram z 3 przedziałami, percentylu z p75 INP
largest_contentful_paint int milisek. histogram z 3 przedziałami, percentylu z p75 lcp
experimental_time_to_first_byte int milisek. histogram z 3 przedziałami, percentylu z p75 ttfb
form_factors Liczba zmiennoprzecinkowa o 4 miejscach po przecinku percent, mapowanie z formatu na ułamek formaty
navigation_types Liczba zmiennoprzecinkowa o 4 miejscach po przecinku percent, mapowanie z typu nawigacji na ułamek typy nawigacji,

Mapowanie nazw wskaźników BigQuery

Nazwa danych interfejsu CrUX API Nazwa wskaźnika 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 nie dotyczy

Okres zbierania danych

Od października 2022 roku interfejs CrUX API zawiera obiekt collectionPeriod z polami firstDate i endDate wskazującymi daty rozpoczęcia i zakończenia okresu agregacji. Na przykład:

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

Dzięki temu łatwiej zrozumiesz, czy dane zostały już zaktualizowane na dany dzień, czy też zwracają takie same dane jak wczoraj.

Pamiętaj, że interfejs CrUX API jest opóźniony o około 2 dni, ponieważ czeka na pełne dane z danego dnia, a udostępnienie go w interfejsie API wymaga czasu na przetworzenie. Używana strefa czasowa to czas pacyficzny standardowy (PST), bez zmian w przypadku zmiany czasu na letni.

Przykładowe zapytania

Zapytania są przesyłane jako obiekty JSON za pomocą żądania POST wysyłanego do https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=[YOUR_API_KEY]", gdzie dane zapytania są obiektem JSON w treści POST:

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

Na przykład można ją wywołać ze strony curl za pomocą następującego wiersza poleceń (zastępując API_KEY kluczem):

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"]}'

Dane na poziomie strony są dostępne przez interfejs API dzięki przekazaniu w zapytaniu właściwości url zamiast origin:

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

Jeśli właściwość metrics nie jest skonfigurowana, zwracane będą wszystkie dostępne dane:

  • cumulative_layout_shift
  • first_contentful_paint
  • first_input_delay (wycofano)
  • interaction_to_next_paint
  • largest_contentful_paint
  • experimental_time_to_first_byte
  • navigation_types
  • form_factors (raportowany tylko wtedy, gdy w żądaniu nie określono żadnego formFactor)

Jeśli nie podasz żadnej wartości formFactor, wartości zostaną zebrane ze wszystkich formatów.

Więcej przykładowych zapytań znajdziesz w artykule Używanie interfejsu Chrome UX Report API.

Potok danych

Zbiór danych raportu CrUX jest przetwarzany za pomocą potoku w celu konsolidacji, agregacji i filtrowania danych przed udostępnieniem ich za pomocą interfejsu API.

Średnia krocząca

Dane w Raporcie na temat użytkowania Chrome to średnia krocząca danych zbiorczych z 28 dni. Oznacza to, że dane przedstawione w danym momencie w Raporcie na temat użytkowania Chrome to tak naprawdę dane z ostatnich 28 dni zebrane.

Przypomina to sposób, w jaki zbiór danych na temat użytkowania Chrome w BigQuery zbiera raporty miesięczne.

Codzienne aktualizacje

Dane są aktualizowane codziennie około 04:00 czasu UTC. Nie ma gwarancji jakości usług dla godzin aktualizacji. Jest ona uruchamiana codziennie w miarę naszych możliwości.

Schemat

Istnieje jeden punkt końcowy dla interfejsu CrUX API, który akceptuje żądania HTTP POST. Interfejs API zwraca element record, który zawiera co najmniej 1 element metrics odpowiadający danym o wydajności żądanego źródła lub strony.

Żądanie HTTP

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

Adres URL używa składni transkodowania gRPC.

Treść żądania

Treść żądania powinna zawierać dane o następującej strukturze:

{
  "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.
}
Pola
effectiveConnectionType

string

Efektywny typ połączenia to wymiar zapytania określający efektywną klasę sieci, do której mają należeć dane rekordu.

To pole używa wartości ["offline", "slow-2G", "2G", "3G", "4G"] zgodnie z specyfikacją interfejsu Network Information API

Uwaga: jeśli nie podasz efektywnego typu połączenia, zostanie zwrócony specjalny rekord z danymi zbiorczymi dotyczącymi wszystkich skutecznych typów połączeń.
formFactor

enum (FormFactor)

Format to wymiar zapytania określający klasę urządzenia, do której mają należeć dane rekordu.

To pole używa wartości DESKTOP, PHONE lub TABLET.

Uwaga: jeśli nie podasz formatu, wyświetli się specjalny rekord z danymi zbiorczymi dotyczącymi wszystkich formatów.
metrics[]

string

Wskaźniki, które powinny zostać uwzględnione w odpowiedzi. Jeśli nie podasz żadnej wartości, zwrócone zostaną wszystkie znalezione wskaźniki.

Dozwolone wartości: ["cumulative_layout_shift", "first_contentful_paint", "first_input_delay", "interaction_to_next_paint", "largest_contentful_paint", "experimental_time_to_first_byte"]
Pole sumy url_pattern. url_pattern to główny identyfikator wyszukiwania rekordów. Może być tylko jednym z tych typów:
origin

string

Pole „origin” url_pattern odnosi się do wzorca adresu URL, który jest źródłem witryny.

Przykłady: "https://example.com", "https://cloud.google.com".
url

string

Pole url_pattern url odnosi się do dowolnego adresu URL.

Przykłady: "https://example.com/, https://cloud.google.com/why-google-cloud/".

Aby na przykład zażądać maksymalnych wartości wyrenderowania treści na komputerach na stronie głównej dokumentacji dla deweloperów Chrome:

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

Treść odpowiedzi

Udane żądania zwracają odpowiedzi z obiektem record i urlNormalizationDetails w następującej strukturze:

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

Na przykład odpowiedź w poprzednim żądaniu może wyglądać tak:

{
  "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
      }
    }
  }
}

Klucz

Key określa wszystkie wymiary, które identyfikują ten rekord jako unikalny.

{
  "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.
}
Pola
formFactor

enum (FormFactor)

Format to klasa urządzenia, z której wszyscy użytkownicy uzyskali dostęp do witryny na potrzeby tego rekordu.

Jeśli format jest nieokreślony, zwracane są dane zbiorcze dotyczące wszystkich formatów.
effectiveConnectionType

string

Efektywny typ połączenia to ogólna klasa połączenia napotkana przez wszystkich użytkowników w przypadku tego rekordu. To pole używa wartości ["offline", "slow-2G", "2G", "3G", "4G"] zgodnie z informacjami podanymi na stronie https://wicg.github.io/netinfo/#effective-connection-types.

Jeśli efektywny typ połączenia jest nieokreślony, zwracane są dane zbiorcze dotyczące wszystkich skutecznych typów połączeń.
Pole sumy url_pattern. Wzorzec adresu URL to adres URL, którego dotyczy rekord. url_pattern może być tylko jedną z tych wartości:
origin

string

origin określa źródło, którego dotyczy ten rekord.

Uwaga: gdy określisz właściwość origin, dane dotyczące wczytywania w ramach tego źródła na wszystkich stronach są agregowane w postaci danych dotyczących wrażeń użytkowników na poziomie źródła.
url

string

url określa konkretny adres URL, którego dotyczy ten rekord.

Uwaga: jeśli określisz właściwość url, dane tylko dla tego konkretnego adresu URL będą agregowane.

Wskaźniki

Element metric to zbiór zagregowanych danych o wrażeniach użytkowników związanych z pojedynczym wskaźnikiem wydajności w internecie, takim jak pierwsze wyrenderowanie treści. Może on zawierać histogram podsumowujący rzeczywiste użytkowanie Chrome w postaci serii bins, konkretnych danych centylowych (np. P75) lub ułamków oznaczonych etykietami.

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

lub

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

object (Bin)

Histogram przedstawiający wrażenia użytkowników związane z określonym rodzajem danych. Histogram będzie zawierał co najmniej 1 przedział, a gęstości wszystkich z nich będą wynosić ~1.
percentiles

object (Percentiles)

Typowe przydatne centyle wskaźnika. Typ wartości centyli będzie taki sam jak typ wartości podany dla przedziału histogramu.
fractions

object (Fractions)

Ten obiekt zawiera ułamki oznaczone etykietami, których suma równa 1.

Ułamki są zaokrąglane do 4 miejsc po przecinku.

Przedział

bin to osobna część danych, obejmująca od początku do końca lub jeśli nie ma końca od początku do dodatniej nieskończoności.

Wartości początkowe i końcowe przedziału są określone w typie wartości reprezentowanych przez niego wartości. Na przykład pierwsze wyrenderowanie treści jest mierzone w milisekundach i wyświetlane jako liczba int, dlatego przedziały metryczne używają int32 jako typu początkowego i końcowego. Jednak skumulowane przesunięcie układu jest mierzone w ułamkach dziesiętnych bez jednostek i wyświetlane jako liczba dziesiętna zakodowana jako ciąg znaków, dlatego typy wartości w jego przedziałach danych będą używać ciągów znaków.

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

(integer | string)

Argument początek to początek koszyka danych.
end

(integer | string)

Argument koniec to koniec koszyka danych. Jeśli koniec nie jest podany, przedział ten nie ma końca i jest prawidłowy od początku do +inf.
density

number

Odsetek użytkowników, którzy napotkali wartość tego przedziału w przypadku danego rodzaju danych.

Gęstości są zaokrąglane do 4 miejsc po przecinku.

Centyle

Percentiles zawiera syntetyczne wartości danych w danym percentylu statystycznym. Służą do oszacowania wartości danych na podstawie odsetka użytkowników w stosunku do łącznej liczby użytkowników.

{
  "P75": value
}
Pola
p75

(integer | string)

W przypadku 75% przypadków wczytania strony dana wartość miała wartość mniejszą lub równą tej wartości.

Ułamki

Funkcja Fractions zawiera ułamki oznaczone etykietą, które dają razem ~1. Każda etykieta opisuje w jakiś sposób wczytywanie strony, więc przedstawiane w ten sposób wskaźniki można traktować jako generujące odrębne wartości zamiast wartości liczbowych, a ułamki pokazują, jak często mierzono konkretną odrębną wartość.

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

Podobnie jak wartości gęstości w pojemnikach histogramu, każdy element fraction jest liczbą 0.0 <= value <= 1.0, której suma równa się ok.1,0.

UrlNormalization

Obiekt reprezentujący działania normalizacji podejmowane w celu znormalizowania adresu URL, tak aby zwiększyć szansę na udane wyszukiwanie. Oto proste zmiany automatyczne wprowadzane podczas wyszukiwania podanych elementów url_pattern. Złożone działania, takie jak śledzenie przekierowań, nie są obsługiwane.

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

string

Pierwotny adres URL, którego dotyczyło żądanie, przed wykonaniem jakichkolwiek czynności związanych z normalizacją.
normalizedUrl

string

Adres URL po wykonaniu działań normalizacji. Jest to prawidłowy adres URL wrażeń użytkownika, który można wyszukać.

Ograniczenia liczby żądań

Interfejs CrUX API jest dostępny bez opłat do 150 zapytań na minutę na projekt Google Cloud. Ten limit oraz aktualne wykorzystanie możesz sprawdzić w Google Cloud Console. Taki duży limit powinien wystarczyć do większości zastosowań, a jego zwiększenie nie jest możliwe.