Interfejs API CrUX

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

Wypróbuj

Typowy przypadek użycia

Interfejs CrUX API umożliwia wysyłanie zapytań o dane o ocenie funkcjonalności dotyczące konkretnego adresu URI, np. „Pobierz dane o źródle https://example.com”.

Klucz interfejsu API CrUX

Korzystanie z interfejsu CrUX API wymaga klucza interfejsu Google Cloud API udostępnionego na potrzeby Chrome UX Report API.

Uzyskiwanie i używanie klucza interfejsu API

Kup klucz

Możesz też utworzyć konto na stronie Dane logowania.

Gdy uzyskasz klucz interfejsu API, aplikacja może dołączać parametr zapytania key=yourAPIKey do wszystkich adresów URL żądań.

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

Zobacz Przykładowe zapytania.

Model danych

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

Rekord

Oddzielna informacja o stronie lub witrynie. Rekord może zawierać dane, które są charakterystyczne dla danego identyfikatora i konkretnej kombinacji wymiarów. Rekord może zawierać informacje dotyczące jednego lub większej liczby wskaźników.

Identyfikatory

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

Punkt początkowy

Gdy identyfikator jest źródłem, wszystkie dane ze wszystkich stron w tym źródle są agregowane razem. Załóżmy na przykład, że domena http://www.example.com zawierała strony o takim układzie, jak w tej mapie witryny:

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

Oznacza to, że w wyniku wysłania zapytania do raportu na temat użytkowania Chrome z źródłem ustawionym na http://www.example.com zostaną zwrócone dane dotyczące witryn http://www.example.com/, http://www.example.com/foo.html i http://www.example.com/bar.html, które zostaną zagregowane, ponieważ to są wszystkie strony z tego źródła.

Adresy URL

Gdy identyfikatorem jest adres URL, zwracane są tylko dane dotyczące tego konkretnego adresu URL. Szukam mapy witryny źródłowej http://www.example.com:

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

Jeśli identyfikator ma wartość http://www.example.com/foo.html, zwracane są tylko dane o tej stronie.

Wymiary

Wymiary określają konkretną grupę danych, na podstawie których jest agregowany rekord. Format PHONE wskazuje, że rekord zawiera informacje o wczytywaniu danych na urządzeniu mobilnym. Każdy wymiar będzie miał pewną liczbę wartości, a brak określenia tego wymiaru spowoduje, że będzie on agregowany we wszystkich wartościach. Na przykład brak formatu oznacza, że rekord zawiera informacje o wczytaniach, które miały miejsce na dowolnym formacie.

Rodzaj obudowy

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

Efektywny typ połączenia

Efektywny typ połączenia to szacowana jakość połączenia urządzenia podczas otwierania strony. Zajęcia ogólne podzielone na te kategorie: offline, slow-2G, 2G, 3G i 4G.

Dane

Dane są raportowane w postaci agregacji statystycznych 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ą zakodowane podwójnie jako ciąg znaków, więc nie są one uznawane za liczby zmiennoprzecinkowe i są raportowane z dokładnością do 2 miejsc po przecinku).

Histogram

Gdy dane są wyrażone w histogramie, pokazujemy procentowe wczytań strony przypadające określone zakresy tego wskaźnika.

Histogram trzech przedziałów dla 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 zakresie od 0 ms do 1000 ms. Histogram nie zawiera jednostek danych, w tym przypadku zakładamy milisekundy.

Dodatkowo w 49,91% przypadków wartość danych w przypadku wczytywania strony mieściła się w zakresie 1000–3000 ms, a w 11,92% przypadków była większa niż 3000 ms.

Centyl

Wskaźniki mogą też zawierać centyle, które mogą być przydatne przy dodatkowej analizie. Raportujemy konkretne wartości danych przy określonym percentylu. Są one oparte na pełnym zbiorze dostępnych danych, a nie na ostatecznym zbiorze danych więc nie muszą być zgodne z interpolowanym percentylem opartym na ostatecznego histogramu bind.

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

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

Ułamki

Ułamki określają procent przypadków wczytania strony, które można oznaczyć w określony sposób. W tym przypadku wartościami danych są te etykiety.

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

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

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

Typy wartości danych

Nazwa wskaźnika w interfejsie API CrUX	Typ danych	Jednostki metryczne	Agregacje statystyczne	Dokumentacja
cumulative_layout_shift	2 miejsca dziesiętne zakodowane podwójnie jako ciąg znaków	bez jednostek	histogram z 3 przedziałami, percentyle z p75	cls
first_contentful_paint	int,	milisekundy	histogram z 3 przedziałami, percentyle z p75	fcp
interaction_to_next_paint	int,	milisekundy	histogram z 3 przedziałami, percentyle z p75	inp
largest_contentful_paint	int,	milisekundy	histogram z 3 przedziałami, percentyle z p75	lcp
experimental_time_to_first_byte	int,	milisekundy	histogram z 3 przedziałami, percentyle z p75	ttfb
form_factors	Liczba zmiennoprzecinkowa z czterema miejscami po przecinku	procent	mapowanie z formatu na ułamek	formaty
navigation_types	Liczba zmiennoprzecinkowa z czterema miejscami po przecinku	procent	mapowanie z typu nawigacji na ułamek	typów nawigacji
round_trip_time	int,	milisekundy	percentyle z p75	rtt

