Hoe de Crux-API te gebruiken

Ontdek hoe u de Chrome UX Report API gebruikt om toegang te krijgen tot gegevens over echte gebruikerservaringen op miljoenen websites.

Rick Viscomi

Shane Exterkamp

De Chrome UX Report (CrUX)-dataset geeft weer hoe echte Chrome-gebruikers populaire bestemmingen op internet ervaren. Sinds 2017, toen de bevraagbare dataset voor het eerst werd uitgebracht op BigQuery , zijn veldgegevens van CrUX geïntegreerd in ontwikkelaarstools zoals PageSpeed ​​Insights , het CrUX Dashboard en het Core Web Vitals-rapport van Search Console, waardoor ontwikkelaars echte gebruikerservaringen kunnen meten en monitoren. Het stuk dat al die tijd heeft gemist, is een tool die programmatisch gratis en RESTful toegang biedt tot CrUX-gegevens. Om die kloof te helpen overbruggen, kondigen we met trots de release aan van de geheel nieuwe Chrome UX Report API !

Deze API is gebouwd met als doel ontwikkelaars eenvoudige, snelle en uitgebreide toegang tot CrUX-gegevens te bieden. De CrUX API rapporteert alleen gegevens over gebruikerservaringen in het veld , in tegenstelling tot de bestaande PageSpeed ​​Insights API , die ook laboratoriumgegevens van de Lighthouse-prestatieaudits rapporteert. De CrUX API is gestroomlijnd en kan snel gegevens over gebruikerservaringen leveren, waardoor deze bij uitstek geschikt is voor realtime audittoepassingen.

Om ervoor te zorgen dat ontwikkelaars toegang hebben tot alle statistieken die er het meest toe doen – de Core Web Vitals – controleert en monitort de CrUX API Largest Contentful Paint (LCP), Interaction to Next Paint (INP) en Cumulative Layout Shift (CLS) op zowel het oorsprongs- als het URL-niveau.

Dus laten we erin duiken en kijken hoe we het kunnen gebruiken!

Probeer de API op deze pagina

Probeer het!

Oorsprongsgegevens opvragen

De oorsprong in de Crux-dataset omvat alle onderliggende ervaringen op paginaniveau. In het volgende voorbeeld ziet u hoe u de CrUX API kunt opvragen voor de gebruikerservaringsgegevens van een origin met behulp van cURL op de opdrachtregel.

API_KEY="[YOUR_API_KEY]"
curl "https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=$API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"origin": "https://web.dev"}'

Opmerking: Alle API-verzoeken moeten een waarde opgeven voor de key : [YOUR_API_KEY] in het vorige voorbeeld blijft als tijdelijke aanduiding staan. Verkrijg uw eigen privé CrUX API-sleutel zoals beschreven in de CrUX API-documentatie .

Het curl -commando bestaat uit drie delen:

1. Het URL-eindpunt van de API, inclusief de privé-API-sleutel van de aanroeper.
2. De Content-Type: application/json header, die aangeeft dat de aanvraagtekst JSON bevat.
3. De JSON-gecodeerde aanvraagtekst , met vermelding van de https: https://web.dev .

Om hetzelfde in JavaScript te doen, gebruik je het hulpprogramma CrUXApiUtil , dat de API-aanroep doet en het gedecodeerde antwoord retourneert (zie ook onze Github-variant voor meer functies, waaronder geschiedenis en batchondersteuning).

const CrUXApiUtil = {};
// Get your CrUX API key at https://goo.gle/crux-api-key.
CrUXApiUtil.API_KEY = '[YOUR_API_KEY]';
CrUXApiUtil.API_ENDPOINT = `https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=${CrUXApiUtil.API_KEY}`;
CrUXApiUtil.query = function (requestBody) {
  if (CrUXApiUtil.API_KEY == '[YOUR_API_KEY]') {
    throw 'Replace "YOUR_API_KEY" with your private CrUX API key. Get a key at https://goo.gle/crux-api-key.';
  }
  return fetch(CrUXApiUtil.API_ENDPOINT, {
    method: 'POST',
    body: JSON.stringify(requestBody)
  }).then(response => response.json()).then(response => {
    if (response.error) {
      return Promise.reject(response);
    }
    return response;
  });
};

