CrUX API verwenden

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

Rick Viscomi
Shane Exterkamp
Shane Exterkamp
X GitHub

Der Datensatz Chrome UX Report (CrUX) gibt Aufschluss darüber, wie Chrome-Nutzer beliebte Websites im Web erleben. Seit 2017, als der abfragbare Datensatz erstmals in BigQuery veröffentlicht wurde, wurden Felddaten aus CrUX in Entwicklertools wie PageSpeed Insights, das CrUX-Dashboard und den Core Web Vitals-Bericht der Search Console integriert. So können Entwickler die Nutzerfreundlichkeit für echte Nutzer messen und beobachten. Was bisher fehlte, war ein Tool, das programmatisch kostenlosen und RESTful-Zugriff auf CrUX-Daten bietet. Um diese Lücke zu schließen, freuen wir uns, die Chrome UX Report API ankündigen zu können.

Diese API wurde entwickelt, um Entwicklern einfachen, schnellen und umfassenden Zugriff auf CrUX-Daten zu ermöglichen. Im Gegensatz zur PageSpeed Insights API, die auch Lab-Daten aus den Lighthouse-Leistungsaudits enthält, werden in der CrUX API nur Felddaten zur Nutzererfahrung erfasst. Die CrUX API ist optimiert und kann schnell Daten zur Nutzererfahrung bereitstellen. Sie eignet sich daher ideal für Echtzeit-Auditanwendungen.

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 an, wie Sie sie verwenden.

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 über cURL in der Befehlszeile auf Daten zur Nutzererfahrung eines Ursprungs 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 Content-Type: application/json-Header, der angibt, dass der Anfragetext JSON enthält.
  3. Der JSON-codierte Anfragetext, der den https://web.dev-Ursprung angibt.

Wenn du das Gleiche in JavaScript tun möchtest, verwende das Dienstprogramm CrUXApiUtil. Es führt den API-Aufruf aus und gibt die decodierte Antwort zurück. Weitere Funktionen wie Verlauf und Batch-Unterstützung findest du 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 Anfrageobjekt.

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

Wenn für diesen Ursprung Daten vorhanden sind, ist die API-Antwort ein JSON-codiertes Objekt mit Messwerten, die die Verteilung der Nutzererfahrungen darstellen. Die Verteilungsmesswerte sind Histogrammbalken 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 geben den Wertebereich an, der Nutzern für den jeweiligen Messwert angezeigt wird. Die Property density gibt den Anteil der Nutzererfahrungen in diesem Bereich an. In diesem Beispiel liegt der LCP für 79% der Nutzer auf allen web.dev-Seiten unter 2.500 Millisekunden. Das ist der Grenzwert für eine gute LCP-Leistung. Der Wert percentiles.p75 bedeutet,dass bei 75% der Nutzererfahrungen in dieser Verteilung weniger als 2.216 Millisekunden benötigt werden. 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 zuerst, ob der angeforderte Ursprung öffentlich zugänglich ist, um diesen Fehler zu beheben. Sie können das testen, indem Sie den Ursprung in die Adressleiste Ihres Browsers eingeben und ihn nach allen Weiterleitungen mit der finalen URL vergleichen. Häufige Probleme sind das unnötige Hinzufügen oder Auslassen 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 Samples enthält. Alle im Datensatz enthaltenen Ursprünge und URLs müssen eine ausreichende Anzahl von Samples haben, um einzelne Nutzer zu anonymisieren. Außerdem müssen Ursprünge und URLs öffentlich indexierbar sein. Weitere Informationen dazu, wie Websites in den Datensatz aufgenommen werden, finden Sie in der CrUX-Methodik.

URL-Abfragedaten

Sie haben gelernt, wie Sie die CrUX API für die allgemeine Nutzererfahrung auf einer Quelle abfragen. 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 der Parameter url verwendet wird, um die Seite anzugeben, die gesucht 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 im CrUX-Datensatz Daten für diese URL 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/ eine LCP-Leistung von 85 % hat und ein 75. Perzentil von 1.947 Millisekunden, was etwas besser ist als die standortweite Verteilung.

URL-Normalisierung

Die CrUX API kann angeforderte URLs normalisieren, damit sie besser mit der Liste der bekannten URLs übereinstimmen. Wenn Sie beispielsweise nach der URL https://web.dev/fast/#measure-performance-in-the-field suchen, werden aufgrund der Normalisierung Daten für https://web.dev/fast/ zurückgegeben. In diesem Fall ist ein urlNormalizationDetails-Objekt in der Antwort enthalten.

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

Nach Formfaktor abfragen

Die Nutzerfreundlichkeit kann je nach Websiteoptimierung, Netzwerkbedingungen und Geräten der Nutzer stark variieren. Wenn Sie diese Unterschiede besser nachvollziehen möchten, können Sie mithilfe der Dimension formFactor der CrUX API die Leistung von Ursprung und URL 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 Request-Body 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 formfaktorspezifischen Daten 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
        }
      },
    // ...
    }
  }
}

Das Feld key der Antwort gibt die formFactor-Anfragekonfiguration zurück, um zu bestätigen, dass nur mobile Versionen enthalten sind.

Im vorherigen Abschnitt wurde erwähnt, dass 85% der Nutzererfahrungen auf dieser Seite einen „guten“ LCP hatten. Zum Vergleich: Nur 78% der Smartphone-spezifischen Erfahrungen werden als „gut“ eingestuft. Auch der 75. Perzentilwert ist auf Smartphones langsamer, von 1.947 Millisekunden auf 2.366 Millisekunden. Die Segmentierung nach Formfaktor kann extremere Unterschiede bei der Nutzererfahrung aufzeigen.

Core Web Vitals-Leistung bewerten

Im Rahmen des Core Web Vitals-Programms werden Ziele definiert, anhand derer bestimmt werden kann, ob eine Nutzererfahrung oder eine Verteilung von Nutzererfahrungen als „gut“ eingestuft werden kann. Im folgenden Beispiel wird die CrUX API und die Funktion CrUXApiUtil.query verwendet, 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-Bewertungen 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 Möglichkeit zur Überwachung von API-Ergebnissen können Daten aus CrUX verwendet werden, um dafür zu sorgen, dass die Nutzererfahrung schnell und schnell bleibt. Weitere Informationen zu Core Web Vitals und deren Messung finden Sie unter Web Vitals und Tools zum Messen von Core Web Vitals.

Nächste Schritte

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

  • Zusätzliche Messwerte
    • first_paint
    • dom_content_loaded
    • onload
    • time_to_first_byte
    • notification_permissions
  • Zusätzliche Dimensionen
    • month
    • country
    • effective connection type (ECT)
  • Zusätzliche Granularität
    • Detaillierte Histogramme
    • Mehr Perzentile

In der offiziellen CrUX API-Dokumentation können Sie Ihren API-Schlüssel abrufen und weitere Anwendungsbeispiele ansehen. Wir hoffen, dass Sie es ausprobieren. Bei Fragen oder Feedback können Sie sich jederzeit im CrUX-Diskussionsforum an uns wenden. Wenn Sie über alle geplanten Funktionen der CrUX API auf dem Laufenden bleiben möchten, abonnieren Sie das CrUX-Ankündigungsforum oder folgen Sie uns auf Twitter unter @ChromeUXReport.