Crux-API

De CrUX API biedt toegang met lage latentie tot geaggregeerde gegevens over de echte gebruikerservaring op pagina- en oorsprongsgranulariteit.

Probeer het!

Veelvoorkomend gebruiksscenario

Met de CrUX API kunnen statistieken over de gebruikerservaring worden opgevraagd voor een specifieke URI, zoals 'Get metrics for the https://example.com origin'.

Crux API-sleutel

Voor het gebruik van de CrUX API is een Google Cloud API-sleutel vereist die is ingericht voor gebruik van Chrome UX Report API .

Een API-sleutel verkrijgen en gebruiken

Of maak er een aan op de pagina Referenties .

Nadat u een API-sleutel heeft, kan uw toepassing de queryparameter key= yourAPIKey aan alle aanvraag-URL's toevoegen.

De API-sleutel kan veilig worden ingesloten in URL's; het heeft geen codering nodig.

Zie Voorbeeldquery's .

Gegevensmodel

In dit gedeelte wordt de structuur van gegevens in verzoeken en antwoorden beschreven.

Dossier

Een discreet stukje informatie over een pagina of site. Een record kan gegevens bevatten die specifiek zijn voor een identifier en voor een specifieke combinatie van dimensies. Een record kan gegevens bevatten voor een of meer metrieken.

Identificatiegegevens

Identifiers specificeren welke records moeten worden opgezocht. In Crux zijn deze identifiers webpagina's en websites.

Oorsprong

Wanneer de identifier een oorsprong is, worden alle aanwezige gegevens voor alle pagina's in die oorsprong samengevoegd. Stel bijvoorbeeld dat de oorsprong http://www.example.com pagina's had zoals weergegeven in deze sitemap:

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

Dit zou betekenen dat bij het bevragen van het Chrome UX-rapport met de oorsprong ingesteld op http://www.example.com , gegevens voor http://www.example.com/ , http://www.example.com/foo.html en http://www.example.com/bar.html zouden worden geretourneerd, samengevoegd, omdat dit alle pagina's onder die oorsprong zijn.

URL's

Wanneer de ID een URL is, worden alleen gegevens voor die specifieke URL geretourneerd. Kijk nog eens naar de oorspronkelijke sitemap http://www.example.com :

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

Als de ID is ingesteld op URL met de waarde http://www.example.com/foo.html , worden alleen gegevens voor die pagina geretourneerd.

Afmetingen

Dimensies identificeren een specifieke groep gegevens waartegen een record wordt samengevoegd. De vormfactor PHONE geeft bijvoorbeeld aan dat de record informatie bevat over ladingen die hebben plaatsgevonden op een mobiel apparaat. Elke dimensie zal een bepaald aantal waarden hebben, en impliciet zal het ontbreken van het specificeren van die dimensie betekenen dat de dimensie over alle waarden wordt geaggregeerd. Als u bijvoorbeeld geen vormfactor opgeeft, geeft dit aan dat de record informatie bevat over belastingen die op een bepaalde vormfactor hebben plaatsgevonden.

Vormfactor

De apparaatklasse die de eindgebruiker heeft gebruikt om naar de pagina te navigeren. Dit is een algemene apparaatklasse, opgesplitst in PHONE , TABLET en DESKTOP .

Metrisch

We rapporteren statistieken als statistische aggregaties, in histogrammen, percentielen en breuken.

Waarden met drijvende komma worden afgerond op 4 decimalen (houd er rekening mee dat de cumulative_layout_shift -statistieken dubbel gecodeerd zijn als een tekenreeks, dus niet als floats worden beschouwd en worden gerapporteerd met 2 decimalen binnen de tekenreeks).

Histogram

Wanneer statistieken in een histogram worden uitgedrukt, laten we de percentages paginaladingen zien die binnen bepaalde bereiken voor die statistiek vallen.

Een histogram met drie bakken voor een voorbeeldstatistiek ziet er als volgt uit:

{
  "histogram": [
    {
      "start": 0,
      "end": 1000,
      "density": 0.3818
    },
    {
      "start": 1000,
      "end": 3000,
      "density": 0.4991
    },
    {
      "start": 3000,
      "density": 0.1192
    }
  ]
}