Vervang [YOUR_API_KEY] door uw sleutel . Roep vervolgens de functie CrUXApiUtil.query aan en geef het body-object van de aanvraag door.

CrUXApiUtil.query({
  origin: 'https://web.dev'
}).then(response => {
  console.log(response);
}).catch(response => {
  console.error(response);
});

Als er gegevens voor deze oorsprong bestaan, is het API-antwoord een JSON-gecodeerd object dat statistieken bevat die de distributie van gebruikerservaringen vertegenwoordigen. De distributiestatistieken zijn histogrambins en percentielen.

{
  "record": {
    "key": {
      "origin": "https://web.dev"
    },
    "metrics": {
      "largest_contentful_paint": {
        "histogram": [
          {
            "start": 0,
            "end": 2500,
            "density": 0.7925068547983514
          },
          {
            "start": 2500,
            "end": 4000,
            "density": 0.1317422195536863
          },
          {
            "start": 4000,
            "density": 0.07575092564795324
          }
        ],
        "percentiles": {
          "p75": 2216
        }
      },
      // ...
    }
  }
}

De start en end van het histogram vertegenwoordigen het bereik van waarden die gebruikers ervaren voor de gegeven metriek. De density vertegenwoordigt het aandeel gebruikerservaringen binnen dat bereik. In dit voorbeeld bedraagt ​​79% van de LCP-gebruikerservaringen op alle web.dev-pagina's minder dan 2500 milliseconden, wat de ' goede ' LCP-drempel is. De percentiles.p75 waarde betekent dat 75% van de gebruikerservaringen in deze distributie minder dan 2.216 milliseconden duren. Meer informatie over de antwoordstructuur vindt u in de documentatie over de antwoordtekst .

Fouten

Wanneer de CrUX API geen gegevens heeft voor een bepaalde oorsprong, reageert deze met een JSON-gecodeerd foutbericht:

{
  "error": {
    "code": 404,
    "message": "chrome ux report data not found",
    "status": "NOT_FOUND"
  }
}

Om deze fout op te lossen, controleert u eerst of de gevraagde oorsprong openbaar navigeerbaar is. U kunt dit testen door de oorsprong in de adresbalk van uw browser in te voeren en deze na eventuele omleidingen te vergelijken met de uiteindelijke URL. Veelvoorkomende problemen zijn onder meer het onnodig toevoegen of weglaten van het subdomein en het gebruik van het verkeerde HTTP-protocol.

Fout

{"origin": "http://www.web.dev"}

Deze oorsprong omvat ten onrechte het http:// -protocol en www. subdomein.

Succes

{"origin": "https://web.dev"}

Deze oorsprong is openbaar bevaarbaar.

Als de gevraagde oorsprong de navigeerbare versie is , kan deze fout ook optreden als de oorsprong een onvoldoende aantal monsters heeft. Alle herkomsten en URL's die in de dataset zijn opgenomen, moeten voldoende voorbeelden hebben om individuele gebruikers te anonimiseren. Bovendien moeten de oorsprong en URL's openbaar indexeerbaar zijn. Raadpleeg de Crux-methodologie voor meer informatie over hoe websites in de dataset worden opgenomen.

URL-gegevens opvragen

Je hebt gezien hoe je de CrUX API kunt bevragen voor de algehele gebruikerservaring op een origin. Om de resultaten te beperken tot een bepaalde pagina, gebruikt u de url verzoekparameter.

API_KEY="[YOUR_API_KEY]"
curl "https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=$API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"url": "https://web.dev/fast/"}'

Deze cURL-opdracht is vergelijkbaar met het origin-voorbeeld, behalve dat de aanvraagtekst de url parameter gebruikt om de pagina op te geven die moet worden opgezocht.

Als u URL-gegevens uit de CrUX API in JavaScript wilt opvragen, roept u de functie CrUXApiUtil.query aan met behulp van de url parameter in de hoofdtekst van het verzoek.

CrUXApiUtil.query({
  url: 'https://web.dev/fast/'
}).then(response => {
  console.log(response);
}).catch(response => {
  console.error(response);
});

Als er gegevens voor deze URL aanwezig zijn in de CrUX-gegevensset, retourneert de API een JSON-gecodeerd antwoord. Bijvoorbeeld

