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 żadnegoformFactor
)
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 |
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 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 |
Format to wymiar zapytania określający klasę urządzenia, do której mają należeć dane rekordu. To pole używa wartości Uwaga: jeśli nie podasz formatu, wyświetli się specjalny rekord z danymi zbiorczymi dotyczącymi wszystkich formatów. |
metrics[] |
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: |
Pole sumy url_ . url_pattern to główny identyfikator wyszukiwania rekordów. Może być tylko jednym z tych typów: |
|
origin |
Pole „origin” Przykłady: |
url |
Pole Przykłady: |
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 |
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 |
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_ . Wzorzec adresu URL to adres URL, którego dotyczy rekord. url_ może być tylko jedną z tych wartości: |
|
origin |
Uwaga: gdy określisz właściwość |
url |
Uwaga: jeśli określisz właściwość |
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[] |
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 |
Typowe przydatne centyle wskaźnika. Typ wartości centyli będzie taki sam jak typ wartości podany dla przedziału histogramu. |
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 |
Argument początek to początek koszyka danych. |
end |
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 |
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 |
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 |
Pierwotny adres URL, którego dotyczyło żądanie, przed wykonaniem jakichkolwiek czynności związanych z normalizacją. |
normalizedUrl |
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.