Deze gegevens geven aan dat voor 38,18% van de paginaladingen de voorbeeldstatistiek werd gemeten tussen 0 ms en 1000 ms. De eenheden van de metriek zijn niet opgenomen in dit histogram; in dit geval gaan we uit van milliseconden.

Bovendien zag 49,91% van de paginaladingen een metrische waarde tussen 1.000 ms en 3.000 ms, en 11,92% zag een waarde groter dan 3.000 ms.

Percentielen

Statistieken kunnen ook percentielen bevatten die nuttig kunnen zijn voor aanvullende analyses. We rapporteren specifieke statistische waarden op het gegeven percentiel voor die statistiek. Ze zijn gebaseerd op de volledige set beschikbare gegevens en niet op de uiteindelijke opgeslagen gegevens. Ze komen dus niet noodzakelijkerwijs overeen met een geïnterpoleerd percentiel dat is gebaseerd op het uiteindelijke opgeslagen histogram.

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

In dit voorbeeld werd ten minste 75% van de paginaladingen gemeten met een metrische waarde <= 2063 .

Breuken

Breuken geven de percentages paginaladingen aan die op een bepaalde manier kunnen worden gelabeld. In dit geval zijn de metrische waarden deze labels.

De metriek form_factors bestaat bijvoorbeeld uit een object fractions met een overzicht van de vormfactoren (of apparaten) die de gegeven zoekopdracht omvat:

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

In dit geval werd 3,77% van de paginaladingen gemeten op een desktop, 2,88% op een tablet en 93,35% op een telefoon, wat in totaal 100% oplevert.

Typen metrische waarden

Naamtoewijzing van BigQuery-statistieken

Verzamelperiode

Vanaf oktober 2022 bevat de CrUX API een collectionPeriod object met de velden firstDate en endDate die de begin- en einddatum van het aggregatievenster vertegenwoordigen. Bijvoorbeeld:

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

Dit zorgt voor een beter inzicht in de gegevens en of deze al voor die dag zijn bijgewerkt of dezelfde gegevens retourneren als gisteren.

De verzamelperiode is ook beschikbaar in PageSpeed ​​Insights:

Bovendien zal de collectionPeriod altijd 28 dagen weergeven, zelfs als de gegevens niet de volledige 28 dagen betreffen (bijvoorbeeld als een pagina minder dan 28 dagen geleden is gelanceerd). De collectionPeriod is de periode waarover de CrUX-gegevens zijn verzameld, niet noodzakelijkerwijs de periode die de gegevens vertegenwoordigen.

Voorbeeldvragen

Query's worden verzonden als JSON-objecten met behulp van een POST-verzoek naar https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=[YOUR_API_KEY]" met querygegevens als JSON-object in de POST-tekst:

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

Dit kan bijvoorbeeld vanuit curl worden aangeroepen met de volgende opdrachtregel (waarbij API_KEY wordt vervangen door uw sleutel):

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"]}'

Gegevens op paginaniveau zijn beschikbaar via de API door een url eigenschap in de query door te geven, in plaats van origin :

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

Als de eigenschap metrics niet is ingesteld, worden alle beschikbare statistieken geretourneerd:

• cumulative_layout_shift
• first_contentful_paint
• interaction_to_next_paint
• largest_contentful_paint
• 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 (alleen gerapporteerd als er geen formFactor is opgegeven in de aanvraag)

Als er geen formFactor waarde wordt opgegeven, worden de waarden voor alle vormfactoren samengevoegd.

Zie De Chrome UX Report API gebruiken voor meer voorbeeldquery's.

Gegevenspijplijn

De CrUX-dataset wordt via een pijplijn verwerkt om de gegevens te consolideren, aggregeren en filteren voordat ze beschikbaar komen met behulp van de API.

Het voortschrijdend gemiddelde

De gegevens in het Chrome UX-rapport zijn een voortschrijdend gemiddelde over 28 dagen van verzamelde statistieken. Dit betekent dat de gegevens die op een bepaald moment in het Chrome UX-rapport worden weergegeven, feitelijk gegevens zijn van de afgelopen 28 dagen bij elkaar opgeteld.

