Interfejs API CrUX

Interfejs CrUX API zapewnia z krótkim 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żytkownika 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 Google Cloud API. 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 poniżej.

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.

Nagraj

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

Identyfikatory

Identyfikatory określają, jakich rekordów należy szukać. W przypadku CrUX te identyfikatory to strony internetowe i witryny.

Punkt początkowy

Jeśli identyfikator jest źródłem, wszystkie dane dotyczące wszystkich stron w tym źródle są agregowane. Załóżmy na przykład, że źródło http://www.example.com zawiera strony zgodnie z tą mapą witryny:

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

Oznacza to, że w przypadku zapytania w Raporcie na temat użytkowania Chrome o źródle ustawionym na http://www.example.com zwracane będą dane dotyczące stron http://www.example.com/, http://www.example.com/foo.html i http://www.example.com/bar.html, ponieważ są to wszystkie strony w tym źródle.

Adresy URL

Gdy identyfikatorem jest adres URL, zwracane są tylko dane dla tego konkretnego adresu. Jeszcze raz zwracam uwagę na mapę witryny źródła 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 o 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 agregowane są rekord. Na przykład format PHONE wskazuje, że rekord zawiera informacje o obciążeniach, które nastąpiły na urządzeniu mobilnym. Każdy wymiar będzie miał pewną liczbę wartości, a jego brak oznacza, że będzie on agregowany względem wszystkich wartości. Na przykład brak formatu oznacza, że rekord zawiera informacje o obciążeniach, które miały miejsce w przypadku dowolnego formatu.

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.

Typ skutecznego połączenia

Efektywny typ połączenia to szacowana jakość połączenia urządzenia podczas otwierania strony. To jest klasa ogólna z podziałem na: offline, slow-2G, 2G, 3G i 4G.

Dane

Dane rejestrujemy jako agregacje statystyczne na histogramach, percentylu i ułamkach.

Histogram

Gdy dane są przedstawione na histogramie, pokazujemy, jaki odsetek wczytań strony mieści się w poszczególnych zakresach tych danych.

Prosty histogram z trzech bin dla przykładowych danych wygląda tak:

{
  "histogram": [
    {
      "start": 0,
      "end": 1000,
      "density": 0.38179
    },
    {
      "start": 1000,
      "end": 3000,
      "density": 0.49905
    },
    {
      "start": 3000,
      "density": 0.11916
    }
  ]
}

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

Dodatkowo 49,905% wczytań stron miało wartość z zakresu od 1000 ms do 3000 ms, a 11,916% – powyżej 3000 ms.

Centyle

Wskaźniki mogą też zawierać percentyle, które mogą być przydatne na potrzeby dodatkowej analizy. Raportujemy konkretne wartości danych dla danego percentyla dla tych danych. Opierają się one na pełnym zbiorze dostępnych danych, a nie na ostatecznej grupie danych, więc niekoniecznie muszą odpowiadać percentylu interpolowanego opartemu na końcowym histogramie powiązanym.

{
  "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ściami wskaźników są te etykiety. Przykład:

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

W tym przypadku 3,77% wczytań stron zostało zmierzonych na komputerach, 2,88% na tabletach i 93,35% na telefonach, co daje 100% w sumie.

Typy wartości danych

Nazwa danych interfejsu CrUX API Typ danych Jednostki metryczne Agregacje statystyczne web.dev Dokumenty
cumulative_layout_shift podwójnie kodowane 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 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 Tttfb

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
form_factors nie dotyczy

Okres zbierania danych

Od października 2022 roku interfejs CrUX API zawiera obiekt collectionPeriod z polami firstDate i endDate, które określają daty rozpoczęcia i zakończenia okresu agregacji. Oto 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 sprawdzić, czy są one już zaktualizowane na dany dzień lub czy zwracają te same dane co wczoraj.

Pamiętaj, że interfejs CrUX API jest opóźniony o około 2 dni od dzisiejszej daty, ponieważ czeka na pełne dane z tego dnia, a udostępnianie go w interfejsie API wymaga trochę czasu na przetworzenie. Użyta strefa czasowa to czas pacyficzny standardowy (PST) bez zmian czasu.

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]", w którym dane zapytania są obiektem JSON w treści POST, np.

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

Na przykład można wywołać tę funkcję z curl za pomocą 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"]}'

Dostęp do danych na poziomie strony można uzyskać przez interfejs API, przekazując w zapytaniu właściwość url, a nie 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
  • interaction_to_next_paint
  • largest_contentful_paint
  • experimental_time_to_first_byte
  • form_factors (raportowane tylko wtedy, gdy w żądaniu nie określono żadnego parametru formFactor)

Jeśli nie podasz 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 na temat użytkowania Chrome jest przetwarzany za pomocą potoku w celu konsolidowania, agregowania 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 z 28 dni obejmująca dane zbiorcze. Oznacza to, że dane przedstawione w danym momencie w Raporcie na temat użytkowania Chrome to w rzeczywistości dane z ostatnich 28 dni zebrane.

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