{
  "record": {
    "key": {
      "url": "https://web.dev/fast/"
    },
    "metrics": {
      "largest_contentful_paint": {
        "histogram": [
          {
            "start": 0,
            "end": 2500,
            "density": 0.8477304539092148
          },
          {
            "start": 2500,
            "end": 4000,
            "density": 0.08988202359528057
          },
          {
            "start": 4000,
            "density": 0.062387522495501155
          }
        ],
        "percentiles": {
          "p75": 1947
        }
      },
      // ...
    }
  }
}

Zoals het hoort laten de resultaten zien dat https://web.dev/fast/ 85% "goede" LCP-ervaringen heeft en een 75e percentiel van 1.947 milliseconden, wat iets beter is dan de herkomstbrede distributie.

Normalisatie van URL's

De CrUX API kan aangevraagde URL's normaliseren, zodat deze beter overeenkomen met de lijst met bekende URL's. Als u bijvoorbeeld zoekt naar de URL https://web.dev/fast/#measure-performance-in-the-field resulteert dit vanwege normalisatie in gegevens voor https://web.dev/fast/ . Wanneer dit gebeurt, wordt een object urlNormalizationDetails in het antwoord opgenomen.

{
  "record": {
    "key": {
      "url": "https://web.dev/fast/"
    },
    "metrics": { ... }
  },
  "urlNormalizationDetails": {
    "normalizedUrl": "https://web.dev/fast/",
    "originalUrl": "https://web.dev/fast/#measure-performance-in-the-field"
  }
}

Lees meer over URL-normalisatie in de Crux-documentatie.

Zoekopdracht per vormfactor

Sleutelbegrip: Een vormfactor is het type apparaat waarop een gebruiker een website bezoekt. Veelvoorkomende apparaattypen zijn desktop, telefoon en tablet.

Gebruikerservaringen kunnen aanzienlijk variëren, afhankelijk van website-optimalisaties, netwerkomstandigheden en apparaten van gebruikers. Om deze verschillen beter te begrijpen, kunt u dieper ingaan op de oorsprong en URL-prestaties met behulp van de formFactor dimensie van de CrUX API.

De API ondersteunt drie expliciete vormfactorwaarden: DESKTOP , PHONE en TABLET . Geef naast de oorsprong of URL een van deze waarden op in de hoofdtekst van het verzoek om de resultaten te beperken tot alleen die gebruikerservaringen. In dit voorbeeld ziet u hoe u de API kunt opvragen op vormfactor met behulp van cURL.

API_KEY="[YOUR_API_KEY]"
curl "https://chromeuxreport.googleapis.com/v1/records:queryRecord?key=$API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"url": "https://web.dev/fast/", "formFactor": "PHONE"}'

Als u de CrUX API wilt opvragen voor vormfactorspecifieke gegevens met behulp van JavaScript, roept u de functie CrUXApiUtil.query aan met behulp van de url en formFactor parameters in de hoofdtekst van het verzoek.

CrUXApiUtil.query({
  url: 'https://web.dev/fast/',
  formFactor: 'PHONE'
}).then(response => {
  console.log(response);
}).catch(response => {
  console.error(response);
});

Het weglaten van de parameter formFactor komt overeen met het opvragen van gegevens voor alle vormfactoren samen.

{
  "record": {
    "key": {
      "url": "https://web.dev/fast/",
      "formFactor": "PHONE"
    },
    "metrics": {
      "largest_contentful_paint": {
        "histogram": [
          {
            "start": 0,
            "end": 2500,
            "density": 0.778631284916204
          },
          {
            "start": 2500,
            "end": 4000,
            "density": 0.13943202979515887
          },
          {
            "start": 4000,
            "density": 0.08193668528864119
          }
        ],
        "percentiles": {
          "p75": 2366
        }
      },
    // ...
    }
  }
}

Het key van het antwoord echoot de formFactor aanvraagconfiguratie terug om te bevestigen dat alleen telefoonervaringen zijn opgenomen.

Let op: Hoe fijner het verzoek is, bijvoorbeeld een specifieke combinatie van URL en vormfactor, hoe minder gebruikerservaringen het zal bevatten. Dit kan leiden tot vaker voorkomende 'niet gevonden'-fouten, vooral bij het opvragen van minder populaire URL's of het minder populaire type tabletapparaat.

