CrUX API verwenden

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

Rick Viscomi

Shane Exterkamp

Das Dataset Chrome UX Report (CrUX) gibt Aufschluss darüber, wie echte Chrome-Nutzer beliebte Websites im Internet nutzen. Seit der Veröffentlichung des abfragbaren Datasets in BigQuery 2017 wurden Felddaten aus CrUX in Entwicklertools wie PageSpeed Insights, das CrUX-Dashboard und den Core Web Vitals-Bericht der Search Console integriert, sodass Entwickler reale Nutzerfreundlichkeit messen und im Blick behalten können. Was bisher fehlte, ist ein Tool, das kostenlosen und RESTful-Zugriff auf CrUX-Daten programmatisch ermöglicht. Um diese Lücke zu schließen, freuen wir uns, die Veröffentlichung der neuen Chrome UX Report API ankündigen zu können.

Diese API wurde entwickelt, um Entwicklern einen einfachen, schnellen und umfassenden Zugriff auf CrUX-Daten zu ermöglichen. Im Gegensatz zur bestehenden PageSpeed Insights API, die auch Lab-Daten aus den Lighthouse-Leistungsprüfungen erfasst, werden von der CrUX API nur Daten zur Nutzererfahrung für Feld gemeldet. Die CrUX API ist optimiert und kann schnell Daten zur Nutzererfahrung bereitstellen, wodurch sie ideal für Echtzeit-Auditanwendungen geeignet ist.

Damit Entwickler Zugriff auf alle wichtigsten Messwerte – die Core Web Vitals – haben, werden Largest Contentful Paint (LCP), First Input Delay (FID) und Cumulative Layout Shift (CLS) sowohl auf Ursprungs- als auch auf URL-Ebene geprüft und überwacht.

Los gehts!

Ursprungsdaten der Abfrage

Ursprünge im CrUX-Dataset umfassen alle zugrunde liegenden Erfahrungen auf Seitenebene. Im folgenden Beispiel wird gezeigt, wie Sie die CrUX API mithilfe von cURL in der Befehlszeile nach den Nutzererfahrungsdaten 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"}'

Hinweis:Alle API-Anfragen müssen einen Wert für den Parameter key enthalten. Im vorherigen Beispiel wurde [YOUR_API_KEY] als Platzhalter belassen. Rufen Sie Ihren eigenen privaten CrUX API-Schlüssel ab, wie in der CrUX API-Dokumentation beschrieben.

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 Ursprung https://web.dev angibt.

Um dasselbe in JavaScript zu tun, können Sie das CrUXApiUtil-Dienstprogramm verwenden, das den API-Aufruf durchführt und die decodierte Antwort zurückgibt. Weitere Funktionen, einschließlich Verlauf und Batch-Support, finden Sie 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 Anfragetextobjekt.

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 metrics, die die Verteilung der Nutzererfahrungen darstellen. Die Verteilungsmesswerte sind Histogramm-Klassen 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 erleben. Die Eigenschaft density gibt den Anteil der Nutzererfahrung in diesem Bereich an. In diesem Beispiel liegen 79% der LCP-Nutzererfahrung auf allen web.dev-Seiten unter 2.500 Millisekunden. Das ist der LCP-Grenzwert für gut. Der Wert percentiles.p75 bedeutet,dass 75% der Nutzererfahrung 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, wird eine JSON-codierte Fehlermeldung zurückgegeben:

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

Um diesen Fehler zu beheben, prüfen Sie zuerst, ob der angeforderte Ursprung öffentlich zugänglich ist. Sie können dies testen, indem Sie den Ursprung in die Adressleiste des Browsers eingeben und ihn nach allen Weiterleitungen mit der finalen URL vergleichen. Zu den häufigsten Problemen gehören 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.

Erfolgreich

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

Dieser Ursprung ist öffentlich navigierbar.

Wenn der angeforderte Startort die navigierbare Version ist, kann dieser Fehler auch auftreten, wenn der Startort nicht genügend Stichproben hat. Alle im Datensatz enthaltenen Ursprünge und URLs müssen eine ausreichende Anzahl von Stichproben haben, um einzelne Nutzer zu anonymisieren. Außerdem müssen Ursprünge und URLs öffentlich indexierbar sein. Weitere Informationen dazu, wie Websites im Dataset enthalten sind, finden Sie unter CrUX-Methodik.

URL-Daten abfragen

