CrUX API verwenden

Hier erfahren Sie, wie Sie mit der Chrome UX Report API auf Daten zur Nutzererfahrung von Millionen von Websites zugreifen können.

Rick Viscomi
Shane Exterkamp
Shane Exterkamp
X GitHub

Der Datensatz des Chrome UX Report (CrUX) gibt Aufschluss darüber, wie echte Chrome-Nutzer beliebte Ziele im Web erleben. Seit 2017, als der abfragbare Datensatz zum ersten Mal in BigQuery veröffentlicht wurde, sind Felddaten aus CrUX in Entwicklertools wie PageSpeed Insights und den Core Web Vitals-Bericht der Search Console integriert. So können Entwickler die Nutzerfreundlichkeit messen und im Blick behalten. Bisher fehlte ein Tool, das programmatisch kostenlosen RESTful-Zugriff auf CrUX-Daten bietet. Um diese Lücke zu schließen, freuen wir uns, die neue Chrome UX Report API anzukündigen.

Diese API wurde mit dem Ziel entwickelt, Entwicklern einen schnellen und umfassenden Zugriff auf CrUX-Daten zu ermöglichen. Die CrUX API gibt nur Felddaten zur Nutzererfahrung zurück. Im Gegensatz dazu werden in der vorhandenen PageSpeed Insights API auch Labordaten aus den Lighthouse-Leistungsprüfungen zurückgegeben. Die CrUX API ist optimiert und kann schnell Daten zur Nutzerfreundlichkeit bereitstellen. Sie eignet sich daher ideal für Anwendungen zur Echtzeitprüfung.

Damit Entwickler Zugriff auf alle wichtigen Messwerte haben, die Core Web Vitals, werden mit der CrUX API Largest Contentful Paint (LCP), Interaction to Next Paint (INP) und Cumulative Layout Shift (CLS) sowohl auf Ursprungs- als auch auf URL-Ebene geprüft und überwacht.

Sehen wir uns also an, wie das funktioniert.

API auf dieser Seite testen

Testen!

Ursprungsdaten abfragen

Ursprünge im CrUX-Dataset umfassen alle zugrunde liegenden Nutzungsszenarien auf Seitenebene. Im folgenden Beispiel wird gezeigt, wie Sie die CrUX API mit curl über die Befehlszeile nach Daten zur Nutzererfahrung für einen Ursprung abfragen.

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

Der Befehl curl besteht aus drei Teilen:

  1. Der URL-Endpunkt der API, einschließlich des privaten API-Schlüssels des Aufrufers.
  2. Der Header Content-Type: application/json, der angibt, dass der Anfragetext JSON enthält.
  3. Der JSON-codierte Anfragetext, in dem der https://web.dev-Ursprung angegeben ist.

Um dasselbe in JavaScript zu tun, verwenden Sie das Dienstprogramm CrUXApiUtil, das den API-Aufruf ausführt und die decodierte Antwort zurückgibt. Weitere Funktionen wie Verlauf und Batch-Unterstützung finden Sie auch in unserer GitHub-Variante.

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;
  });
};

Ersetzen Sie [YOUR_API_KEY] durch Ihren Schlüssel. Rufen Sie als Nächstes die Funktion CrUXApiUtil.query auf und übergeben Sie das Objekt Anfragetext.

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

Wenn Daten für diesen Ursprung vorhanden sind, ist die API-Antwort ein JSON-codiertes Objekt mit Messwerten, die die Verteilung der Nutzererfahrungen darstellen. Die Verteilungsmesswerte sind Histogrammklassen und Perzentile.

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

Die Eigenschaften start und end des histogram-Objekts stellen den Wertebereich dar, den Nutzer für den jeweiligen Messwert sehen. Die Eigenschaft density gibt den Anteil der Nutzererfahrungen in diesem Bereich an. In diesem Beispiel liegen 79% der LCP-Nutzererlebnisse auf allen web.dev-Seiten unter 2.500 Millisekunden, dem guten LCP-Grenzwert. Der Wert percentiles.p75 bedeutet,dass 75% der Nutzererfahrungen in dieser Verteilung weniger als 2.216 Millisekunden betragen. Weitere Informationen zur Antwortstruktur finden Sie in der Dokumentation zum Antworttext.

Fehler

Wenn die CrUX API keine Daten für einen bestimmten Ursprung hat, antwortet sie mit einer JSON-codierten Fehlermeldung:

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

Prüfen Sie zur Fehlerbehebung zuerst, ob der angeforderte Ursprung öffentlich zugänglich ist. Sie können dies testen, indem Sie den Ursprung in die Adressleiste Ihres Browsers eingeben und mit der finalen URL nach allen Weiterleitungen vergleichen. Häufige Probleme sind das unnötige Hinzufügen oder Weglassen der Subdomain und die Verwendung des falschen HTTP-Protokolls.

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

Dieser Ursprung enthält fälschlicherweise das http://-Protokoll und die www.-Subdomain.

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

Dieser Ursprung ist öffentlich zugänglich.

Wenn der angeforderte Ursprung die navigierbare Version ist, kann dieser Fehler auch auftreten, wenn der Ursprung nicht genügend Stichproben hat. Alle Ursprünge und URLs im Dataset müssen eine ausreichende Anzahl von Stichproben enthalten, um einzelne Nutzer zu anonymisieren. Außerdem müssen Ursprünge und URLs öffentlich indexierbar sein. Weitere Informationen dazu, wie Websites in das Dataset aufgenommen werden, finden Sie hier.

URL-Daten abfragen

