Esegui la migrazione ai client hint dello user agent

Strategie per eseguire la migrazione del tuo sito dall'utilizzo della stringa dello user agent ai nuovi client hint dello user agent.

Pubblicazione: 19 maggio 2021

La stringa dello user agent è una superficie di fingerprinting passivo significativa nei browser, oltre a essere difficile da elaborare. Tuttavia, esistono diversi motivi validi per raccogliere ed elaborare i dati dello user agent, quindi è necessario trovare una soluzione migliore. I client hint dello user agent forniscono un modo esplicito per dichiarare la necessità di dati dello user agent e metodi per restituire i dati in un formato facile da usare.

Qui ti spieghiamo come controllare l'accesso ai dati dello user agent ed eseguire la migrazione dell'utilizzo della stringa dello user agent ai client hint dello user agent.

Browser Support

  • Chrome: 90.
  • Edge: 90.
  • Firefox: not supported.
  • Safari: not supported.

Source

Controlla la raccolta e l'utilizzo dei dati dello user agent

Come per qualsiasi forma di raccolta dei dati, devi sempre capire perché li raccogli. Il primo passaggio, indipendentemente dal fatto che tu debba o meno intraprendere un'azione, è capire dove e perché utilizzi i dati dello user agent.

Se non sai se o dove vengono utilizzati i dati dello user agent, ti consigliamo di cercare nel codice frontend l'utilizzo di navigator.userAgent e nel codice backend l'utilizzo dell'intestazione HTTP User-Agent. Devi anche controllare il codice frontend per verificare l'utilizzo di funzionalità già ritirate, come navigator.platform e navigator.appVersion.

Dal punto di vista funzionale, pensa a qualsiasi punto del codice in cui registri o elabori:

  • Nome o versione del browser
  • Nome o versione del sistema operativo
  • Marca o modello del dispositivo
  • Tipo, architettura o bitness della CPU (ad esempio, 64 bit)

È anche probabile che tu stia utilizzando una libreria o un servizio di terze parti per elaborare lo user agent. In questo caso, verifica se stanno eseguendo l'aggiornamento per supportare i client hint dello user agent.

Stai utilizzando solo i dati di base dello user agent?

L'insieme predefinito di client hint dello user agent include:

  • Sec-CH-UA: nome del browser e versione principale/significativa
  • Sec-CH-UA-Mobile: valore booleano che indica un dispositivo mobile
  • Sec-CH-UA-Platform: il nome del sistema operativo

Anche la versione ridotta della stringa dello user agent proposta manterrà queste informazioni di base in modo compatibile con le versioni precedenti. Ad esempio, invece di Chrome/90.0.4430.85, la stringa includerebbe Chrome/90.0.0.0.

Se controlli la stringa dello user agent solo per il nome del browser, la versione principale o il sistema operativo, il codice continuerà a funzionare, anche se è probabile che vengano visualizzati avvisi di ritiro.

Sebbene sia possibile ed è consigliabile eseguire la migrazione ai client hint dello user agent, potresti avere vincoli di codice o risorse legacy che lo impediscono. La riduzione delle informazioni nella stringa dello user agent in questo modo compatibile con le versioni precedenti ha lo scopo di garantire che, sebbene il codice esistente riceva informazioni meno dettagliate, mantenga comunque la funzionalità di base.

Strategie

Esistono diverse strategie che puoi adottare per eseguire la migrazione dell'utilizzo della stringa dello user agent ai client hint dello user agent.

API JavaScript lato client on demand

Se utilizzi navigator.userAgent, devi passare a preferire navigator.userAgentData prima di tornare ad analizzare la stringa dello user agent.

if (navigator.userAgentData) {
  // use new hints
} else {
  // fall back to user-agent string parsing
}

Se stai eseguendo il controllo per dispositivi mobili o computer, utilizza il valore booleano mobile:

const isMobile = navigator.userAgentData.mobile;

userAgentData.brands è un array di oggetti con proprietà brand e version in cui il browser è in grado di elencare la sua compatibilità con questi brand. Puoi accedervi direttamente come array o utilizzare una chiamata some() per verificare se è presente una voce specifica:

function isCompatible(item) {
  // In real life you most likely have more complex rules here
  return ['Chromium', 'Google Chrome', 'NewBrowser'].includes(item.brand);
}
if (navigator.userAgentData.brands.some(isCompatible)) {
  // browser reports as compatible
}

