CrUX API verwenden

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

Rick Viscomi
Shane Exterkamp
Shane Exterkamp
X GitHub

Der Chrome UX Report (CrUX) zeigt, wie echte Chrome-Nutzer beliebte Websites im Web erleben. Seit 2017, als der abfragbare Datensatz zum ersten Mal 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 eingebunden. So können Entwickler die Nutzerfreundlichkeit tatsächlich 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 Veröffentlichung der brandneuen 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. Die CrUX API meldet im Gegensatz zur PageSpeed Insights API, die auch Lab-Daten aus Lighthouse-Leistungsprüfungen umfasst, nur Daten zur Nutzererfahrung von Feldern. Die CrUX API ist optimiert und kann schnell Daten zur Nutzererfahrung bereitstellen. Daher eignet sie sich ideal für Echtzeit-Audit-Anwendungen.

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

Sehen wir uns an, wie das funktioniert.

Ursprungsdaten abfragen

Die Ursprünge im Datensatz für die Nutzererfahrung in Chrome umfassen alle zugrunde liegenden Websitevarianten auf Seitenebene. Im folgenden Beispiel wird gezeigt, wie Sie die CrUX API mithilfe von cURL in der Befehlszeile nach den Nutzererfahrungsdaten eines Ursprungsservers 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. Den Content-Type: application/json-Header, der angibt, dass der Anfragetext JSON enthält.
  3. Der JSON-codierte Anfragetext, der den Ursprung https://web.dev angibt.

In JavaScript können Sie das mit dem Dienstprogramm CrUXApiUtil tun. der den API-Aufruf durchführt und die decodierte Antwort zurückgibt (siehe auch unsere GitHub-Variante) für weitere Funktionen wie Verlaufs- und Batch-Unterstützung).

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, das Messwerte für die Verteilung der Nutzererfahrungen enthält. Die Verteilungsmesswerte sind Histogramm-Bins 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 Objekts histogram stellen den Wertebereich dar, den die Nutzer für den jeweiligen Messwert sehen. Die Eigenschaft density repräsentiert den Anteil der Nutzererfahrungen in diesem Bereich. In diesem Beispiel liegen 79% der LCP-Nutzererfahrungen auf allen web.dev-Seiten unter 2.500 Millisekunden. Das entspricht dem guten Wert. 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 zum Beheben dieses Fehlers zuerst, ob der angeforderte Ursprung öffentlich navigierbar ist. Sie können dies 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 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 aufrufbar.

Wenn der angeforderte Ursprung die navigierbare Version ist, kann dieser Fehler auch auftreten, wenn der Ursprung nicht genügend Stichproben hat. Für alle im Datensatz enthaltenen Ursprünge und URLs muss eine ausreichende Anzahl von Stichproben vorhanden sein, 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-Daten abfragen

Sie haben erfahren, wie Sie die CrUX API abfragen, um die gesamte Nutzererfahrung an einem Ursprung abzufragen. 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 Ursprungsbeispiel, mit der Ausnahme, dass im Anfragetext der Parameter url verwendet wird, um die zu suchende Seite anzugeben.

Wenn Sie URL-Daten über die 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
        }
      },
      // ...
    }
  }
}

Wenn dies wahr ist, zeigen die Ergebnisse, dass https://web.dev/fast/ zu 85 % „gut“ ist LCP-Nutzererfahrungen und ein 75. Perzentil von 1.947 Millisekunden, was etwas besser als die ursprungsweite Verteilung ist.

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.

Abfrage nach Formfaktor

Die Nutzererfahrung kann je nach Website-Optimierung, Netzwerkbedingungen und Geräte. Zum besseren Verständnis dieser Unterschiede schlüsseln Sie die Ursprungs- und URL-Leistung mithilfe der Dimension formFactor der CrUX API auf.

Die API unterstützt drei explizite Formfaktorwerte: DESKTOP, PHONE und TABLET. Geben Sie zusätzlich zum Ursprung oder der URL im Anfragetext einen dieser Werte an, um die Ergebnisse auf diese Nutzererfahrungen zu beschränken. In diesem Beispiel wird gezeigt, wie Sie die API mithilfe von 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 Formfaktordaten 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);
});

Das Weglassen des Parameters formFactor entspricht der kombinierten Anforderung von Daten für alle Formfaktoren.

{
  "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 Smartphones verwendet werden.

Aus dem vorherigen Abschnitt wissen Sie, dass die Nutzererfahrung auf dieser Seite in 85% der Fälle „gut“ war. LCP Vergleichen Sie dies mit Smartphone-spezifischen Funktionen, von denen nur 78% als „gut“ gelten. Das 75. Perzentil ist auch langsamer bei der Nutzung von Smartphones – von 1.947 Millisekunden auf 2.366 Millisekunden. Durch die Segmentierung nach Formfaktor kann die User Experience noch stärker auffallen.

Core Web Vitals-Leistung bewerten

Im Core Web Vitals-Programm sind Ziele definiert, mit denen bestimmt werden kann, ob eine Nutzerfreundlichkeit oder eine Verteilung von Nutzererfahrungen als „gut“ eingestuft werden können. 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/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}).`)
  });
}

Aus den Ergebnissen geht hervor, 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 der API-Ergebnisse können Daten aus CrUX verwendet werden, um dafür zu sorgen, dass die Nutzererfahrung auf der Website 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, die in der ursprünglichen Version der CrUX API enthalten sind, sind nur an der Oberfläche der Informationen, 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 Leseeinheit
    • Detaillierte Histogramme
    • weitere Perzentile

In der offiziellen CrUX API-Dokumentation erfahren Sie, wie Sie Ihren API-Schlüssel erhalten, und sehen sich weitere Beispielanwendungen an. Wir hoffen, dass Sie es ausprobieren, und freuen uns auf Ihre Fragen und Anregungen. Kontaktieren Sie uns im CrUX-Diskussionsforum. Wenn Sie über unsere Pläne zur CrUX API auf dem Laufenden bleiben möchten, abonnieren Sie das CrUX-Ankündigungsforum oder folgen Sie uns auf Twitter unter @ChromeUXReport.