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 są wyrażone na histogramie, który przedstawia odsetek użytkowników, którzy mieli odpowiednią wartość proporcjonalnie do wszystkich.

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 38,179% użytkowników korzysta z przykładowych danych z zakresu od 0 ms do 1000 ms. Jednostki metryczne nie są ujęte na tym histogramie. W tym przypadku przyjmujemy milisekundy.

Poza tym 49,905% użytkowników ma wartość z zakresu od 1000 ms do 3000 ms, a 11,916% użytkowników ma wartość większą niż 3000 ms.

Wskaźniki będą też zawierać percentyle, które mogą być przydatne na potrzeby dodatkowej analizy.

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

Te percentyle mogą pokazywać określone 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 odpowiadają danemu percentylu interpolowanemu opartemu na końcowym histogramie powiązanym.

Typy wartości danych

Mapowanie nazw wskaźników BigQuery

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

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 lub PHONE. 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 danych o wrażeniach użytkownika związanych z pojedynczym wskaźnikiem wydajności witryny, np. pierwsze wyrenderowanie treści. Zawiera on histogram podsumowujący rzeczywiste korzystanie z Chrome w postaci serii bins.

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

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.

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.

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.