Mapowanie nazwy wskaźnika BigQuery

Nazwa wskaźnika interfejsu CrUX API	Nazwa wskaźnika BigQuery
cumulative_layout_shift	layout_instability.cumulative_layout_shift
first_contentful_paint	first_contentful_paint
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
round_trip_time	nie dotyczy

Okres zbierania danych

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

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

Dzięki temu możesz lepiej zrozumieć dane i dowiedzieć się, czy w danym dniu zostały już zaktualizowane, czy zwracają te same dane co wczoraj.

Pamiętaj, że interfejs CrUX API jest opóźniony o około 2 dni w stosunku do bieżącej daty, ponieważ czeka na zebranie kompletnych danych z danego dnia. Zanim zostanie on udostępniony w interfejsie API, może minąć trochę czasu na ich przetworzenie. Użyta 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 do https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=[YOUR_API_KEY]" z danymi zapytań w postaci obiektu JSON w treści POST:

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

Można je na przykład wywołać z curl przy użyciu tego wiersza poleceń (zastępując API_KEY swoim 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 w interfejsie API poprzez przekazanie 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 są wszystkie dostępne dane:

• cumulative_layout_shift
• first_contentful_paint
• 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 elementu formFactor)

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

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

Potok danych

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

Średnia krocząca

Dane w Raporcie na temat użytkowania Chrome to średnia krocząca z 28 dni. Oznacza to, że dane przedstawiane w Raporcie na temat użytkowania Chrome w danym momencie są sumowanymi danymi z ostatnich 28 dni.

Podobnie jest w przypadku zbioru danych na temat użytkowania Chrome w BigQuery, który zbiera raporty miesięczne.

Codzienne aktualizacje

Dane są aktualizowane codziennie około godziny 4:00 czasu UTC. Nie ma gwarancji jakości usług dla czasu aktualizacji. jest codziennie przeprowadzany z możliwie największą dokładnością.

Schemat

Interfejs CrUX API przyjmuje jeden punkt końcowy, który akceptuje żądania HTTP POST. Interfejs API zwraca record, który zawiera co najmniej 1 element metrics odpowiadający danym o skuteczności dotyczącym żą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 powinny należeć dane rekordu. To pole używa wartości ["offline", "slow-2G", "2G", "3G", "4G"] zgodnie ze specyfikacją interfejsu Network Information API. Uwaga: jeśli nie określisz efektywnego typu połączenia, zostanie zwrócony specjalny rekord ze zbiorczymi danymi dla wszystkich aktywnych typów połączeń.
formFactor	enum (FormFactor) Format to wymiar zapytania określający klasę urządzenia, do której powinny należeć dane rekordu. Pole używa wartości DESKTOP, PHONE, lub TABLET. Uwaga: jeśli nie podasz formatu, zostanie zwrócony specjalny rekord ze zbiorczymi danymi dla wszystkich formatów.
metrics[]	string Dane, które powinny znaleźć się 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", "interaction_to_next_paint", "largest_contentful_paint", "experimental_time_to_first_byte"]
Pole sumy url_pattern. url_pattern to główny identyfikator wyszukiwania rekordu. Może to być tylko 1 z tych wartości:
origin	string „Źródło” url_pattern to wzór adresu URL, który jest źródłem witryny. Przykłady: "https://example.com", "https://cloud.google.com"
url	string Element url_pattern url odnosi się do wzorca adresu URL, którym jest dowolny adres URL. Przykłady: "https://example.com/, https://cloud.google.com/why-google-cloud/"

Aby na przykład zażądać największych wartości wyrenderowania treści na komputery na stronie głównej dokumentacji dla programistów Chrome:

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

Treść odpowiedzi

Żądania zakończone powodzeniem zwracają odpowiedzi z obiektem record i obiektem urlNormalizationDetails o następującej strukturze:

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