Sie haben gesehen, wie Sie die CrUX API für die allgemeine Nutzererfahrung an einem Ursprung abfragen können. 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 „origin“-Beispiel, mit der Ausnahme, dass der Anfragetext den url-Parameter verwendet, um die Seite anzugeben, nach der gesucht werden soll.

Wenn Sie URL-Daten aus der CrUX API in JavaScript abfragen möchten, rufen Sie die Funktion CrUXApiUtil.query mithilfe des url-Parameters 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/ zu 85 % „gute“ LCP-Werte hat und ein 75. Perzentil von 1.947 Millisekunden liegt, was etwas besser ist als die ursprungsweite Verteilung.

URL-Normalisierung

Die CrUX API normalisiert die angeforderten URLs, damit sie besser mit der Liste der bekannten URLs übereinstimmen. Beispielsweise liefert die Abfrage der URL https://web.dev/fast/#measure-performance-in-the-field 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

Wichtiger Begriff:Ein Formfaktor ist der Typ des Geräts, über das ein Nutzer eine Website besucht. Gängige Gerätetypen sind Computer, Smartphones und Tablets.

Die Nutzererfahrung kann je nach Websiteoptimierung, Netzwerkbedingungen und Nutzergeräten stark variieren. Schlüsseln Sie die Leistung von Ursprung und URL mithilfe der Dimension formFactor der CrUX API auf, um diese Unterschiede besser zu verstehen.

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 Nutzer zu beschränken. In diesem Beispiel wird gezeigt, wie die API mithilfe von cURL nach Formfaktor abgefragt wird.

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

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

{
  "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 Konfiguration der formFactor-Anfrage zurückgegeben, um zu bestätigen, dass nur Smartphone-Erlebnisse enthalten sind.

Achtung:Je präziser die Anfrage ist, z. B. eine bestimmte Kombination aus URL und Formfaktor, desto weniger nutzerfreundlich ist die Anfrage. Dies kann zu häufigeren „Nicht gefunden“-Fehlern führen, insbesondere bei der Abfrage weniger beliebter URLs oder des weniger beliebten Tablet-Gerätetyps.

Wie im vorherigen Abschnitt erwähnt, wiesen 85% der Nutzererfahrung auf dieser Seite einen „guten“ LCP-Wert auf. Vergleiche das mit Smartphone-spezifischen Erfahrungen, von denen nur 78% als „gut“ eingestuft werden. Auch das 75. Perzentil ist bei der Nutzung von Smartphones langsamer, nämlich von 1.947 Millisekunden auf 2.366 Millisekunden. Durch die Segmentierung nach Formfaktor können noch extremere Unterschiede bei der User Experience deutlich werden.

Core Web Vitals-Leistung bewerten

Im Core Web Vitals-Programm sind Ziele definiert, anhand derer festgelegt wird, ob eine Nutzererfahrung oder die Verteilung von Inhalten als „gut“ eingestuft 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, FID, 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',
    'first_input_delay',
    '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}).`)
  });
}

Wichtiger Hinweis:Die API kann jeweils nur mit einem Ursprung oder einer URL aufgerufen werden. Wenn Sie mehrere Websites oder Seiten bewerten möchten, führen Sie separate Aufrufe an die API aus.

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 first_input_delay passes the Core Web Vitals "good" threshold (100).
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 sicherzustellen, dass die echte Nutzung schnell und schnell bleibt. Weitere Informationen zu Core Web Vitals und deren Messung finden Sie in den Artikeln Web Vitals und Tools zur Messung von Core Web Vitals.

Nächste Schritte

Die Funktionen der ersten Version der CrUX API bieten nur oberflächliche Einblicke, die mit CrUX möglich sind. Nutzer des CrUX-Datasets in BigQuery sind möglicherweise mit einigen der erweiterten Features 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ätzlicher Detaillierungsgrad
  • Detaillierte Histogramme
  • weitere Perzentile

In der offiziellen CrUX API-Dokumentation finden Sie Informationen zum Erwerben eines API-Schlüssels sowie weitere Beispielanwendungen. Wir hoffen, Sie probieren es aus und freuen uns über Fragen oder Feedback. Wenden Sie sich daher über das CrUX-Diskussionsforum an uns. Wenn Sie über alle Pläne für die CrUX API auf dem Laufenden bleiben möchten, abonnieren Sie das CrUX-Ankündigungsforum oder folgen Sie uns auf Twitter unter @ChromeUXReport.