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

Il set di dati del Report sull'esperienza utente di Chrome (CrUX) rappresenta il modo in cui gli utenti reali di Chrome trovano le destinazioni più frequenti sul web. Dal 2017, quando il set di dati interrogabile è stato rilasciato per la prima volta su BigQuery, i dati sul campo di CrUX sono stati integrati in strumenti per sviluppatori come PageSpeed Insights, la dashboard di CrUX e il report Core Web Vitals di Search Console, consentendo agli sviluppatori di misurare e monitorare le esperienze degli utenti reali. Ciò che mancava finora era uno strumento che fornisse accesso programmatico senza costi e REST ai dati di CrUX. Per colmare questa lacuna, siamo lieti di annunciare il rilascio della nuova API Chrome UX Report.

Questa API è stata creata con l'obiettivo di fornire agli sviluppatori un accesso semplice, rapido e completo ai dati di CrUX. L'API CrUX registra solo i dati sull'esperienza utente sul campo, a differenza dell'API PageSpeed Insights esistente, che registra anche i dati di laboratorio dei controlli delle prestazioni di Lighthouse. L'API CrUX è semplificata e può fornire rapidamente i dati sull'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, ovvero i Core Web Vitals, l'API CrUX controlla e monitora Largest Contentful Paint (LCP), Interaction to Next Paint (INP) e Cumulative Layout Shift (CLS) sia a livello di origine che di URL.

Vediamo come si usa.

Prova l'API in questa pagina

Prova!

Dati dell'origine query

Le origini nel set di dati CrUX comprendono tutte le esperienze a livello di pagina sottostanti. 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"}'

Nota: tutte le richieste API devono fornire un valore per il parametro key. [YOUR_API_KEY] nell'esempio precedente viene lasciato come segnaposto. Ottieni la tua chiave API CrUX privata come descritto nella documentazione dell'API CrUX.

Il comando curl è composto da tre parti:

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

Per fare lo stesso in JavaScript, utilizza l'utilità CrUXApiUtil, che effettua la chiamata all'API e restituisce la risposta decodificata (consulta anche la nostra variante GitHub per altre funzionalità, tra cui la cronologia e il supporto 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. Quindi, 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 che gli utenti sperimentano per la metrica specificata. La proprietà density rappresenta la proporzione di esperienze utente all'interno di 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 relativa al 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. Per verificare, inserisci l'origine nella barra degli indirizzi del browser e confrontala con l'URL finale dopo eventuali reindirizzamenti. I problemi comuni includono l'aggiunta o l'omissione non necessaria 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 esempi per anonimizzare i singoli utenti. Inoltre, le origini e gli URL devono essere indicizzati pubblicamente. Consulta la metodologia CrUX per scoprire di più su come i siti web vengono inclusi nel set di dati.

Query sui dati dell'URL

Hai visto come eseguire query sull'API CrUX per l'esperienza utente complessiva in 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 degli 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 per questo URL esistono nel set di dati CrUX, l'API restituirà una risposta codificata in 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
        }
      },
      // ...
    }
  }
}

In linea con le aspettative, i risultati mostrano che https://web.dev/fast/ ha un'esperienza LCP "buona" per l'85% delle volte e un percentile del 75° pari a 1947 millisecondi, che è leggermente migliore rispetto alla distribuzione a livello di origine.

Normalizzazione degli URL

L'API CrUX potrebbe normalizzare gli URL richiesti per una migliore corrispondenza con l'elenco degli URL noti. Ad esempio, la query sull'URL https://web.dev/fast/#measure-performance-in-the-field restituirà i dati per https://web.dev/fast/ a causa della normalizzazione. In questo caso, nella risposta verrà 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

Termine chiave: un fattore di forma è il tipo di dispositivo su cui un utente visita un sito web. I tipi di dispositivi più comuni sono computer, smartphone e tablet.

Le esperienze utente 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 delle origini e degli URL utilizzando la dimensione formFactor dell'API CrUX.

L'API supporta tre valori espliciti del fattore di forma: DESKTOP, PHONE e TABLET. Oltre all'origine o all'URL, specifica uno di questi valori nel corpo della richiesta per limitare i risultati solo a queste esperienze utente. 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 sull'API CrUX per dati specifici del fattore 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 restituirà la configurazione della richiesta formFactor per confermare che sono incluse solo le esperienze con lo smartphone.

Attenzione: più la richiesta è granulare, ad esempio una combinazione specifica di URL e fattore di forma, meno esperienze utente includerà. Ciò può comportare errori di tipo "non trovato" più frequenti, in particolare quando vengono eseguite query su URL meno popolari o sul tipo di tablet meno popolare.

Ricorda che nella sezione precedente abbiamo indicato che l'85% delle esperienze utente su questa pagina aveva un LCP "buono". Confronta questo dato 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, passando da 1947 millisecondi a 2366 millisecondi. Il segmentazione in base al fattore di forma ha il potenziale di evidenziare disparità più estreme nelle esperienze utente.

Valutare il rendimento dei Core Web Vitals

Il programma Core Web Vitals definisce dei target che aiutano a determinare se un'esperienza utente o una distribuzione di esperienze può essere considerata "buona". Nell'esempio seguente utilizziamo l'API CrUX e la funzione CrUXApiUtil.query per valutare se la distribuzione delle metriche Core Web Vitals (LCP, INP, CLS) di 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/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}).`)
  });
}

Punto chiave:l'API può essere chiamata con una sola origine o un solo URL alla volta. Per valutare più siti web o pagine, effettua chiamate separate all'API.

I risultati mostrano che questa pagina supera le valutazioni di 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).

Se combinati con un modo automatico per monitorare i risultati dell'API, i dati di CrUX possono essere utilizzati per garantire che le esperienze degli utenti reali diventino rapide e rimangano rapide. Per saperne di più su Core Web Vitals e su come misurarli, consulta Web Vitals e Strumenti per misurare Core Web Vitals.

Passaggi successivi

Le funzionalità incluse nella versione iniziale dell'API CrUX rappresentano solo una parte dei tipi di approfondimenti possibili con CrUX. Gli utenti del set di dati CrUX su BigQuery potrebbero conoscere 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)
• Granularità aggiuntiva
  • istogrammi dettagliati
  • altri percentili

Consulta la documentazione ufficiale dell'API CrUX per acquisire la tua chiave API ed esplorare altre applicazioni di esempio. Ci auguriamo che tu decida di provarlo e saremo lieti di ricevere eventuali domande o feedback. Contattaci nel forum di discussione CrUX. Per rimanere al passo con tutto ciò che abbiamo in programma per l'API CrUX, iscriviti al forum degli annunci di CrUX o seguici su Twitter all'indirizzo @ChromeUXReport.