Se hai bisogno di uno dei valori user agent più dettagliati e ad alta entropia, devi specificarlo e controllare il risultato nel Promise restituito:

navigator.userAgentData.getHighEntropyValues(['model'])
  .then(ua => {
    // requested hints available as attributes
    const model = ua.model
  });

Ti consigliamo di utilizzare questa strategia anche se vuoi passare dall'elaborazione lato server a quella lato client. L'API JavaScript non richiede l'accesso alle intestazioni delle richieste HTTP, pertanto i valori dello user agent possono essere richiesti in qualsiasi momento.

Intestazione lato server statica

Se utilizzi l'intestazione della richiesta User-Agent sul server e le tue esigenze relative a questi dati sono relativamente coerenti in tutto il sito, puoi specificare i client hint come insieme statico nelle risposte. Si tratta di un approccio relativamente semplice, poiché in genere è sufficiente configurarlo in un'unica posizione. Ad esempio, potrebbe trovarsi nella configurazione del server web se aggiungi già intestazioni, nella configurazione di hosting o nella configurazione di primo livello del framework o della piattaforma che utilizzi per il tuo sito.

Prendi in considerazione questa strategia se stai trasformando o personalizzando le risposte pubblicate in base ai dati dello user agent.

I browser o altri client possono scegliere di fornire hint predefiniti diversi, quindi è buona norma specificare tutto ciò di cui hai bisogno, anche se in genere viene fornito per impostazione predefinita.

Ad esempio, le impostazioni predefinite attuali di Chrome verrebbero rappresentate come:

⬇️ Intestazioni della risposta

Accept-CH: Sec-CH-UA-Mobile, Sec-CH-UA-Platform, Sec-CH-UA

Se vuoi ricevere anche il modello del dispositivo nelle risposte, devi inviare:

⬇️ Intestazioni della risposta

Accept-CH: Sec-CH-UA-Mobile, Sec-CH-UA-Model, Sec-CH-UA-Platform, Sec-CH-UA

Quando elabori questa operazione lato server, devi prima verificare se l'intestazione Sec-CH-UA desiderata è stata inviata, quindi eseguire il fallback all'analisi dell'intestazione User-Agent se non è disponibile.

Delega gli hint alle richieste multiorigine

Se richiedi risorse secondarie multiorigine o cross-site che richiedono l'invio di client hint dello user agent nelle relative richieste, devi specificare esplicitamente gli hint desiderati utilizzando una policy sulle autorizzazioni.

Ad esempio, supponiamo che https://blog.site ospiti risorse su https://cdn.site che possono restituire risorse ottimizzate per un dispositivo specifico. https://blog.site può richiedere l'hint Sec-CH-UA-Model, ma deve delegarlo esplicitamente a https://cdn.site utilizzando l'intestazione Permissions-Policy. L'elenco degli hint controllati dalle policy è disponibile nella bozza dell'infrastruttura Client Hints

⬇️ Risposta di blog.site che delega il suggerimento

Accept-CH: Sec-CH-UA-Model
Permissions-Policy: ch-ua-model=(self "https://cdn.site")

⬆️ Le richieste alle risorse secondarie su cdn.site includono l'hint delegato

Sec-CH-UA-Model: "Pixel 5"

Puoi specificare più suggerimenti per più origini e non solo dall'intervallo ch-ua:

⬇️ Risposta di blog.site che delega più hint a più origini

Accept-CH: Sec-CH-UA-Model, DPR
Permissions-Policy: ch-ua-model=(self "https://cdn.site"),
                    ch-dpr=(self "https://cdn.site" "https://img.site")

Delega i suggerimenti agli iframe

Gli iframe multiorigine funzionano in modo simile alle risorse multiorigine, ma devi specificare i suggerimenti che vuoi delegare nell'attributo allow.

⬇️ Risposta di blog.site

Accept-CH: Sec-CH-UA-Model

↪️ HTML per blog.site

<iframe src="https://widget.site" allow="ch-ua-model"></iframe>

⬆️ Richiesta a widget.site

Sec-CH-UA-Model: "Pixel 5"

L'attributo allow nell'iframe sostituirà qualsiasi intestazione Accept-CH che widget.site potrebbe inviare autonomamente, quindi assicurati di aver specificato tutto ciò di cui il sito nell'iframe avrà bisogno.

Suggerimenti dinamici lato server

