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
UserAgent
viene compilato in base ai relativi contenuti. - Se la richiesta contiene solo l'intestazione User-Agent, il campo
UserAgent
viene 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.brand
eUserAgent.platform.brand
sono spesso diversi da unaUserAgent
in base all'intestazione User-Agent o ai Client hint. Ad esempio,UserAgent.platform.brand
potrebbe essere visualizzato come "Windows NT" se si basava sull'intestazione User-Agent o "Windows" se si basava sui client hint. - Alcune voci
UserAgent.browsers
sono univoche per l'intestazione user agent o per i client hint. Ad esempio, "AppleWebKit" verrebbe visualizzato seUserAgent
si basasse sull'intestazione User-Agent, mentre "Chromium" verrebbe visualizzato solo se si basava su Client Hints. - Solo un
UserAgent
basato sull'intestazione user agent può contenere valori bloccati. Ad esempio, se la piattaforma fosse Windows 11 22H2,UserAgent.platform.brand
verrebbe impostato su "Windows NT" eUserAgent.platform.version
verrebbe 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 campoversion
potrebbe 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_ENTROPY
eCLIENT_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 campiversion
presenti 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 campoversion
potrebbe 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 campoversion
non verrà compilato.CLIENT_HINTS_HIGH_ENTROPY
: il campoversion
può 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
model
contiene 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.architecture
eUserAgent.bitness
.
- Dispositivi non mobili: il campo
CLIENT_HINTS_LOW_ENTROPY
: il campomodel
non verrà compilato.CLIENT_HINTS_HIGH_ENTROPY
: il campomodel
verrà 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.