Dit is vergelijkbaar met de manier waarop de Crux-dataset op BigQuery maandelijkse rapporten verzamelt.

Dagelijkse updates

Gegevens worden dagelijks rond 04:00 UTC bijgewerkt. Er is geen Service Level Agreement voor updatetijden; het wordt elke dag op een best-effort-basis uitgevoerd.

Schema

Er is één eindpunt voor de CrUX API dat POST HTTP-verzoeken accepteert. De API retourneert een record dat een of meer metrics bevat die overeenkomen met prestatiegegevens over de opgevraagde oorsprong of pagina.

HTTP-verzoek

POST https://chromeuxreport.googleapis.com/v1/records:queryRecord

De URL gebruikt de syntaxis van gRPC-transcodering .

Lichaam aanvragen

De verzoektekst moet gegevens bevatten met de volgende structuur:

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

Als u bijvoorbeeld de grootste inhoudelijke paint-waarden op het bureaublad wilt opvragen voor de startpagina van de Chrome-ontwikkelaarsdocumentatie:

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

Reactie lichaam

Succesvolle verzoeken retourneren antwoorden met een record en urlNormalizationDetails in de volgende structuur:

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

Het antwoord op de verzoektekst in het vorige verzoek zou bijvoorbeeld kunnen zijn:

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

Sleutel

Key definieert alle dimensies die deze record als uniek identificeren.

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

Statistieken

Een metric is een reeks verzamelde gebruikerservaringsgegevens voor één enkele webprestatiestatistiek, zoals de eerste inhoudsvolle verf. Het kan een samenvattend histogram van Chrome-gebruik in de echte wereld bevatten als een reeks bins , specifieke percentielgegevens (zoals de p75), of het kan gelabelde breuken bevatten.

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

of

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

Bak

Een bin is een afzonderlijk deel van de gegevens dat zich uitstrekt van begin tot eind, of als er geen einde is opgegeven, van begin tot positieve oneindigheid.

De begin- en eindwaarden van een bak worden gegeven in het waardetype van de metriek die deze vertegenwoordigt. De eerste contentful paint wordt bijvoorbeeld gemeten in milliseconden en weergegeven als ints, daarom zullen de metrische bins int32s gebruiken voor de begin- en eindtypen. De cumulatieve lay-outverschuiving wordt echter gemeten in eenheidsloze decimalen en wordt weergegeven als een decimaal gecodeerd als een tekenreeks. Daarom zullen de metrische bins tekenreeksen gebruiken voor het waardetype.

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

Percentielen

Percentiles bevatten synthetische waarden van een metriek bij een bepaald statistisch percentiel. Deze worden gebruikt voor het schatten van de waarde van een statistiek zoals ervaren door een percentage van de gebruikers van het totale aantal gebruikers.

{
  "P75": value
}

Breuken

Fractions bevatten gelabelde breuken die optellen tot ~1. Elk label beschrijft op de een of andere manier het laden van een pagina, dus statistieken die op deze manier worden weergegeven, kunnen worden gezien als afzonderlijke waarden in plaats van numerieke waarden, en de breuken geven aan hoe vaak een bepaalde afzonderlijke waarde is gemeten.

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

Net als de dichtheidswaarden in histogramvakken is elke fraction een getal 0.0 <= value <= 1.0 , en opgeteld is dat ~1.0.

UrlNormalisatie

Object dat de normalisatieacties vertegenwoordigt die zijn ondernomen om een ​​URL te normaliseren om een ​​grotere kans op een succesvolle zoekopdracht te bereiken. Dit zijn eenvoudige, geautomatiseerde wijzigingen die worden aangebracht wanneer het opzoeken van het opgegeven url_pattern mislukt. Complexe acties zoals het volgen van omleidingen worden niet afgehandeld.

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

Tarieflimieten

De CrUX API is beperkt tot 150 queries per minuut per Google Cloud-project en wordt gratis aangeboden. Deze limiet en uw huidige verbruik kunt u zien in de Google Cloud Console . Dit genereuze quotum zou voldoende moeten zijn voor de overgrote meerderheid van de gebruiksscenario's en het is niet mogelijk om voor een verhoogd quotum te betalen.