Bedenk uit de vorige sectie dat 85% van de gebruikerservaringen op deze pagina een "goede" LCP had. Vergelijk dat eens met telefoonspecifieke ervaringen, waarvan slechts 78% als ‘goed’ wordt beschouwd. Het 75e percentiel is ook langzamer bij telefoonervaringen, van 1.947 milliseconden naar 2.366 milliseconden. Segmentatie op vormfactor heeft het potentieel om extremere verschillen in gebruikerservaringen te benadrukken.

Beoordeel de prestaties van Core Web Vitals

Het Core Web Vitals -programma definieert doelen die helpen bepalen of een gebruikerservaring of een verdeling van ervaringen als "goed" kan worden beschouwd. In het volgende voorbeeld gebruiken we de CrUX API en de CrUXApiUtil.query functie om te beoordelen of de distributie van Core Web Vitals-statistieken (LCP, INP, CLS) door een webpagina "goed" is.

CrUXApiUtil.query({
  url: 'https://web.dev/fast/'
}).then(response => {
  assessCoreWebVitals(response);
}).catch(response => {
  console.error(response);
});

function assessCoreWebVitals(response) {
  // See https://web.dev/vitals/#core-web-vitals.
  const CORE_WEB_VITALS = [
    'largest_contentful_paint',
    'interaction_to_next_paint',
    'cumulative_layout_shift'
  ];
  CORE_WEB_VITALS.forEach(metric => {
    const data = response.record.metrics[metric];
    if (!data) {
      console.log('No data for', metric);
      return;
    }
    const p75 = data.percentiles.p75;
    const threshold = data.histogram[0].end;
    // A Core Web Vitals metric passes the assessment if
    // its 75th percentile is under the "good" threshold.
    const passes = p75 < threshold;
    console.log(`The 75th percentile (${p75}) of ${metric} ` +
        `${passes ? 'passes' : 'does not pass'} ` +
        `the Core Web Vitals "good" threshold (${threshold}).`)
  });
}

Belangrijk punt: De API mag slechts met één oorsprong of URL tegelijk worden aangeroepen. Om meerdere websites of pagina's te beoordelen, voert u afzonderlijke oproepen naar de API uit.

Uit de resultaten blijkt dat deze pagina de Core Web Vitals-beoordelingen voor alle drie de statistieken doorstaat.

The 75th percentile (1973) of largest_contentful_paint passes the Core Web Vitals "good" threshold (2500).
The 75th percentile (20) of interaction_to_next_paint passes the Core Web Vitals "good" threshold (200).
The 75th percentile (0.05) of cumulative_layout_shift passes the Core Web Vitals "good" threshold (0.10).

Gecombineerd met een geautomatiseerde manier om API-resultaten te monitoren, kunnen gegevens uit CrUX worden gebruikt om ervoor te zorgen dat echte gebruikerservaringen snel worden en blijven . Voor meer informatie over Core Web Vitals en hoe u deze kunt meten, gaat u naar Web Vitals en Tools om Core Web Vitals te meten .

Wat is het volgende?

De functies in de eerste versie van de CrUX API zijn slechts een schets van de soorten inzichten die mogelijk zijn met CrUX. Gebruikers van de Crux-dataset op BigQuery zijn wellicht bekend met enkele van de meer geavanceerde functies, waaronder:

• Aanvullende statistieken
  • first_paint
  • dom_content_loaded
  • onload
  • time_to_first_byte
  • notification_permissions
• Extra afmetingen
  • month
  • country
  • effective connection type (ECT)
• Extra granulariteit
  • gedetailleerde histogrammen
  • meer percentielen

Bekijk de officiële Crux API-documentatie om uw API-sleutel te verkrijgen en meer voorbeeldapplicaties te verkennen. We hopen dat je het eens wilt proberen en we horen graag al je vragen of feedback. Neem dus contact met ons op via het CrUX-discussieforum . En om op de hoogte te blijven van alles wat we hebben gepland voor de CrUX API, abonneert u zich op het CrUX-aankondigingsforum of volgt u ons op Twitter op @ChromeUXReport .