L'intestazione User-Agent è storicamente inclusa nelle richieste di offerta per fornire dati di targeting utili come il browser e la piattaforma del dispositivo che lo ha avviato. Tuttavia, i browser spesso oscurano in modo significativo lo user agent a causa della sua difficoltà di utilizzo e per proteggere meglio la privacy dell'utente. In risposta a ciò, Google supporta i client user agent, che sono inclusi nelle richieste di offerta, se disponibili, per integrare l'intestazione user agent. Questi client hint (in breve) possono essere recuperati dalle intestazioni Sec-Ch-UA* o dall'API JavaScript Client Hints.
A seconda del protocollo utilizzato, l'intestazione dello user agent viene esposta con uno dei seguenti campi di stringa:
- Google:
BidRequest.user_agent - OpenRTB:
BidRequest.device.ua
Un messaggio UserAgent verrà compilato con i client hint quando disponibili, ma in caso contrario verrà compilato in base ai valori analizzati dall'intestazione User-Agent. A seconda del protocollo utilizzato, verrà visualizzato uno dei seguenti campi:
- Google:
BidRequest.user_agent_data - OpenRTB:
BidRequest.device.sua
Consigliamo vivamente agli offerenti di usare il messaggio UserAgent anziché la stringa user agent.
Modalità di compilazione di UserAgent
A differenza dell'intestazione User-Agent, il messaggio UserAgent rappresenta le informazioni dello user agent suddivise in più campi per informazioni specifiche.
A seconda che i client hint siano disponibili nella richiesta di annuncio, il messaggio UserAgent può essere compilato nei seguenti modi:
- Se la richiesta contiene client hint almeno
a bassa entropia, il valore
UserAgentviene compilato in base ai relativi contenuti. - Se la richiesta contiene solo l'intestazione User-Agent, il campo
UserAgentviene completato in base a ciò che può essere analizzato dall'intestazione.
Esempio: compilazione di UserAgent in base all'intestazione user agent
Supponi 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 ai client hint
Supponi 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 vengono inclusi Client hint almeno a bassa entropia, UserAgent
verrà completato in base ai contenuti di queste intestazioni anche se sono presenti intestazioni
User-Agent. L'URL avrà il seguente aspetto:
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 e ai Client hint
Alcuni campi vengono compilati in modo diverso a seconda che si basino sull'intestazione user agent o sui client hint. Di seguito è riportato un riepilogo di queste differenze:
- Per browser e piattaforme identici,
UserAgent.browsers.brandeUserAgent.platform.brandsono spesso diversi da unaUserAgentin base all'intestazione User-Agent o ai Client hint. Ad esempio,UserAgent.platform.brandpotrebbe essere visualizzato come "Windows NT" se si basava sull'intestazione User-Agent o "Windows" se si basava sui client hint. - Alcune voci
UserAgent.browserssono univoche per l'intestazione user agent o per i client hint. Ad esempio, "AppleWebKit" verrebbe visualizzato seUserAgentsi basasse sull'intestazione User-Agent, mentre "Chromium" verrebbe visualizzato solo se si basava su Client Hints. - Solo un
UserAgentbasato sull'intestazione user agent può contenere valori bloccati. Ad esempio, se la piattaforma fosse Windows 11 22H2,UserAgent.platform.brandverrebbe impostato su "Windows NT" eUserAgent.platform.versionverrebbe impostato su[“10”, “0”]perché questo è il valore bloccato per qualsiasi versione di Windows pari o superiore a 10.
I dati in UserAgent basati sui client hint non sostituiscono in genere in modo accurato le informazioni bloccate o oscurate. In caso di incongruenze tra l'intestazione dello user agent e un valore UserAgent in base ai client hint, è preferibile utilizzare le informazioni provenienti da UserAgent.
Campi oggetto UserAgent
Questa sezione riassume ogni campo, con particolare attenzione al comportamento specifico delle RTB di Google e alle best practice per l'utilizzo.
Browser
Contiene un elenco di voci BrandVersion generalmente ordinate in base alla 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 per computer, anziché per dispositivo mobile. |
UserAgent non sempre elenca i browser in un ordine specifico, soprattutto se si basa sui client hint. Di seguito vengono descritte altre differenze
che potresti notare in base al valore di source:
USER_AGENT: il campoversionpotrebbe essere ridotto a una versione principale o bloccato (a seconda del criterio specifico dell'agente). Tieni presente che non verrà indicato che il valore è bloccato.CLIENT_HINTS_LOW_ENTROPYeCLIENT_HINTS_HIGH_ENTROPY: le voci non sono ordinate in base a nessun criterio; 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: è possibile impostare le versioni complete di tutti i campiversionpresenti nei browser.
Piattaforma
Una voce BrandVersion che descrive la piattaforma. Poiché potrebbe non essere compatibile con l'intestazione user agent e i client hint, il targeting di alcune piattaforme potrebbe richiedere il test di due nomi. Ad esempio, il sistema operativo Macintosh di Apple è contrassegnato come "Macintosh" nell'intestazione User-Agent, ma "macOS" nei client hint.
Di seguito vengono descritte altre differenze che potresti notare in base al valore di source:
USER_AGENT: il campoversionpotrebbe essere ridotto a una versione principale o bloccato. Tieni presente che non ci sarà alcuna indicazione che il valore sia bloccato.CLIENT_HINTS_LOW_ENTROPY: il campoversionnon verrà compilato.CLIENT_HINTS_HIGH_ENTROPY: il campoversionpuò essere impostato sulla versione completa.
Dispositivo mobile
Indica se i contenuti come gli annunci devono essere ottimizzati per gli schermi piccoli e/o l'input tocco. Tieni presente che questo non è necessariamente un indicatore del tipo di dispositivo, in quanto i browser per dispositivi mobili possono essere configurati in modo da richiedere un "sito desktop".
Architettura
Identifica l'architettura della piattaforma, ad esempio "x86" o "arm".
Per un valore UserAgent basato sui client hint, tieni presente che questo verrà completato solo
quando source è impostato su CLIENT_HINTS_HIGH_ENTROPY.
Numero di bit
Identifica il bit della piattaforma, ad esempio se ha una CPU a 32 o 64 bit. Il campo è una stringa intera che fornisce informazioni aggiuntive sulla sua architettura; ad esempio, un'architettura "x86" può avere un bitness impostato su "32" o "64".
Per un valore UserAgent basato sui client hint, tieni presente che questo verrà completato solo
quando source è impostato su CLIENT_HINTS_HIGH_ENTROPY.
Modello
Identifica il modello del dispositivo. Per i dispositivi mobili, non laptop o desktop, verrà inserito il nome del modello, ad esempio "Pixel 6 Pro".
Di seguito vengono descritte le differenze che potrebbero verificarsi in base al
valore di source:
USER_AGENT- Dispositivi non mobili: il campo
modelcontiene spesso 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 il numero di bit.
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 mobile. Non viene impostato alcun valore per le piattaforme desktop.
Origine
Identifica quali intestazioni sono state utilizzate per creare UserAgent. Per Client hint, viene effettuata una distinzione 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.