Interfejs API CrUX

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

Wypróbuj

Częsty przypadek użycia

Interfejs CrUX API umożliwia wysyłanie zapytań o dane dotyczące wygody użytkowników w przypadku konkretnego identyfikatora 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 udostępnionego na potrzeby Chrome UX Report API.

Uzyskiwanie i używanie klucza interfejsu API

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

Gdy masz już klucz interfejsu API, Twoja 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

W tej sekcji opisano strukturę danych w żądaniach i odpowiedziach.

Nagraj

Oddzielna informacja o stronie lub witrynie. Rekord może zawierać dane, które są specyficzne dla identyfikatora i określonej kombinacji wymiarów. Rekord może zawierać dane dotyczące co najmniej 1 rodzaju danych.

Identyfikatory

Identyfikatory określają, które rekordy mają być wyszukiwane. W CrUX tymi identyfikatorami są strony i witryny.

Punkt początkowy

Jeśli identyfikatorem jest źródło, 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 rozmieszczone zgodnie z tą mapą 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 ze źródłem ustawionym na http://www.example.com zostaną zwrócone dane dotyczące stron http://www.example.com/, http://www.example.com/foo.html i http://www.example.com/bar.html, które zostaną zagregowane, 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. Spójrzmy jeszcze raz na 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, według której agregowany jest rekord. Na przykład format PHONE wskazuje, że rekord zawiera informacje o wczytaniach, które miały miejsce na urządzeniu mobilnym. Każdy wymiar będzie miał określoną liczbę wartości, a brak określenia tego wymiaru będzie oznaczał, że wymiar jest agregowany we wszystkich wartościach. Jeśli na przykład nie określisz formatu, rekord będzie zawierać informacje o wczytywaniu na dowolnym formacie.

Format

Klasa urządzenia, którego użytkownik użył do przejścia na stronę. Jest to ogólna klasa urządzeń podzielona na PHONE, TABLET i DESKTOP.

Wskaźnik

Dane raportujemy jako agregacje statystyczne w histogramach, percentylach i ułamkach.

Wartości zmiennoprzecinkowe są zaokrąglane do 4 miejsc po przecinku (pamiętaj, że dane cumulative_layout_shift to liczby zmiennoprzecinkowe podwójnej precyzji zakodowane jako ciąg znaków, więc nie są traktowane jako liczby zmiennoprzecinkowe i są raportowane do 2 miejsc po przecinku w ciągu znaków).

Histogram

Gdy dane są przedstawione na histogramie, pokazujemy odsetek wczytań strony mieszczących się w określonych zakresach dla tych danych.

Histogram z 3 przedziałami 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ładowy wskaźnik został zmierzony w zakresie od 0 ms do 1000 ms. Ten histogram nie zawiera jednostek danych. W tym przypadku przyjmiemy, że są to milisekundy.

Dodatkowo w przypadku 49,91% wczytań strony wartość danych wynosiła od 1000 ms do 3000 ms, a w przypadku 11,92% – powyżej 3000 ms.

Percentyle

Dane mogą też zawierać percentyle, które mogą być przydatne do dodatkowej analizy. Podajemy konkretne wartości danych dla danego percentyla. Są one oparte na pełnym zestawie dostępnych danych, a nie na ostatecznych danych pogrupowanych, więc nie muszą odpowiadać interpolowanemu percentylowi opartemu na ostatecznym histogramie pogrupowanym.

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

W tym przykładzie co najmniej 75% wczytań strony zostało zmierzonych z wartością danych <= 2063.

Ułamki

Ułamki wskazują odsetek wczytań 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, który zawiera listę formatów (lub urządzeń) objętych danym zapytaniem:

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

W tym przypadku 3,77% wczytań strony zostało zmierzonych na komputerze, 2,88% na tablecie, a 93,35% na telefonie, co daje łącznie 100%.

Typy wartości danych

Mapowanie nazw danych BigQuery

Okres zbierania danych

Od października 2022 r. interfejs CrUX API zawiera obiekt collectionPeriod z polami firstDate i endDate, które reprezentują 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żna lepiej zrozumieć dane i dowiedzieć się, czy zostały już zaktualizowane w danym dniu, czy też są takie same jak poprzedniego dnia.

Okres zbierania danych jest też dostępny w PageSpeed Insights:

Dodatkowo collectionPeriod zawsze będzie wyświetlać 28 dni, nawet jeśli dane nie obejmują pełnych 28 dni (np. jeśli strona została uruchomiona mniej niż 28 dni temu). collectionPeriod to okres, w którym dane CrUX zostały zagregowane, a niekoniecznie okres, który te dane reprezentują.

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 zapytania jako obiektem JSON w treści żądania POST:

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

