Come utilizzare l'API CrUX

Scopri come utilizzare l'API Chrome UX Report per accedere ai dati sull'esperienza utente reale su milioni di siti web.

Rick Viscomi
Shane Exterkamp
Shane Exterkamp
X GitHub

Il set di dati del Report sull'esperienza utente di Chrome (CrUX) rappresenta l'esperienza degli utenti reali di Chrome su destinazioni popolari sul web. Dal 2017, quando il set di dati interrogabili è stato rilasciato per la prima volta su BigQuery, i dati dei campi di CrUX sono stati integrati in strumenti per sviluppatori come PageSpeed Insights, Dashboard di CrUX e nel report Segnali web essenziali di Search Console, consentendo agli sviluppatori di misurare e monitorare le esperienze degli utenti reali. L'elemento che per tutto questo tempo è sfuggito è stato uno strumento che fornisce accesso senza costi e RESTful ai dati CrUX in modo programmatico. Per contribuire a colmare questo divario, siamo felici di annunciare il rilascio della nuovissima API Chrome UX Report.

Questa API è stata creata con l'obiettivo di fornire agli sviluppatori un accesso semplice, rapido e completo ai dati CrUX. L'API CrUX segnala solo i dati sull'esperienza utente sul campo, a differenza dell'API PageSpeed Insights esistente, che riporta anche i dati di lab dei controlli delle prestazioni di Lighthouse. L'API CrUX è semplificata e può fornire rapidamente i dati relativi all'esperienza utente, il che la rende ideale per le applicazioni di controllo in tempo reale.

Per garantire che gli sviluppatori abbiano accesso a tutte le metriche più importanti, Core Web Vitals, l'API CrUX controlla e monitora le metriche Largest Contentful Paint (LCP), Interaction to Next Paint (INP) e Cumulative Layout Shift (CLS) sia a livello di origine che di URL.

Vediamo come utilizzarlo.

Query sui dati di origine

Le origini nel set di dati CrUX comprendono tutte le esperienze sottostanti a livello di pagina. L'esempio seguente mostra come eseguire query sull'API CrUX per recuperare i dati sull'esperienza utente di un'origine utilizzando cURL a riga di comando.

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

Il comando curl è composto da tre parti:

  1. L'endpoint URL dell'API, inclusa la chiave API privata del chiamante.
  2. L'intestazione Content-Type: application/json, che indica che il corpo della richiesta contiene JSON.
  3. Il corpo della richiesta con codifica JSON, che specifica l'origine https://web.dev.

Per fare la stessa cosa in JavaScript, usa l'utilità CrUXApiUtil, che effettua la chiamata API e restituisce la risposta decodificata (vedi anche la nostra variante GitHub per ulteriori funzionalità, tra cui il supporto della cronologia e dei batch).

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

Sostituisci [YOUR_API_KEY] con la tua chiave. A questo punto, chiama la funzione CrUXApiUtil.query e passa l'oggetto corpo della richiesta.

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

Se esistono dati per questa origine, la risposta dell'API è un oggetto con codifica JSON contenente metriche che rappresentano la distribuzione delle esperienze utente. Le metriche di distribuzione sono intervalli dell'istogramma e percentile.

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

Le proprietà start e end dell'oggetto histogram rappresentano l'intervallo di valori esperienza degli utenti per la metrica specificata. La proprietà density rappresenta la proporzione di esperienze utente in questo intervallo. In questo esempio, il 79% delle esperienze utente LCP in tutte le pagine web.dev è inferiore a 2500 millisecondi, che è la soglia LCP "buona". Il valore percentiles.p75 indica che il 75% delle esperienze utente in questa distribuzione è inferiore a 2216 millisecondi. Scopri di più sulla struttura della risposta nella documentazione del corpo della risposta.

Errori

Quando l'API CrUX non dispone di dati per una determinata origine, risponde con un messaggio di errore codificato in JSON:

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

Per eseguire il debug di questo errore, verifica innanzitutto che l'origine richiesta sia navigabile pubblicamente. Puoi verificarlo inserendo l'origine nella barra degli indirizzi del browser e confrontandola con l'URL finale dopo qualsiasi reindirizzamento. I problemi più comuni includono l'aggiunta o l'omissione inutilmente del sottodominio e l'utilizzo del protocollo HTTP errato.

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

Questa origine include erroneamente il protocollo http:// e il sottodominio www..

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

Questa origine è navigabile pubblicamente.

Se l'origine richiesta è la versione navigabile, questo errore può verificarsi anche se l'origine ha un numero insufficiente di campioni. Tutte le origini e gli URL inclusi nel set di dati devono avere un numero sufficiente di campioni per anonimizzare i singoli utenti. Inoltre, le origini e gli URL devono essere indicizzati pubblicamente. Per saperne di più su come i siti web sono inclusi nel set di dati, consulta la Metodologia CrUX.

Esegui query sui dati dell'URL