De CrUX API biedt toegang met lage latentie tot geaggregeerde gegevens over de echte gebruikerservaring op pagina- en oorsprongsgranulariteit.

Probeer het!

Veelvoorkomend gebruiksscenario

Met de CrUX API kunnen statistieken over de gebruikerservaring worden opgevraagd voor een specifieke URI, zoals 'Get metrics for the https://example.com origin'.

Crux API-sleutel

Voor het gebruik van de CrUX API is een Google Cloud API-sleutel vereist die is ingericht voor gebruik van Chrome UX Report API .

Een API-sleutel verkrijgen en gebruiken

Of maak er een aan op de pagina Referenties .

Nadat u een API-sleutel heeft, kan uw toepassing de queryparameter key= yourAPIKey aan alle aanvraag-URL's toevoegen.

De API-sleutel kan veilig worden ingesloten in URL's; het heeft geen codering nodig.

Zie Voorbeeldquery's .

Gegevensmodel

In dit gedeelte wordt de structuur van gegevens in verzoeken en antwoorden beschreven.

Dossier

Een discreet stukje informatie over een pagina of site. Een record kan gegevens bevatten die specifiek zijn voor een identifier en voor een specifieke combinatie van dimensies. Een record kan gegevens bevatten voor een of meer metrieken.

Identificatiegegevens

Identifiers specificeren welke records moeten worden opgezocht. In Crux zijn deze identifiers webpagina's en websites.

Oorsprong

Wanneer de identifier een oorsprong is, worden alle aanwezige gegevens voor alle pagina's in die oorsprong samengevoegd. Stel bijvoorbeeld dat de oorsprong http://www.example.com pagina's had zoals weergegeven in deze sitemap:

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

Dit zou betekenen dat bij het bevragen van het Chrome UX-rapport met de oorsprong ingesteld op http://www.example.com , gegevens voor http://www.example.com/ , http://www.example.com/foo.html en http://www.example.com/bar.html zouden worden geretourneerd, samengevoegd, omdat dit alle pagina's onder die oorsprong zijn.

URL's

Wanneer de ID een URL is, worden alleen gegevens voor die specifieke URL geretourneerd. Kijk nog eens naar de oorspronkelijke sitemap http://www.example.com :

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

Als de ID is ingesteld op URL met de waarde http://www.example.com/foo.html , worden alleen gegevens voor die pagina geretourneerd.

Afmetingen

Dimensies identificeren een specifieke groep gegevens waartegen een record wordt samengevoegd. De vormfactor PHONE geeft bijvoorbeeld aan dat de record informatie bevat over ladingen die hebben plaatsgevonden op een mobiel apparaat. Elke dimensie zal een bepaald aantal waarden hebben, en impliciet zal het ontbreken van het specificeren van die dimensie betekenen dat de dimensie over alle waarden wordt geaggregeerd. Als u bijvoorbeeld geen vormfactor opgeeft, geeft dit aan dat de record informatie bevat over belastingen die op een bepaalde vormfactor hebben plaatsgevonden.

Vormfactor

De apparaatklasse die de eindgebruiker heeft gebruikt om naar de pagina te navigeren. Dit is een algemene apparaatklasse, opgesplitst in PHONE , TABLET en DESKTOP .

Metrisch

We rapporteren statistieken als statistische aggregaties, in histogrammen, percentielen en breuken.

Waarden met drijvende komma worden afgerond op 4 decimalen (houd er rekening mee dat de cumulative_layout_shift -statistieken dubbel gecodeerd zijn als een tekenreeks, dus niet als floats worden beschouwd en worden gerapporteerd met 2 decimalen binnen de tekenreeks).

Histogram

Wanneer statistieken in een histogram worden uitgedrukt, laten we de percentages paginaladingen zien die binnen bepaalde bereiken voor die statistiek vallen.

Een histogram met drie bakken voor een voorbeeldstatistiek ziet er als volgt uit:

{
  "histogram": [
    {
      "start": 0,
      "end": 1000,
      "density": 0.3818
    },
    {
      "start": 1000,
      "end": 3000,
      "density": 0.4991
    },
    {
      "start": 3000,
      "density": 0.1192
    }
  ]
}