Codzienne aktualizacje

Dane są aktualizowane codziennie około 04:00 czasu UTC. Nie ma gwarancji jakości usług co do godzin aktualizacji. Uruchamiamy ją każdego dnia w miarę możliwości.

Schemat

Interfejs API CrUX ma 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, który określa efektywną klasę sieci, do której powinny należeć dane rekordu.

To pole używa wartości ["offline", "slow-2G", "2G", "3G", "4G"] określonych w specyfikacji interfejsu Network Information API

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

formFactor

enum (FormFactor)

Format to wymiar zapytania, który określa 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, zostanie zwrócony 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 żadnych danych, 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. Wzorzec adresu URL jest głównym identyfikatorem wyszukiwania rekordów. Może to być jeden z wielu typów wartości. url_pattern może mieć tylko jedną z tych wartości:
origin

string

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

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

url

string

Wzorzec adresu URL „url” odnosi się do wzorca adresu URL, który jest dowolnym dowolnym adresem 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

Pomyślne żądania zwracania 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 powyższym żą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.98148451581189577
          },
          {
            "start": 2500,
            "end": 4000,
            "density": 0.010814353596591841
          },
          {
            "start": 4000,
            "density": 0.0077011305915124116
          }
        ],
        "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 do uzyskania dostępu do witryny dla danego rekordu.

Jeśli format jest nieokreślony, zwracane są dane zbiorcze ze 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 skuteczny typ połączenia jest nieokreślony, zwracane są dane zbiorcze ze wszystkich efektywnych typów połączeń.

Pole sumy url_pattern. Wzorzec adresu URL to adres URL, którego dotyczy rekord. url_pattern może mieć tylko jedną z tych wartości:
origin

string

Źródło określa źródło, dla którego przeznaczony jest ten rekord.

Uwaga: podczas określania źródła dane dotyczące wczytań z tego źródła na wszystkich stronach są agregowane w dane o wrażeniach użytkowników na poziomie źródła.

url

string

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

Uwaga: jeśli podasz „url”, agregujemy dane tylko z tego konkretnego adresu URL.

Wskaźniki

metric to zbiór zbiorczych danych o wrażeniach użytkownika związanych z pojedynczym wskaźnikiem wydajności witryny, takim jak pierwsze wyrenderowanie treści. Może on zawierać histogram podsumowujący rzeczywiste korzystanie z 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 wrażeń użytkowników związanych z rodzajem danych. Histogram będzie miał co najmniej 1 przedział, a gęstość wszystkich przedziałów będzie wynosić ~1.

percentiles

object (Percentiles)

Najpopularniejsze przydatne percentyle danych. 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 etykietami, których suma daje ~1.

Przedział

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

Wartości początkowa i końcowa przedziału są określone jako typ wartości reprezentowanego przez niego wskaźnika. Na przykład pierwsze wyrenderowanie treści jest mierzone w milisekundach i wyświetlane jako liczba całkowita, dlatego przedziały metryczne używają ciągu int32s jako typu początkowego i końcowego. Łączne przesunięcie układu jest jednak mierzone przy użyciu ułamków dziesiętnych bez jednostek i jest ujawniane jako zapis dziesiętny zakodowany jako ciąg znaków, więc typ wartości w jego przedziałach danych będzie używać ciągów tekstowych.

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

value (Value format)

Początek to początek kosza danych.

end

value (Value format)

Argument koniec to koniec kosza danych. Jeśli pole End nie jest wypełnione, oznacza to, że przedział 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.

Centyle

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

{
  "P75": value
}
Pola
p75

value (Value format)

U 75% użytkowników określone dane wystąpiły na poziomie tej lub niższej wartości.

Ułamki

Fractions zawiera ułamki oznaczone etykietami o sumie ~1. Każda etykieta opisuje w jakiś sposób wczytanie strony, dlatego przedstawione w ten sposób wskaźniki mogą generować różne wartości zamiast wartości liczbowych, a ułamki wskazują, jak często była mierzona dana unikalna wartość.

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

Podobnie jak w przypadku wartości gęstości w pojachach histogramu, każdy element fraction jest liczbą 0.0 <= value <= 1.0, a suma równa tej wartości wynosi ok.1,0.

UrlNormalization

Obiekt reprezentujący działania normalizacji podejmowane w celu znormalizowania adresu URL i zwiększenia szansy na pomyślne wyszukiwanie. To są proste automatyczne zmiany wprowadzane podczas wyszukiwania podanego elementu url_pattern, którego wykonanie może się wiązać z błędami. 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 działań związanych z normalizacją.

normalizedUrl

string

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

Ograniczenia liczby żądań

Interfejs CrUX API może zawierać maksymalnie 150 zapytań na minutę na projekt Google Cloud, który jest oferowany bezpłatnie. Ten limit i bieżące wykorzystanie możesz sprawdzić w konsoli Google Cloud. Ten duży limit powinien wystarczać w większości przypadków użycia, a obecnie nie można zapłacić za jego zwiększenie.