Come utilizzare l'API CrUX

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

Rick Viscomi
Shane Exterkamp
Shane Exterkamp
X GitHub

Il set di dati del Chrome UX Report (CrUX) rappresenta l'esperienza degli utenti reali di Chrome nelle 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 e nel report Core Web Vitals di Search Console, consentendo agli sviluppatori di misurare e monitorare le esperienze degli utenti reali. Lo strumento che mancava da tempo è un'API che fornisce l'accesso senza costi e RESTful ai dati CrUX in modo programmatico. Per contribuire a colmare questa lacuna, siamo felici di annunciare il rilascio della nuova API Chrome UX Report.

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

Scopriamo subito come utilizzarlo.

Prova l'API in questa pagina

Prova!

Esegui query sui dati di origine

Le origini nel set di dati CrUX comprendono tutte le esperienze a livello di pagina sottostanti. Il seguente esempio mostra come eseguire una query sull'API CrUX per i dati sull'esperienza utente di un'origine utilizzando curl dalla 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, utilizza l'utilità CrUXApiUtil, che esegue la chiamata API e restituisce la risposta decodificata (vedi anche la nostra variante di 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. Successivamente, chiama la funzione CrUXApiUtil.query e trasmetti 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 metrics che rappresentano la distribuzione delle esperienze utente. Le metriche di distribuzione sono bin e percentili dell'istogramma.

{
  "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 riscontrano 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, ovvero 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. Puoi verificarlo inserendo l'origine nella barra degli indirizzi del browser e confrontandola con l'URL finale dopo eventuali reindirizzamenti. I problemi più 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 campioni per anonimizzare i singoli utenti. Inoltre, le origini e gli URL devono essere indicizzabili pubblicamente. Consulta la metodologia CrUX per scoprire di più su come i siti web vengono inclusi nel set di dati.

Query sui dati degli URL

Hai visto come eseguire query sull'API CrUX per 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 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 formato 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
        }
      },
      // ...
    }
  }
}

Come previsto, i risultati mostrano che https://web.dev/fast/ ha l'85% di esperienze LCP "buone" 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 per trovare una corrispondenza migliore con l'elenco degli URL noti. Ad esempio, l'interrogazione dell'URL https://web.dev/fast/#measure-performance-in-the-field restituirà 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.

Query per fattore di forma

L'esperienza utente può variare notevolmente in base alle ottimizzazioni del sito web, alle condizioni di rete e ai dispositivi degli utenti. Per comprendere meglio queste differenze, esamina in dettaglio le prestazioni di origine e URL utilizzando la dimensione formFactor dell'API CrUX.

L'API supporta tre valori espliciti per il 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 per 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 equivale a richiedere i 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 per smartphone.

Ricorda dalla sezione precedente che l'85% delle esperienze utente su questa pagina aveva un valore 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 su smartphone, passando da 1947 millisecondi a 2366 millisecondi. La segmentazione per fattore di forma può evidenziare disparità più estreme nelle esperienze utente.

Valutare il rendimento dei Core Web Vitals

Il programma Segnali web essenziali definisce 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}).`)
  });
}

I risultati mostrano che questa pagina supera le valutazioni dei Segnali web essenziali 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 automatizzato per monitorare i risultati delle API, i dati di CrUX possono essere utilizzati per garantire che le esperienze degli utenti reali siano veloci e rimangano veloci. Per saperne di più su Core Web Vitals e su come misurarle, consulta Web Vitals e Strumenti per misurare Core Web Vitals.

Passaggi successivi

Le funzionalità incluse nella versione iniziale dell'API CrUX sono solo una parte dei tipi di approfondimenti possibili 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
  • Granularità aggiuntiva
    • istogrammi dettagliati
    • più percentili

Consulta la documentazione ufficiale dell'API CrUX per ottenere la chiave API ed esplorare altre applicazioni di esempio. Ci auguriamo che tu possa provarlo e ci farebbe piacere ricevere domande o feedback. Contattaci nel forum di discussione di CrUX. Per rimanere aggiornato su tutto ciò che abbiamo pianificato per l'API CrUX, iscriviti al forum degli annunci di CrUX o seguici su Twitter all'indirizzo @ChromeUXReport.