Można go na przykład wywołać z curl za pomocą tego wiersza poleceń (zastąp 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 przez interfejs API, gdy w zapytaniu przekażesz właściwość 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 ustawiona, zwracane są wszystkie dostępne dane:

• cumulative_layout_shift
• first_contentful_paint
• interaction_to_next_paint
• largest_contentful_paint
• experimental_cumulative_layout_shift_with_softnavs
• experimental_first_contentful_paint_with_softnavs
• experimental_interaction_to_next_paint_with_softnavs
• experimental_largest_contentful_paint_with_softnavs
• experimental_navigation_types_with_softnavs
• experimental_time_to_first_byte
• largest_contentful_paint_resource_type
• largest_contentful_paint_image_time_to_first_byte
• largest_contentful_paint_image_resource_load_delay
• largest_contentful_paint_image_resource_load_duration
• largest_contentful_paint_image_element_render_delay
• navigation_types
• round_trip_time
• form_factors (raportowane tylko wtedy, gdy w żądaniu nie podano parametru formFactor)
• experimental_ad_count (raportowane tylko w przypadku stron uwzględnionych w danych o reklamach)
• experimental_ad_density (raportowane tylko w przypadku stron uwzględnionych w danych o reklamach)
• experimental_ad_cpu (raportowane tylko w przypadku stron uwzględnionych w danych o reklamach)
• experimental_ad_kilobytes (raportowane tylko w przypadku stron uwzględnionych w danych o reklamach)

Jeśli nie podasz wartości formFactor, wartości zostaną zagregowane we wszystkich formatach.

Więcej przykładowych zapytań znajdziesz w artykule Korzystanie z interfejsu Raport na temat użytkowania Chrome API.

Potok danych

Zbiór danych CrUX jest przetwarzany przez potok w celu konsolidacji, agregacji i filtrowania danych, zanim zostaną one udostępnione za pomocą interfejsu API.

Średnia krocząca

Dane w raporcie na temat użytkowania Chrome to średnia krocząca z 28 dni zagregowanych danych. Oznacza to, że dane prezentowane w raporcie na temat użytkowania Chrome w danym momencie są w rzeczywistości danymi z ostatnich 28 dni.

Jest to podobne do sposobu, w jaki zbiór danych CrUX w BigQuery agreguje raporty miesięczne.

Aktualizacje codzienne

Dane są aktualizowane codziennie około godziny 4:00 czasu UTC. Nie ma gwarancji jakości usług dotyczącej czasu aktualizacji. Jest ona przeprowadzana codziennie w miarę możliwości.

Schemat

Interfejs CrUX API ma jeden punkt końcowy, który akceptuje żądania HTTP POST. Interfejs API zwraca obiekt record, który zawiera co najmniej 1 obiekt metrics odpowiadający danym o skuteczności żądanego źródła lub żądanej 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:

{
  "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.
}

Aby na przykład poprosić o wartości największego wyrenderowania treści na komputerze dla strony głównej dokumentacji dla deweloperów Chrome:

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

Treść odpowiedzi

Pomyślne żądania zwracają odpowiedzi z obiektem record i urlNormalizationDetails w tej strukturze:

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

Na przykład odpowiedź na treść żądania 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 definiuje wszystkie wymiary, które identyfikują ten rekord jako unikalny.

{
  "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.
}

Dane

metric to zestaw zagregowanych danych o wrażeniach użytkowników dotyczących pojedynczego wskaźnika wydajności sieci, np. pierwszego wyrenderowania treści. Może zawierać histogram podsumowujący rzeczywiste wykorzystanie Chrome jako serię bins, dane dotyczące określonych percentyli (np. p75) lub oznaczone etykietami ułamki.

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

lub

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

Przedział

bin to odrębna część danych obejmująca okres od początku do końca lub, jeśli nie podano końca, od początku do nieskończoności.

Wartości początkowa i końcowa przedziału są podawane w typie wartości danych, które reprezentuje. Na przykład pierwsze wyrenderowanie treści jest mierzone w milisekundach i wyświetlane jako liczba całkowita, więc jego przedziały danych będą używać typu int32 dla typów początkowych i końcowych. Skumulowane przesunięcie układu jest jednak mierzone w ułamkach dziesiętnych bez jednostek i jest podawane jako ułamek dziesiętny zakodowany jako ciąg znaków, dlatego jego przedziały danych będą używać ciągów znaków jako typu wartości.

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

Percentyle

Percentiles zawiera syntetyczne wartości danych w danym percentylu statystycznym. Służą one do szacowania wartości danych, która dotyczy określonego odsetka użytkowników z łącznej liczby użytkowników.

{
  "P75": value
}

Ułamki

Fractions zawiera oznaczone etykietami ułamki, które sumują się do ~1. Każda etykieta w jakiś sposób opisuje wczytanie strony, więc dane przedstawione w ten sposób można traktować jako generujące odrębne wartości, a nie wartości liczbowe, a ułamki wyrażają, 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 przedziałach histogramu, każda wartość fraction jest liczbą 0.0 <= value <= 1.0, a ich suma wynosi około 1,0.

UrlNormalization

Obiekt reprezentujący działania normalizacyjne podjęte w celu znormalizowania adresu URL, aby zwiększyć szanse na pomyślne wyszukiwanie. Są to podstawowe, automatyczne zmiany, które są wprowadzane, gdy wiadomo, że wyszukiwanie podanego url_pattern nie powiedzie się. Złożone działania, takie jak przekierowania, nie są obsługiwane.

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

Ograniczenia liczby żądań

Interfejs CrUX API jest ograniczony do 150 zapytań na minutę na projekt Google Cloud, co jest oferowane bezpłatnie. Ten limit oraz bieżące wykorzystanie możesz sprawdzić w konsoli Google Cloud. Ten wysoki limit powinien wystarczyć w większości przypadków użycia. Nie można zapłacić za zwiększenie limitu.