L'intestazione User-Agent è sempre stata inclusa nelle richieste di offerta per fornire dati di targeting utili come il browser e la piattaforma del dispositivo di avvio. Tuttavia, i browser spesso oscurano pesantemente lo user agent a causa della sua difficoltà d'uso e per proteggere meglio la privacy degli utenti. In risposta a questo, Google supporta i client hint User-Agent, che sono inclusi nelle richieste di offerta quando disponibili per integrare l'intestazione User-Agent. Questi client hint (in breve) possono essere ricavati dalle intestazioni Sec-Ch-UA* o dall'API Client Hints di JavaScript.
L'intestazione User-Agent viene esposta come stringa nel campo BidRequest.device.ua.
Un messaggio UserAgent
verrà compilato con i client hint quando sono disponibili, ma
altrimenti verrà compilato in base ai valori analizzati dall'intestazione User-Agent. Questo
è esposto nel campo BidRequest.device.sua.
Gli offerenti sono vivamente invitati a utilizzare il messaggio UserAgent anziché la stringa
User-Agent.
Come viene compilato il UserAgent
A differenza dell'intestazione User-Agent, il messaggio UserAgent rappresenta le informazioni
sullo user agent suddivise in più campi per informazioni specifiche.
A seconda della disponibilità di Client Hints nella richiesta di annuncio, il messaggio
UserAgent può essere compilato nei seguenti modi:
- Se la richiesta contiene almeno
suggerimenti client
a bassa entropia,
UserAgentviene compilato in base ai relativi contenuti. - Se la richiesta contiene solo l'intestazione User-Agent,
UserAgentviene compilato in base a ciò che può essere analizzato dall'intestazione.
Esempio: compilazione di UserAgent in base all'intestazione User-Agent
Supponiamo che esista una richiesta di annuncio in cui il browser invia le seguenti intestazioni:
User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64)
AppleWebKit/537.36 (KHTML, like Gecko) Chrome/103.0.0.0 Safari/537.36
Un UserAgent compilato esclusivamente in base all'intestazione User-Agent potrebbe avere il seguente aspetto:
browsers: [{ brand: "Mozilla", version: ["5", "0"] },
{ brand: "AppleWebKit", version: ["537", "36"] },
{ brand: "Chrome", version: ["103", "0", "0", "0"] },
{ brand: "Safari", version: ["537", "36"] }],
platform: { brand: "Windows NT", version: ["10", "0"] },
mobile: false,
architecture: "x86",
bitness: "64",
model: "x64",
source: USER_AGENT_STRING
Esempio: compilazione di UserAgent in base agli hint client
Supponiamo che esista una richiesta di annuncio in cui il browser invia le seguenti intestazioni:
User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64)
AppleWebKit/537.36 (KHTML, like Gecko) Chrome/103.0.0.0 Safari/537.36
Sec-Ch-Ua: ".Not/A)Brand";v="99", "Google Chrome";v="103", "Chromium";v="103"
Sec-Ch-Ua-Arch: x86
Sec-Ch-Ua-Full-Version: 103.0.5060.134
Sec-Ch-Ua-Mobile: ?0
Sec-Ch-Ua-Platform: Windows
Sec-Ch-Ua-Platform-Version: 15.0.0
Nei casi in cui sono inclusi almeno i client hint a bassa entropia, UserAgent
verrà compilato in base ai contenuti di queste intestazioni anche se sono presenti intestazioni User-Agent. Avrà un aspetto simile al seguente:
browsers: [{ brand: ".Not/A)Brand", version: ["99", "0", "0", "0"] },
{ brand: "Google Chrome", version: ["103", "0", "5060", "134"] },
{ brand: "Chromium", version: ["103", "0", "5060", "134"] }],
platform: { brand: "Windows", version: ["15", "0", "0"] },
mobile: false,
architecture: "x86",
bitness: "64",
source: CLIENT_HINTS_HIGH_ENTROPY
Compilazione in base all'intestazione User-Agent anziché ai client hint
Alcuni campi vengono compilati in modo diverso a seconda che si basino sull'intestazione User-Agent o sui suggerimenti client. Di seguito è riportato un riepilogo di queste differenze:
- Per browser e piattaforme identici,
UserAgent.browsers.brandeUserAgent.platform.brandspesso differiscono tra unUserAgentin base all'intestazione User-Agent o ai suggerimenti per i client. Ad esempio,UserAgent.platform.brandpotrebbe essere visualizzato come "Windows NT" se fosse basato sull'intestazione User-Agent o come "Windows" se fosse basato sui client hint. - Alcune voci
UserAgent.browserssono univoche per l'intestazione User-Agent o per i client hint. Ad esempio, "AppleWebKit" verrà visualizzato seUserAgentsi basa sull'intestazione User-Agent, mentre "Chromium" verrà visualizzato solo se si basa sui suggerimenti client. - Solo un
UserAgentbasato sull'intestazione User-Agent può contenere valori bloccati. Ad esempio, se la piattaforma fosse Windows 11 22H2,UserAgent.platform.brandsarebbe impostato su "Windows NT" eUserAgent.platform.versionsarebbe impostato su[“10”, “0”]perché questo è il valore bloccato per qualsiasi versione di Windows pari o superiore a 10.
I dati in UserAgent basati sugli indizi del client normalmente non sono una
sostituzione imprecisa delle informazioni bloccate o oscurate. In caso di
incoerenza tra l'intestazione User-Agent e un UserAgent basato sui client
hint, devono essere preferite le informazioni del UserAgent.
Campi dell'oggetto UserAgent
Questa sezione riepiloga ogni campo, concentrandosi sul comportamento specifico di Google RTB e sulle best practice per l'utilizzo.
Browser
Contiene un elenco di voci BrandVersion generalmente ordinate per specificità. Ad esempio, se dovessi elencare i contenuti di browsers, il brand per ogni voce potrebbe essere visualizzato nel seguente ordine:
| Brand | Significato |
| Mozilla | Compatibile con Mozilla |
| AppleWebKit | Basato su AppleWebKit, un sottoinsieme di Mozilla. |
| Chrome | Browser Chrome, un sottoinsieme di browser compatibili con AppleWebKit |
| Safari | Variante desktop, anziché mobile. |
L'UserAgent non elencherà sempre i browser in un ordine specifico, soprattutto
se si basa sugli hint client. Di seguito sono descritte altre differenze
che puoi aspettarti di vedere in base al valore di source:
USER_AGENT: il campoversionpotrebbe essere ridotto a una versione principale o bloccato (a seconda delle norme specifiche dell'agente). Tieni presente che non ci sarà alcuna indicazione che il valore è bloccato.CLIENT_HINTS_LOW_ENTROPYeCLIENT_HINTS_HIGH_ENTROPY: le voci non sono ordinate in base a criteri; ad esempio, lo stesso browser potrebbe inviare queste voci in ordini diversi in ogni richiesta. Potrebbero contenere anche una voce GREASE, che deve essere ignorata.CLIENT_HINTS_HIGH_ENTROPY: Tutti i campiversiontrovati nei browser possono essere impostati sulle versioni complete.
Piattaforma
Una voce BrandVersion
che descrive la piattaforma. Potrebbe non essere compatibile con l'intestazione User-Agent e i suggerimenti per i client, pertanto il targeting di alcune piattaforme potrebbe richiedere il test di due nomi. Ad esempio, il sistema operativo Macintosh di Apple è indicato come
"Macintosh" nell'intestazione User-Agent, ma come "macOS" negli hint client.
Di seguito sono descritte altre differenze che puoi aspettarti in base al valore di source:
USER_AGENT: Il campoversionpotrebbe essere ridotto a una versione principale o bloccato. Tieni presente che non verrà visualizzata alcuna indicazione che il valore è bloccato.CLIENT_HINTS_LOW_ENTROPY: il campoversionnon verrà compilato.CLIENT_HINTS_HIGH_ENTROPY: Il campoversionpotrebbe essere impostato sulla versione completa.
Dispositivi mobili
Indica se contenuti come gli annunci devono essere ottimizzati per schermi di piccole dimensioni e/o input tattile. Tieni presente che questo non è necessariamente un indicatore del tipo di dispositivo, in quanto i browser mobile possono essere configurati per richiedere un "sito desktop".
Architettura
Identifica l'architettura della piattaforma, ad esempio "x86" o "arm".
Per un UserAgent basato su Client Hints, tieni presente che questo valore verrà compilato solo
quando source è impostato su CLIENT_HINTS_HIGH_ENTROPY.
Bitness
Identifica la bitness della piattaforma, ad esempio se ha una CPU a 32 bit o 64 bit. Il campo è una stringa di numeri interi che fornisce informazioni aggiuntive sulla sua architettura; ad esempio, un'architettura "x86" può avere una bitness impostata su "32" o "64".
Per un UserAgent basato su Client Hints, tieni presente che questo valore verrà compilato solo
quando source è impostato su CLIENT_HINTS_HIGH_ENTROPY.
Modello
Identifica il modello del dispositivo. Per i dispositivi mobili, ovvero non laptop o computer, questo campo verrà compilato con un nome del modello come "Pixel 6 Pro".
Di seguito sono descritte le differenze che puoi aspettarti in base al valore di source:
USER_AGENT- Dispositivi non mobili: il campo
modelspesso contiene un valore combinato di architettura e bitness, ad esempio "x64" per Windows. Questo valore non è multipiattaforma; ad esempio, Linux potrebbe utilizzare "x86_64" per lo stesso hardware. - Dispositivi mobili: questo campo non includerà l'architettura e la bitness.
Se ti interessano questi valori, consulta
UserAgent.architectureeUserAgent.bitness.
- Dispositivi non mobili: il campo
CLIENT_HINTS_LOW_ENTROPY: il campomodelnon verrà compilato.CLIENT_HINTS_HIGH_ENTROPY: il campomodelverrà compilato solo per il modello di dispositivo dei dispositivi mobili. Nessun valore è impostato per le piattaforme desktop.
Origine
Identifica le intestazioni utilizzate per creare UserAgent. Per i suggerimenti client,
questo distingue anche tra i due casi seguenti:
CLIENT_HINTS_LOW_ENTROPY: sono disponibili solo i client hint di base.CLIENT_HINTS_HIGH_ENTROPY: sono disponibili client hint, incluso almeno un campo classificato come ad alta entropia.