Se in alcune parti specifiche dello user journey hai bisogno di una selezione di hint più ampia rispetto al resto del sito, puoi scegliere di richiedere questi hint on demand anziché staticamente in tutto il sito. Questa opzione è più complessa da gestire, ma se hai già impostato intestazioni diverse per ogni route, potrebbe essere fattibile.

La cosa importante da ricordare è che ogni istanza dell'intestazione Accept-CH sovrascriverà effettivamente l'insieme esistente. Pertanto, se imposti l'intestazione in modo dinamico, ogni pagina deve richiedere l'insieme completo di hint richiesti.

Ad esempio, potresti avere una sezione del tuo sito in cui vuoi fornire icone e controlli che corrispondono al sistema operativo dell'utente. A questo scopo, potresti voler inserire anche Sec-CH-UA-Platform-Version per pubblicare le risorse secondarie appropriate.

⬇️ Intestazioni della risposta per /blog

Accept-CH: Sec-CH-UA-Mobile, Sec-CH-UA-Platform, Sec-CH-UA

⬇️ Intestazioni della risposta per /app

Accept-CH: Sec-CH-UA-Mobile, Sec-CH-UA-Platform, Sec-CH-UA-Platform-Version, Sec-CH-UA

Suggerimenti lato server per l'indirizzo richiesti alla prima richiesta

Potrebbero esserci casi in cui hai bisogno di più suggerimenti rispetto a quelli predefiniti nella prima richiesta, ma è probabile che ciò accada raramente, quindi assicurati di aver esaminato il ragionamento.

La prima richiesta indica la prima richiesta di primo livello per l'origine inviata nella sessione di navigazione. L'insieme predefinito di hint include il nome del browser con la versione principale, la piattaforma e l'indicatore mobile. Quindi la domanda da porsi è: hai bisogno di dati estesi al caricamento iniziale della pagina?

Per ulteriori suggerimenti sulla prima richiesta, sono disponibili due opzioni. Innanzitutto, puoi utilizzare l'intestazione Critical-CH. Il formato è lo stesso di Accept-CH, ma indica al browser che deve riprovare immediatamente a inviare la richiesta se la prima è stata inviata senza l'hint critico.

⬆️ Richiesta iniziale

[With default headers]

⬇️ Intestazioni della risposta

Accept-CH: Sec-CH-UA-Model
Critical-CH: Sec-CH-UA-Model

🔃 Il browser riprova la richiesta iniziale con l'intestazione aggiuntiva

[With default headers + …]
Sec-CH-UA-Model: Pixel 5

Questo comporta l'overhead del nuovo tentativo alla prima richiesta, ma il costo di implementazione è relativamente basso. Invia l'intestazione aggiuntiva e il browser farà il resto.

Per le situazioni in cui hai davvero bisogno di suggerimenti aggiuntivi al primo caricamento pagina, la proposta di affidabilità dei suggerimenti client sta definendo un percorso per specificare i suggerimenti nelle impostazioni a livello di connessione. In questo modo, viene utilizzata l'estensione Application-Layer Protocol Settings (ALPS) di TLS 1.3 per consentire questo passaggio anticipato di suggerimenti sulle connessioni HTTP/2 e HTTP/3. Questa funzionalità è ancora in una fase molto iniziale, ma se gestisci attivamente le tue impostazioni TLS e di connessione, questo è il momento ideale per contribuire.

Assistenza legacy

Sul tuo sito potrebbe essere presente codice legacy o di terze parti che dipende da navigator.userAgent, incluse parti della stringa dello user agent che verranno ridotte. Dovresti pianificare il passaggio alle chiamate navigator.userAgentData equivalenti, ma esiste una soluzione provvisoria.

UA-CH retrofill è una piccola libreria che ti consente di sovrascrivere navigator.userAgent con una nuova stringa creata dai valori navigator.userAgentData richiesti.

Ad esempio, questo codice genera una stringa user agent che include anche l'hint "model":

import { overrideUserAgentUsingClientHints } from './uach-retrofill.js';
overrideUserAgentUsingClientHints(['model'])
  .then(() => { console.log(navigator.userAgent); });

La stringa risultante mostrerà il modello Pixel 5, ma mostrerà comunque la versione ridotta 92.0.0.0 poiché il suggerimento uaFullVersion non è stato richiesto:

Mozilla/5.0 (Linux; Android 10.0; Pixel 5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/92.0.0.0 Mobile Safari/537.36

Ulteriore assistenza

Se queste strategie non sono adatte al tuo caso d'uso, avvia una discussione nel repository privacy-sandbox-dev-support per esaminare il problema insieme.