Come utilizzare l'API CrUX

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

Rick Viscomi

Shane Exterkamp

Il set di dati Chrome UX Report (CrUX) rappresenta l'esperienza degli utenti di Chrome reali nelle destinazioni più frequenti sul web. Dal 2017, quando il set di dati interrogabile è stato rilasciato per la prima volta su BigQuery, i dati dei campi di CrUX sono stati integrati in strumenti per sviluppatori come PageSpeed Insights, CrUX Dashboard e il report Segnali web essenziali di Search Console, consentendo agli sviluppatori di misurare e monitorare le esperienze degli utenti reali. Ciò che è scomparso tutto questo tempo è uno strumento che fornisce accesso senza costi e RESTful ai dati di CrUX in modo programmatico. Per contribuire a colmare questo divario, siamo lieti 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 di CrUX. L'API CrUX genera report solo sui dati relativi all'esperienza utente del campo, a differenza dell'API PageSpeed Insights esistente, che riporta anche i dati di lab derivanti dai 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 applicazioni di controllo in tempo reale.

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

Vediamo come si usa!

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 all'API CrUX per i dati sull'esperienza utente di un'origine utilizzando cURL nella 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. Richiedi la tua chiave API CrUX privata come descritto nella documentazione relativa all'API CrUX.

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 effettua la chiamata API e restituisce la risposta decodificata (vedi anche la nostra variante GitHub per ulteriori funzionalità tra cui cronologia e 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 passala nell'oggetto request body.

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 fasce e percentili a istogrammi.

{
  "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 utilizzati dagli utenti 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 con codifica 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 comuni includono l'aggiunta o l'omissione non necessaria del sottodominio e l'utilizzo del protocollo HTTP sbagliato.

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 disporre di un numero sufficiente di campioni per anonimizzare i singoli utenti. Inoltre, le origini e gli URL devono essere indicizzabili pubblicamente. Per saperne di più su come i siti web sono inclusi nel set di dati, consulta la metodologia CrUX.

Dati URL query

Hai visto come eseguire query all'API CrUX per l'esperienza utente complessiva su un'origine. Per limitare i risultati a una determinata pagina, 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 dell'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 dell'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 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
        }
      },
      // ...
    }
  }
}

Fedeli alla forma, i risultati mostrano che https://web.dev/fast/ ha un 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 in modo che corrispondano meglio all'elenco degli URL noti. Ad esempio, l'esecuzione di 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.

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, telefono e tablet.

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

L'API supporta tre valori espliciti dei fattori 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 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 una query all'API CrUX per dati specifici del fattore di forma utilizzando JavaScript, chiama la funzione CrUXApiUtil.query usando 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);
});

Omettere il parametro formFactor equivale a richiedere 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 farà eco la configurazione della richiesta formFactor per confermare che siano incluse solo le esperienze telefoniche.

Attenzione: più è granulare la richiesta, ad esempio una combinazione specifica di URL e fattore di forma, minore è il numero di esperienze utente che includerà. Questo potrebbe causare più frequenti errori di tipo "Non trovato", soprattutto quando si eseguono query su URL meno popolari o sul tipo di tablet meno utilizzato.

Come abbiamo detto nella sezione precedente, l'85% delle esperienze utente in questa pagina ha un LCP "buono". Confronta queste informazioni con le esperienze specifiche dello smartphone, di cui solo il 78% è considerata "buona". Anche il 75° percentile è più lento tra le esperienze con il telefono, passando da 1947 a 2366 millisecondi. La segmentazione per fattore di forma può mettere in evidenza disparità più estreme nelle esperienze utente.

Valutare le prestazioni dei Segnali web essenziali

Il programma Segnali web essenziali definisce gli obiettivi che contribuiscono a determinare se un'esperienza utente o una distribuzione di esperienze può essere considerata "buona". Nel seguente esempio, utilizziamo l'API CrUX e la funzione CrUXApiUtil.query per valutare se la distribuzione di una pagina web delle metriche di Core Web Vitals (LCP, FID, CLS) è "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',
    '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}).`)
  });
}

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

I risultati mostrano che questa pagina ha superato 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 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).

Combinati con un metodo automatizzato per monitorare i risultati delle API, i dati di CrUX possono essere utilizzati per garantire che le esperienze degli utenti reali diventano veloci e rimangano veloci. Per ulteriori informazioni sui Segnali web essenziali e su come misurarli, visita la pagina Segnali web e Strumenti per misurare i Segnali web essenziali.

Passaggi successivi

Le funzionalità incluse nella versione iniziale dell'API CrUX sono solo un'anteprima dei tipi di insight 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)
• Maggiore granularità
  • istogrammi dettagliati
  • percentili in più

Consulta i documenti ufficiali dell'API CrUX per acquisire la chiave API ed esplorare altre applicazioni di esempio. Ci auguriamo che tu decida di provarlo e ci farebbe piacere ricevere qualsiasi domanda o feedback, perciò contattaci sul forum di discussione di CrUX. Per restare al corrente 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.