Uit deze gegevens blijkt dat voor 38,18% van de paginaladingen de voorbeeldstatistiek werd gemeten tussen 0 ms en 1000 ms. De eenheden van de metriek zijn niet opgenomen in dit histogram; in dit geval gaan we uit van milliseconden.

Bovendien zag 49,91% van de paginaladingen een metrische waarde tussen 1.000 ms en 3.000 ms, en 11,92% zag een waarde groter dan 3.000 ms.

Percentielen

Statistieken kunnen ook percentielen bevatten die nuttig kunnen zijn voor aanvullende analyses. We rapporteren specifieke statistische waarden op het gegeven percentiel voor die statistiek. Ze zijn gebaseerd op de volledige set beschikbare gegevens en niet op de uiteindelijke opgeslagen gegevens. Ze komen dus niet noodzakelijkerwijs overeen met een geïnterpoleerd percentiel dat is gebaseerd op het uiteindelijke opgeslagen histogram.

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

In dit voorbeeld werd ten minste 75% van de paginaladingen gemeten met een metrische waarde <= 2063 .

Breuken

Breuken geven de percentages paginaladingen aan die op een bepaalde manier kunnen worden gelabeld. In dit geval zijn de metrische waarden deze labels.

De metriek form_factors bestaat bijvoorbeeld uit een object fractions met een overzicht van de vormfactoren (of apparaten) die de gegeven zoekopdracht omvat:

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

In dit geval werd 3,77% van de paginaladingen gemeten op een desktop, 2,88% op een tablet en 93,35% op een telefoon, wat in totaal 100% oplevert.

Typen metrische waarden

Naamtoewijzing van BigQuery-statistieken

Verzamelperiode

Vanaf oktober 2022 bevat de CrUX API een collectionPeriod object met de velden firstDate en endDate die de begin- en einddatum van het aggregatievenster vertegenwoordigen. Bijvoorbeeld:

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

Dit zorgt voor een beter inzicht in de gegevens en of deze al voor die dag zijn bijgewerkt of dezelfde gegevens retourneren als gisteren.

De verzamelperiode is ook beschikbaar in PageSpeed ​​Insights:

Bovendien zal de collectionPeriod altijd 28 dagen weergeven, zelfs als de gegevens niet de volledige 28 dagen betreffen (bijvoorbeeld als een pagina minder dan 28 dagen geleden is gelanceerd). De collectionPeriod is de periode waarover de CrUX-gegevens zijn verzameld, niet noodzakelijkerwijs de periode die de gegevens vertegenwoordigen.

Voorbeeldvragen

Query's worden verzonden als JSON-objecten met behulp van een POST-verzoek naar https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=[YOUR_API_KEY]" met querygegevens als JSON-object in de POST-tekst:

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

Dit kan bijvoorbeeld vanuit curl worden aangeroepen met de volgende opdrachtregel (waarbij API_KEY wordt vervangen door uw sleutel):

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"]}'

Gegevens op paginaniveau zijn beschikbaar via de API door een url eigenschap in de query door te geven, in plaats van origin :

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

Als de eigenschap metrics niet is ingesteld, worden alle beschikbare statistieken geretourneerd:

• cumulative_layout_shift
• first_contentful_paint
• interaction_to_next_paint
• largest_contentful_paint
• 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 (alleen gerapporteerd als er geen formFactor is opgegeven in de aanvraag)

Als er geen formFactor waarde wordt opgegeven, worden de waarden voor alle vormfactoren samengevoegd.

Zie De Chrome UX Report API gebruiken voor meer voorbeeldquery's.

Gegevenspijplijn

De CrUX-dataset wordt via een pijplijn verwerkt om de gegevens te consolideren, aggregeren en filteren voordat ze beschikbaar komen met behulp van de API.

Het voortschrijdend gemiddelde

De gegevens in het Chrome UX-rapport zijn een voortschrijdend gemiddelde over 28 dagen van verzamelde statistieken. Dit betekent dat de gegevens die op een bepaald moment in het Chrome UX-rapport worden weergegeven, feitelijk gegevens zijn van de afgelopen 28 dagen bij elkaar opgeteld.