Hai visto come eseguire query all'API CrUX per conoscere l'esperienza utente complessiva su un'origine. Per limitare i risultati a una pagina specifica, utilizza il parametro di richiesta 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/"}'

Questo comando cURL è simile all'esempio di origine, tranne per il fatto che il corpo della richiesta utilizza il parametro url per specificare la pagina da cercare.

Per eseguire query sui dati URL dall'API CrUX in JavaScript, chiama la funzione CrUXApiUtil.query utilizzando il parametro url nel corpo della richiesta.

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

Se i dati di questo URL esistono nel set di dati CrUX, l'API restituirà una risposta con codifica JSON. Ad esempio:

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

Fedele alla forma, i risultati mostrano che l'85% di https://web.dev/fast/ è "Buono" Esperienze LCP e un 75° percentile di 1947 millisecondi, leggermente migliore della distribuzione a livello di origine.

Normalizzazione degli URL

L'API CrUX potrebbe normalizzare gli URL richiesti affinché corrispondano meglio all'elenco di URL noti. Ad esempio, l'esecuzione di una query per l'URL https://web.dev/fast/#measure-performance-in-the-field genererà dati per https://web.dev/fast/ a causa della normalizzazione. In questo caso, nella risposta viene incluso un oggetto urlNormalizationDetails.

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

Scopri di più sulla normalizzazione degli URL nella documentazione di CrUX.

Esegui query per fattore di forma

Le esperienze degli utenti possono variare notevolmente a seconda delle ottimizzazioni del sito web, delle condizioni della rete e dei dispositivi degli utenti. Per comprendere meglio queste differenze, visualizza in dettaglio il rendimento dell'origine e dell'URL utilizzando la dimensione formFactor dell'API CrUX.

L'API supporta tre valori di fattori di forma espliciti: DESKTOP, PHONE e TABLET. Oltre all'origine o all'URL, specifica uno di questi valori nel corpo della richiesta per limitare i risultati solo alle esperienze utente in questione. Questo esempio mostra come eseguire query sull'API in base al fattore di forma utilizzando 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"}'

Per eseguire query all'API CrUX per dati specifici dei fattori di forma utilizzando JavaScript, chiama la funzione CrUXApiUtil.query utilizzando i parametri url e formFactor nel corpo della richiesta.

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

L'omissione del parametro formFactor è equivalente alla richiesta di dati per tutti i fattori di forma combinati.

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

Il campo key della risposta riporterà la configurazione della richiesta formFactor per confermare che sono incluse solo le esperienze telefoniche.

Come ricorderai dalla sezione precedente, l'85% delle esperienze utente su questa pagina è stato "buono" LCP. Confrontalo con le esperienze specifiche per smartphone, di cui solo il 78% è considerato "buono". Anche il 75° percentile è più lento tra le esperienze con lo smartphone, da 1947 a 2366 millisecondi. La segmentazione per fattore di forma ha il potenziale per evidenziare ulteriori disparità estreme nelle esperienze utente.

Valuta le prestazioni dei Core Web Vitals

Il programma Core Web Vitals definisce gli obiettivi che aiutano a determinare se un'esperienza utente o una distribuzione di esperienze possono essere considerate "buone". Nell'esempio seguente, utilizziamo l'API CrUX e la funzione CrUXApiUtil.query per valutare se la distribuzione di metriche Core Web Vitals (LCP, INP, CLS) in una pagina web è "buona".

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

I risultati mostrano che questa pagina supera le valutazioni Core Web Vitals per tutte e tre le metriche.

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 combinazione con una modalità automatizzata per monitorare i risultati delle API, è possibile utilizzare i dati di CrUX per garantire che le esperienze degli utenti reali diventano veloci e restino rapide. Per saperne di più sui Core Web Vitals e su come misurarli, consulta gli articoli Web Vitals e Strumenti per misurare Core Web Vitals.

Passaggi successivi

Le funzionalità incluse nella versione iniziale dell'API CrUX sono solo una punta ditura del genere di informazioni che è possibile ottenere con CrUX. Gli utenti del set di dati CrUX su BigQuery potrebbero avere familiarità con alcune delle funzionalità più avanzate, tra cui:

  • Metriche aggiuntive
    • first_paint
    • dom_content_loaded
    • onload
    • time_to_first_byte
    • notification_permissions
  • Dimensioni aggiuntive
    • month
    • country
    • effective connection type (ECT)
  • Livello di granularità aggiuntivo
    • istogrammi dettagliati
    • in più percentili

Consulta la documentazione ufficiale dell'API CrUX per acquisire la tua chiave API ed esplora altre applicazioni di esempio. Ci auguriamo che farai una prova e ci piacerebbe ricevere qualsiasi domanda o feedback, quindi contattaci sul forum di discussione di CrUX. Per non perderti gli aggiornamenti su tutto ciò che abbiamo in programma per l'API CrUX, iscriviti al forum degli annunci di CrUX o seguici su Twitter all'indirizzo @ChromeUXReport.