Sie haben gesehen, wie Sie die CrUX API abfragen, um die allgemeine Nutzererfahrung auf einer Herkunft zu ermitteln. Wenn Sie die Ergebnisse auf eine bestimmte Seite beschränken möchten, verwenden Sie den Anfrageparameter url.

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

Dieser curl-Befehl ähnelt dem Beispiel für den Ursprung, mit der Ausnahme, dass im Anfragetext mit dem Parameter url die Seite angegeben wird, die nachgeschlagen werden soll.

Wenn Sie URL-Daten aus der CrUX API in JavaScript abfragen möchten, rufen Sie die Funktion CrUXApiUtil.query mit dem Parameter url im Anfragetext auf.

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

Wenn Daten für diese URL im CrUX-Dataset vorhanden sind, gibt die API eine JSON-codierte Antwort zurück. Beispiel:

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

Die Ergebnisse zeigen, dass https://web.dev/fast/ 85 % „gute“ LCP-Ergebnisse und ein 75. Perzentil von 1.947 Millisekunden aufweist, was etwas besser ist als die verteilte Verteilung.

URL-Normalisierung

Die CrUX API normalisiert angeforderte URLs möglicherweise, um sie besser mit der Liste der bekannten URLs abzugleichen. Wenn Sie beispielsweise Daten für die URL https://web.dev/fast/#measure-performance-in-the-field abfragen, erhalten Sie aufgrund der Normalisierung Daten für https://web.dev/fast/. In diesem Fall wird ein urlNormalizationDetails-Objekt in die Antwort aufgenommen.

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

Weitere Informationen zur URL-Normalisierung finden Sie in der CrUX-Dokumentation.

Abfrage nach Formfaktor

Die Nutzerfreundlichkeit kann je nach Websiteoptimierung, Netzwerkbedingungen und Geräten der Nutzer erheblich variieren. Um diese Unterschiede besser zu verstehen, können Sie die Leistung von Ursprung und URL mit der Dimension formFactor der CrUX API analysieren.

Die API unterstützt drei explizite Formfaktorwerte: DESKTOP, PHONE und TABLET. Geben Sie zusätzlich zum Ursprung oder zur URL einen dieser Werte im Anfragetext an, um die Ergebnisse auf diese Nutzererfahrungen zu beschränken. In diesem Beispiel wird gezeigt, wie Sie die API mit curl nach Formfaktor abfragen.

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

Wenn Sie die CrUX API mit JavaScript nach Daten für bestimmte Formfaktoren abfragen möchten, rufen Sie die Funktion CrUXApiUtil.query mit den Parametern url und formFactor im Anfragetext auf.

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

Wenn Sie den Parameter formFactor weglassen, werden Daten für alle Formfaktoren zusammen angefordert.

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

Im Feld key der Antwort wird die formFactor-Anfragekonfiguration wiederholt, um zu bestätigen, dass nur Telefonfunktionen enthalten sind.

Wie im vorherigen Abschnitt erwähnt, hatten 85% der Nutzer auf dieser Seite einen „guten“ LCP. Im Vergleich dazu werden nur 78% der smartphone-spezifischen Funktionen als „gut“ eingestuft. Auch das 75. Perzentil ist bei Smartphones langsamer und stieg von 1.947 Millisekunden auf 2.366 Millisekunden. Durch die Segmentierung nach Formfaktor lassen sich möglicherweise extreme Unterschiede bei der Nutzerfreundlichkeit aufzeigen.

Core Web Vitals-Leistung bewerten

Im Programm Core Web Vitals werden Zielwerte definiert, anhand derer sich bestimmen lässt, ob eine Nutzerfreundlichkeit oder eine Verteilung von Nutzerfreundlichkeit als „gut“ angesehen werden kann. Im folgenden Beispiel verwenden wir die CrUX API und die Funktion CrUXApiUtil.query, um zu beurteilen, ob die Verteilung der Core Web Vitals-Messwerte (LCP, INP, CLS) einer Webseite „gut“ ist.

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

function assessCoreWebVitals(response) {
  // See https://web.dev/articles/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}).`)
  });
}

Die Ergebnisse zeigen, dass diese Seite die Core Web Vitals-Tests für alle drei Messwerte besteht.

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).

In Kombination mit einer automatisierten Methode zur Überwachung von API-Ergebnissen können Daten aus CrUX verwendet werden, um dafür zu sorgen, dass die Nutzererfahrung schnell ist und schnell bleibt. Weitere Informationen zu Core Web Vitals und dazu, wie Sie sie messen können, finden Sie unter Web Vitals und Tools zum Messen von Core Web Vitals.

Nächste Schritte

Die Funktionen der ersten Version der CrUX API sind nur ein kleiner Ausschnitt der Erkenntnisse, die mit CrUX möglich sind. Nutzer des CrUX-Datasets in BigQuery kennen möglicherweise einige der erweiterten Funktionen, darunter:

  • Zusätzliche Messwerte
    • first_paint
    • dom_content_loaded
    • onload
    • time_to_first_byte
    • notification_permissions
  • Zusätzliche Dimensionen
    • month
    • country
  • Zusätzliche Granularität
    • detaillierte Histogramme
    • mehr Perzentile

In der offiziellen CrUX API-Dokumentation finden Sie Informationen zum Abrufen Ihres API-Schlüssels und weitere Beispielanwendungen. Wir hoffen, dass Sie es ausprobieren, und freuen uns auf Ihre Fragen und Ihr Feedback im CrUX-Diskussionsforum. Wenn Sie über alles, was wir für die CrUX API geplant haben, auf dem Laufenden bleiben möchten, abonnieren Sie das CrUX-Ankündigungsforum oder folgen Sie uns auf Twitter unter @ChromeUXReport.