Dit is vergelijkbaar met de manier waarop de Crux-dataset op BigQuery maandelijkse rapporten verzamelt.

Dagelijkse updates

Gegevens worden dagelijks rond 04:00 UTC bijgewerkt. Er is geen Service Level Agreement voor updatetijden; het wordt elke dag op een best-effort-basis uitgevoerd.

Schema

Er is één eindpunt voor de CrUX API dat POST HTTP-verzoeken accepteert. De API retourneert een record dat een of meer metrics bevat die overeenkomen met prestatiegegevens over de opgevraagde oorsprong of pagina.

HTTP-verzoek

POST https://chromeuxreport.googleapis.com/v1/records:queryRecord

De URL gebruikt de syntaxis van gRPC-transcodering .

Lichaam aanvragen

De verzoektekst moet gegevens bevatten met de volgende structuur:

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

Als u bijvoorbeeld de grootste inhoudelijke paint-waarden op het bureaublad wilt opvragen voor de startpagina van de Chrome-ontwikkelaarsdocumentatie:

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

Reactie lichaam

Succesvolle verzoeken retourneren antwoorden met een record en urlNormalizationDetails in de volgende structuur:

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

Het antwoord op de verzoektekst in het vorige verzoek zou bijvoorbeeld kunnen zijn:

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

Sleutel

Key definieert alle dimensies die deze record als uniek identificeren.

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

Statistieken

Een metric is een reeks verzamelde gebruikerservaringsgegevens voor één enkele webprestatiestatistiek, zoals de eerste inhoudsvolle verf. Het kan een samenvattend histogram van Chrome-gebruik in de echte wereld bevatten als een reeks bins , specifieke percentielgegevens (zoals de p75), of het kan gelabelde breuken bevatten.

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

of

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

Bak

Een bin is een afzonderlijk deel van de gegevens dat zich uitstrekt van begin tot eind, of als er geen einde is opgegeven, van begin tot positieve oneindigheid.

De begin- en eindwaarden van een bak worden gegeven in het waardetype van de metriek die deze vertegenwoordigt. De eerste contentful paint wordt bijvoorbeeld gemeten in milliseconden en weergegeven als ints, daarom zullen de metrische bins int32s gebruiken voor de begin- en eindtypen. De cumulatieve lay-outverschuiving wordt echter gemeten in eenheidsloze decimalen en wordt weergegeven als een decimaal gecodeerd als een tekenreeks. Daarom zullen de metrische bins tekenreeksen gebruiken voor het waardetype.

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

Percentielen

Percentiles bevatten synthetische waarden van een metriek bij een bepaald statistisch percentiel. Deze worden gebruikt voor het schatten van de waarde van een statistiek zoals ervaren door een percentage van de gebruikers van het totale aantal gebruikers.

{
  "P75": value
}

Breuken

Fractions bevatten gelabelde breuken die optellen tot ~1. Elk label beschrijft op de een of andere manier het laden van een pagina, dus statistieken die op deze manier worden weergegeven, kunnen worden gezien als afzonderlijke waarden in plaats van numerieke waarden, en de breuken geven aan hoe vaak een bepaalde afzonderlijke waarde is gemeten.

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

Net als de dichtheidswaarden in histogramvakken is elke fraction een getal 0.0 <= value <= 1.0 , en opgeteld is dat ~1.0.

UrlNormalisatie

Object dat de normalisatieacties vertegenwoordigt die zijn ondernomen om een ​​URL te normaliseren om een ​​grotere kans op een succesvolle zoekopdracht te bereiken. Dit zijn eenvoudige, geautomatiseerde wijzigingen die worden aangebracht wanneer het opzoeken van het opgegeven url_pattern mislukt. Complexe acties zoals het volgen van omleidingen worden niet afgehandeld.

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

Tarieflimieten

De CrUX API is beperkt tot 150 queries per minuut per Google Cloud-project en wordt kosteloos aangeboden. Deze limiet en uw huidige verbruik kunt u zien in de Google Cloud Console . Dit genereuze quotum zou voldoende moeten zijn voor de overgrote meerderheid van de gebruiksscenario's en het is niet mogelijk om voor een verhoogd quotum te betalen.