Odpowiedź na treść poprzedniego żądania może na przykład 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, której wszyscy użytkownicy użyli, aby uzyskać dostęp do witryny z tym rekordem. Jeśli format nie jest określony, zostaną zwrócone dane zbiorcze ze wszystkich formatów.
effectiveConnectionType	string Efektywny typ połączenia to ogólna klasa połączenia napotkana w przypadku tego rekordu u wszystkich użytkowników. To pole używa wartości [„offline”, „slow-2G”, „2G”, „3G”, „4G"] zgodnie z opisem na tej stronie: https://wicg.github.io/netinfo/#effective-connection-types Jeśli nie określisz skutecznego typu połączenia, zwrócone zostaną zagregowane dane dotyczące wszystkich skutecznych typów połączeń.
Pole sumy url_pattern. Wzorzec adresu URL to adres URL, do którego odnosi się rekord. url_pattern może mieć tylko jedną z tych wartości:
origin	string origin określa źródło, dla którego jest przeznaczony ten rekord. Uwaga: przy określaniu origin dane dotyczące wczytywania w tym punkcie początkowym na wszystkich stronach są zbierane w ramach 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: w przypadku parametru url zostaną zagregowane tylko dane dotyczące tego konkretnego adresu URL.

Dane

metric to zestaw zagregowanych danych dotyczących wygody korzystania z pojedynczego wskaźnika wydajności strony internetowej, np. pierwszego wyrenderowania treści. Może zawierać histogram podsumowania rzeczywistego użytkowania Chrome w postaci serii bins, danych centyliowych (np. p75) lub może zawierać ułamki oznaczone etykietami.

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

lub

{
  "fractions": {
    object (Fractions)
  }
}

Pola
histogram[]	object (Bin) Histogram przedstawiający wrażenia użytkownika w przypadku danego wskaźnika. Histogram będzie zawierał co najmniej jeden przedział, a gęstość wszystkich przedziałów będzie wynosić ~1.
percentiles	object (Percentiles) Typowe przydatne centyle wskaźnika. Typ wartości percentyli będzie taki sam jak typy wartości podane dla przedziałów histogramu.
fractions	object (Fractions) Ten obiekt zawiera cząstki z oznaczeniem, których suma wynosi około 1. Ułamki są zaokrąglane do 4 miejsc po przecinku.

Przedział

Pole bin to odrębny fragment danych rozciągających się od początku do końca lub jeśli nie ma podanego końca od początku do dodatniej nieskończoności.

Początek i koniec przedziału są podane w typie wartości reprezentowanego przez niego wskaźnika. Na przykład pierwsze wyrenderowanie treści jest mierzone w milisekundach i wyświetlane jako liczby całkowite, dlatego jego przedziały wskaźników będą używały int32 jako typów rozpoczęcia i zakończenia. Skumulowane przesunięcie układu jest jednak mierzone w postaci ułamków dziesiętnych i przedstawia je jako ciąg znaków zakodowany w postaci dziesiętnej, dlatego jego typy danych będą zawierać ciągi tekstowe.

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

Pola
start	(integer | string) Początek to początek przedziału danych.
end	(integer | string) Argument koniec wskazuje koniec przedziału danych. Jeśli pole end nie jest wypełnione, przedział nie ma końca i jest prawidłowy od początku do +inf.
density	number Odsetek użytkowników, u których wystąpiła wartość przedziału w przypadku danego rodzaju danych. Gęstości są zaokrąglane do 4 miejsc po przecinku.

Centyl

Percentiles zawiera syntetyczne wartości danych dla danego centyla statystycznego. Służą do szacowania wartości danych w odniesieniu do odsetka użytkowników w stosunku do łącznej liczby użytkowników.

{
  "P75": value
}

Pola
p75	(integer | string) W przypadku 75% wczytywania stron wystąpiła wartość równa tej wartości lub mniejsza.

Ułamki

Fractions zawiera ułamki oznaczone etykietami, które dają sumę ok. 1. Każda etykieta opisuje wczytuje się strona, więc reprezentowane w ten sposób dane można traktować jako generuje różne wartości zamiast wartości liczbowych, a ułamki są wyrażone częstotliwość, z jaką mierzona jest dana odrębna wartość.

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

Podobnie jak wartości gęstości w przedziałach histogramu, każdy element fraction jest liczbą 0.0 <= value <= 1.0 i dają łącznie ok.1, 0.

UrlNormalization

Obiekt reprezentujący działania normalizacji wykonane w celu normalizacji adresu URL w celu zwiększenia szansy na pomyślne wyszukiwanie. To proste automatyczne zmiany wprowadzane podczas wyszukiwania podanego elementu url_pattern, który zwykle kończy się niepowodzeniem. Złożone działania, takie jak śledzenie przekierowań, nie są obsługiwane.

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

Pola
originalUrl	string Pierwotny żądany adres URL przed działaniami normalizacji.
normalizedUrl	string Adres URL po wszystkich działaniach normalizacji. Jest to prawidłowy adres URL związany z wrażeniami użytkownika, który można łatwo wyszukać.

Ograniczenia liczby żądań

Interfejs CrUX API jest dostępny bezpłatnie do 150 zapytań na minutę na każdy projekt Google Cloud. Ten limit oraz informacje o bieżącym wykorzystaniu znajdziesz w Google Cloud Console. Ten wysoki limit powinien być wystarczający w większości przypadków użycia. Nie ma możliwości płacenia za zwiększenie limitu.