Targeting dello user agent

L'intestazione User-Agent è stata storicamente inclusa nelle richieste di offerta per fornire dati di targeting utili, come il browser e la piattaforma del dispositivo di invio. Tuttavia, spesso i browser oscurano notevolmente l'user agent a causa della sua difficoltà d'uso e per proteggere meglio la privacy degli utenti. In risposta a questo problema, Google supporta i client hint User-Agent, che vengono inclusi nelle richieste di offerta, se disponibili, per integrare l'intestazione User-Agent. Questi client hint (per brevità) possono essere ricavati dagli intestazioni Sec-Ch-UA* o dall'API Client Hints di JavaScript.

L'intestazione User-Agent viene visualizzata come stringa nel campo BidRequest.device.ua.

Un messaggio UserAgent viene compilato con i client hint quando sono disponibili, ma in caso contrario viene compilato in base ai valori analizzati dall'intestazione User-Agent. Questo valore è visualizzato nel campo BidRequest.device.sua.

Consigliamo vivamente agli offerenti di utilizzare il messaggio UserAgent anziché la stringa User-Agent.

Come viene compilato il campo 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 gli indicatori client siano disponibili nella richiesta di annuncio, il messaggioUserAgent può essere compilato nei seguenti modi:

• Se la richiesta contiene almeno un UserAgent Client Hints con entropia bassa, il valore viene completato in base ai relativi contenuti.
• Se la richiesta contiene solo l'intestazione User-Agent, UserAgent viene compilato in base a ciò che può essere analizzato dall'intestazione.

Nota: il campo source può essere utilizzato per distinguere ciò che viene utilizzato per compilare UserAgent. Ad esempio, se fosse impostato su USER_AGENT_STRING, ciò suggerirebbe che UserAgent è stato compilato in base ai contenuti delle intestazioni User-Agent.

Esempio: compilazione di UserAgent in base all'intestazione User-Agent

Supponiamo che esista una richiesta di annuncio in cui il browser invii 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

Supponiamo che esista una richiesta di annuncio in cui il browser invii 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

Se sono inclusi almeno client hint a bassa entropia, il campo UserAgent viene compilato in base ai contenuti di queste intestazioni anche se sono presenti intestazioni User-Agent. L'aspetto sarà 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

Completamento in base all'intestazione User-Agent rispetto ai client hint

Alcuni campi vengono compilati in modo diverso a seconda che si basino sull'intestazione User-Agent o sui Client Hints. Di seguito è riportato un riepilogo di queste differenze:

• Per piattaforme e browser identici, i valori UserAgent.browsers.brand e UserAgent.platform.brand saranno spesso diversi da un valore UserAgent in base all'intestazione User-Agent o ai client hint. Ad esempio,UserAgent.platform.brand potrebbe essere visualizzato come "Windows NT" se si basa sull'intestazione User-Agent o "Windows" se si basa sui client hint.
• Alcune voci UserAgent.browsers sono univoche per l'intestazione User-Agent o per i client hint. Ad esempio, "AppleWebKit" viene visualizzato se UserAgent si basa sull'intestazione User-Agent, mentre "Chromium" viene visualizzato solo se si basa 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" e UserAgent.platform.version su [“10”, “0”] perché è il valore congelato per qualsiasi versione di Windows pari o superiore a 10.

In genere, i dati in UserAgent basati su Client Hints non rappresentano un sostituzione imprecisa delle informazioni bloccate o oscurate. In caso di incoerenza tra l'intestazione User-Agent e un UserAgent basato su Client Hints, è preferibile dare la precedenza alle informazioni del UserAgent.

Campi dell'oggetto UserAgent

Questa sezione riassume ogni campo, con un'attenzione particolare al comportamento specifico di Google RTB e alle best practice per l'utilizzo.

Browser

Contiene un elenco di voci BrandVersion generalmente ordinate in base alla specificità. Ad esempio, se elencassi i contenuti di browsers, i valori brand di ogni voce potrebbero essere visualizzati 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	Versione desktop, rispetto a quella mobile.

UserAgent non elenca sempre i browser in un ordine specifico, soprattutto se si basa su Client Hints. Di seguito sono descritte altre differenze che puoi aspettarti di vedere in base al valore di source:

• USER_AGENT: il campo version può essere ridotto a una versione principale o bloccato (dipende dalle norme specifiche dell'agente). Tieni presente che non verrà visualizzata alcuna indicazione che il valore è bloccato.
• CLIENT_HINTS_LOW_ENTROPY e CLIENT_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 anche contenere un elemento GREASE, che deve essere ignorato.
• CLIENT_HINTS_HIGH_ENTROPY: tutti i campi version trovati nei browser possono essere impostati su versioni complete.

Piattaforma

Un'entrata BrandVersion che descrive la piattaforma. Questo potrebbe non essere compatibile con l'intestazione User-Agent e con Client Hints, pertanto il targeting di alcune piattaforme potrebbe richiedere il test di due nomi. Ad esempio, il sistema operativo Macintosh di Apple è identificato come "Macintosh" nell'intestazione User-Agent, ma come "macOS" in Client Hints. Di seguito sono descritte altre differenze che puoi aspettarti di vedere in base al valore di source:

• USER_AGENT: il campo version potrebbe essere ridotto a una versione principale o bloccato. Tieni presente che non verrà visualizzata alcuna indicazione del fatto che il valore è bloccato.
• CLIENT_HINTS_LOW_ENTROPY: il campo version non verrà compilato.
• CLIENT_HINTS_HIGH_ENTROPY: il campo version può essere impostato sulla versione completa.

Dispositivi mobili

Indica se i contenuti, come gli annunci, devono essere ottimizzati per schermi piccoli e/o input tocco. Tieni presente che questo non è necessariamente un indicatore del tipo di dispositivo, poiché i browser mobile possono essere configurati per richiedere un "sito desktop".

Architettura

Identifica l'architettura della piattaforma, ad esempio "x86" o "arm".

Tieni presente che per un UserAgent basato su Client Hints, questo valore verrà compilato solo quando source è impostato su CLIENT_HINTS_HIGH_ENTROPY.

Bitness

Identifica la piattaforma a 32 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 dimensione in bit impostata su "32" o "64".

Tieni presente che per un UserAgent basato su Client Hints, 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, verrà inserito il nome di un modello come "Pixel 6 Pro".

Di seguito sono descritte le differenze che puoi aspettarti di vedere in base al valore di source:

• USER_AGENT
  • Dispositivi non mobili: il campo model spesso contiene un valore combinato di architettura e accoppiamento a bit, ad esempio "x64" per Windows. Questo valore non è cross-platform; ad esempio, Linux potrebbe utilizzare "x86_64" per lo stesso hardware.
  • Dispositivi mobili: questo campo non include l'architettura e la dimensione in bit. Se ti interessano questi valori, consulta UserAgent.architecture e UserAgent.bitness.
• CLIENT_HINTS_LOW_ENTROPY: il campo model non verrà compilato.
• CLIENT_HINTS_HIGH_ENTROPY: il campo model verrà compilato solo per il modello di dispositivo mobile. Nessun valore è impostato per le piattaforme desktop.

Origine

Identifica le intestazioni utilizzate per creare il UserAgent. Per gli indicatori client, viene inoltre fatta distinzione tra i seguenti due casi:

• CLIENT_HINTS_LOW_ENTROPY: sono disponibili solo i client hint di base.
• CLIENT_HINTS_HIGH_ENTROPY: sono disponibili i client hint, incluso almeno un campo classificato come ad alta entropia.