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.

Typowy przypadek użycia

Interfejs CrUX API umożliwia wysyłanie zapytań o wskaźniki dotyczące wrażeń użytkowników w przypadku określonego identyfikatora URI, np. „Pobierz wskaźniki dotyczące źródła https://example.com”.

Klucz interfejsu API CrUX

Korzystanie z interfejsu CrUX API wymaga klucza interfejsu Google Cloud API. Możesz go utworzyć na stronie Credentials (Dane logowania) i udostępnić go do korzystania z 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

W tej sekcji znajdziesz 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 w źródle http://www.example.com były strony określone 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 jest ustawiony na adres URL o wartości http://www.example.com/foo.html, zwracane są tylko dane dotyczące tej strony.

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.

Wskaźnik

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ą podwójnie zakodowane jako ciąg znaków, dlatego 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 postaci histogramu, pokazujemy odsetek wczytań stron mieszczących się w konkretnych zakresach tych danych.

Prosty histogram z trzema binami dla przykładowego wskaźnika 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 były mierzone w czasie od 0 do 1000 ms. Ten histogram nie zawiera jednostek danych, w tym przypadku przyjmujemy milisekundy.

Dodatkowo w 49,91% przypadków ładowania strony wartość danych mieściła się w przedziale od 1000 do 3000 ms, a w przypadku 11,92% – powyżej 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. Opierają się one na pełnym zbiorze dostępnych danych, a nie na ostatecznych danych powiązanych, dlatego nie muszą być zgodne z interpolowanym percentylem opartym na ostatecznym histogramie binarnym.

{
  "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 wskaźnik form_factors składa 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 wynik 100%.

Typy wartości danych

Nazwa wskaźnika interfejsu CrUX API 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 milisekund histogram z 3 przedziałami, percentyle z p75 fcp
first_input_delay
(wycofano)		 int milisekund histogram z 3 przedziałami, percentyle z p75 fid
interaction_to_next_paint int milisekund histogram z 3 przedziałami, percentyle z p75 Inp
largest_contentful_paint int milisekund histogram z 3 przedziałami, percentyle z p75 LCP
experimental_time_to_first_byte int milisekund 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 milisekund 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
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
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
  • 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 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 przez potok w celu konsolidacji, 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 dotyczących czasu aktualizacji. Jest ona przeprowadzana z najwyższą starannością każdego dnia.

Schemat

Interfejs CrUX API przyjmuje jeden punkt końcowy, który akceptuje żądania HTTP POST. Interfejs API zwraca wartość record, która 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 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.

To 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", "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 rekordu. Może to być tylko 1 z tych wartości:
origin

string

Pole „origin” elementu url_pattern odnosi się do wzorca adresu URL, który określa pochodzenie 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 efektywny typ połączenia nie jest określony, zwracane są dane zbiorcze ze wszystkich aktywnych 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.

Wskaźniki

metric to zbiór zagregowanych danych o wrażeniach użytkownika na potrzeby pojedynczego wskaźnika wydajności witryny, np. pierwszego wyrenderowania treści. Może on zawierać histogram podsumowania rzeczywistego użytkowania Chrome w postaci serii bins, danych dotyczących określonych centyli (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 ułamki oznaczone etykietą, które dają sumę ok. 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 metryczne będą używać int32 jako typów rozpoczęcia i zakończenia. Skumulowane przesunięcie układu jest jednak mierzone w bezjednostkowych ułamkach 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 75% przypadków wczytania strony wystąpiła wartość o wartości nieprzekraczającej tej wartości.

Ułamki

Fractions zawiera ułamki oznaczone etykietami, które dają sumę ok. 1. Każda etykieta opisuje w jakiś sposób wczytanie strony, dlatego dane reprezentowane w ten sposób można traktować jako generujące różne wartości, a nie wartości liczbowe, a ułamki pokazują, jak często mierzono daną odrębną 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 to liczba 0.0 <= value <= 1.0, a suma ich sumy wynosi 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.