Questa pagina è stata tradotta dall'API Cloud Translation.

Definisci i dati relativi al pubblico

Scopri come definire un segmento di pubblico creando un gruppo basato sugli interessi utilizzando l'API Protected Audience. Leggi la guida per gli sviluppatori per conoscere l'intero ciclo di vita dell'API Protected Audience e consulta il messaggio esplicativo dell'API Protected Audience per una proposta approfondita su come i browser registrano i gruppi basati sugli interessi.

Non sei uno sviluppatore? Consulta la panoramica dell'API Protected Audience.

Gruppi basati sugli interessi dell'API Protected Audience

Un gruppo basato sugli interessi dell'API Protected Audience rappresenta un gruppo di persone con un interesse comune, corrispondente a un elenco per il remarketing. Ogni gruppo basato sugli interessi dell'API Protected Audience ha un proprietario.

I proprietari di gruppi di interesse agiscono come acquirente nell'asta dell'annuncio dell'API Protected Audience. L'appartenenza ai gruppi di interesse viene memorizzata dal browser sul dispositivo dell'utente e non viene condivisa con il fornitore del browser né con altri.

Funzioni API

`joinAdInterestGroup()`

La Demand-Side Platform (DSP) dell'inserzionista o l'inserzionista stesso chiama navigator.joinAdInterestGroup() per chiedere al browser di aggiungere un gruppo basato sugli interessi all'elenco dei membri del browser.

L'origine del contesto di chiamata per joinAdInterestGroup() deve corrispondere all'origine del proprietario del gruppo di interesse, quindi joinAdInterestGroup() dovrà essere chiamato da un iframe (ad esempio, da una DSP) a meno che l'origine del proprietario del gruppo di interesse non corrisponda all'origine del documento corrente (ad esempio, un sito web con i propri gruppi di interesse).

joinAdInterestGroup() richiede l'autorizzazione di:

Il sito visitato
Proprietario del gruppo di interesse

Questo significa che malicious.example non può chiamare joinAdInterestGroup() per un gruppo di interesse di proprietà di dsp.example.com senza l'autorizzazione di dsp.example.com.

Autorizzazione dal sito visitato

L'autorizzazione può essere concessa dalla stessa origine o multiorigine. Per impostazione predefinita, l'autorizzazione viene concessa per le chiamate joinAdInterestGroup() provenienti dalla stessa origine del sito visitato, ovvero dalla stessa origine del frame di primo livello della pagina corrente.

Esempio di utilizzo

Ecco un esempio di come si potrebbe definire un gruppo basato sugli interessi e chiedere al browser di unirsi al gruppo.

const interestGroup = {
  owner: 'https://dsp.example',
  name: 'custom-bikes',
  biddingLogicUrl: ...,
  biddingWasmHelperUrl: ...,
  updateUrl: ...,
  trustedBiddingSignalsUrl: ...,
  trustedBiddingSignalsKeys: ['key1', 'key2'],
  userBiddingSignals: {...},
  ads: [bikeAd1, bikeAd2, bikeAd3],
  adComponents: [customBike1, customBike2, bikePedal, bikeFrame1, bikeFrame2],
};

navigator.joinAdInterestGroup(interestGroup, 7 * kSecsPerDay);

L'oggetto interestGroup passato alla funzione non deve avere una dimensione superiore a 50 kiB, altrimenti la chiamata non riuscirà. Il secondo parametro specifica la durata del gruppo basato sugli interessi, limitata a 30 giorni. Le chiamate successive sovrascriveranno i valori memorizzati in precedenza.

Punto chiave:tutti gli URL utilizzati come parametri per i metodi dell'API Protected Audience devono provenire da origini sicure: tutte le risorse devono essere pubblicate tramite URL HTTPS. Come utilizzare HTTPS per lo sviluppo locale spiega come farlo quando si esegue l'API Protected Audience localmente. Inoltre, biddingLogicUrl, decisionLogicUrl e trustedBiddingSignals richiedono un'intestazione della risposta HTTP X-Allow-FLEDGE: true.

Proprietà obbligatorie

Le uniche proprietà obbligatorie per i gruppi di interesse sono owner e name:

Proprietà	Esempio	Ruolo
`owner`	`https://dsp.example`	Origine del proprietario del gruppo di interesse.
`name`	`custom-bikes`	Nome del gruppo basato sugli interessi.

Proprietà facoltative

Le altre proprietà sono facoltative:

biddingLogicUrl^{1, 2}: Esempio: https://dsp.example/bid/custom-bikes/bid.js; Ruolo: URL per l'esecuzione di JavaScript per le offerte nel worklet.
biddingWasmHelperUrl^{1, 2}: Esempio: https://dsp.example/bid/custom-bikes/bid.wasm; Ruolo: URL del codice WebAssembly generato da biddingLogicUrl.
updateUrl²: Esempio: https://dsp.example/bid/custom-bikes/update; Ruolo: URL che restituisce un file JSON per aggiornare gli attributi dei gruppi di interesse. Consulta Aggiornare i dati sul pubblico e aggiornare gli annunci.
trustedBiddingSignalsUrl²: Esempio: https://dsp.example/trusted/bidding-signals; Ruolo: URL di base per le richieste chiave-valore al servizio chiave/valore attendibile dell'offerente.
trustedBiddingSignalsKeys: Esempio: ['key1', 'key2' ...]; Ruolo: chiavi per le richieste al servizio chiave-valore attendibile.
userBiddingSignals: Esempio: {...}; Ruolo: metadati aggiuntivi che il proprietario può utilizzare durante le offerte.
ads¹: Esempio: [bikeAd1, bikeAd2, bikeAd3]; Ruolo: annunci che potrebbero essere visualizzati per questo gruppo basato sugli interessi.
adComponents: Esempio: [customBike1, customBike2, bikePedal, bikeFrame1, bikeFrame2]; Ruolo: componenti per annunci composti da più elementi.

¹ Le proprietà biddingLogicUrl e ads sono facoltative, ma obbligatorie per partecipare a un'asta. Potrebbero verificarsi casi d'uso per la creazione di un gruppo basato sugli interessi senza queste proprietà: ad esempio, il proprietario di un gruppo di interesse potrebbe voler aggiungere un browser a un gruppo di interesse per una campagna non ancora pubblicata o per un altro utilizzo futuro oppure potrebbe aver esaurito temporaneamente il budget pubblicitario.

² Nell'attuale implementazione dell'API Protected Audience, biddingLogicUrl, biddingWasmHelperUrl, updateUrl e trustedBiddingSignalsUrl devono avere la stessa origine del proprietario. Potrebbe non trattarsi di un vincolo a lungo termine e gli URL ads e adComponents non hanno questo vincolo.

Specificare gli annunci per un gruppo di interesse

Gli oggetti ads e adComponents includono un URL per una creatività dell'annuncio e, facoltativamente, metadati arbitrari che possono essere utilizzati al momento dell'offerta.

Ad esempio:

{
  renderUrl: 'https://cdn.example/.../bikeAd1.html',
  metadata: bikeAd1metadata // optional
}

`leaveAdInterestGroup()`

Il proprietario del gruppo di interesse può richiedere la rimozione di un browser da un gruppo di interesse. Il browser rimuove il gruppo di interesse dall'elenco dei membri.

navigator.leaveAdInterestGroup({
  owner: 'https://dsp.example',
  name: 'custom-bikes'
});

Se un utente torna sul sito che ha chiesto al browser di aggiungere un gruppo di interesse, il proprietario del gruppo di interesse può chiamare la funzione navigator.leaveAdInterestGroup() per richiedere al browser di rimuovere il gruppo di interesse.

Il codice di un annuncio può chiamare questa funzione anche per il relativo gruppo di interesse.

Domande frequenti

Qual è il numero massimo di gruppi di interesse per proprietario di gruppo per un singolo utente?

Chrome consente fino a 1000 gruppi di interesse per proprietario e fino a 1000 proprietari di gruppi di interesse. Questi limiti sono intesi come guard rail, non devono essere raggiunti durante il normale funzionamento.

Come faccio a massimizzare gli annunci basati sul gruppo di interesse che soddisfano le soglie k-anon?

Come indicato nella spiegazione pubblica, poiché un singolo gruppo basato sugli interessi può includere più annunci possibili, il gruppo avrà l'opportunità di rifare un'offerta per un altro dei suoi annunci affinché agisca come "annuncio di riserva". ogni volta che la sua opzione preferita è al di sotto della soglia. Ciò significa che un piccolo annuncio specializzato, ma ancora al di sotto della soglia di k-anonymity, potrebbe comunque scegliere di partecipare alle aste e il gruppo basato sugli interessi ha un modo per passare a un annuncio più generico fino a quando quello più specializzato non raggiunge un pubblico sufficientemente ampio.

Da un punto di vista tattico, potresti considerare quanto segue:

Per fare in modo che un nuovo annuncio inizi a essere pubblicato, inizia a fare offerte con questo annuncio nei casi in cui vuoi che venga pubblicato. Non devi fare nulla.
Puoi avere un annuncio di riserva da utilizzare quando non esistono nuovi annunci. Esiste un rischio che il tuo annuncio di riserva non sia k-anon, quindi potresti prendere in considerazione a volte solo fare offerte con l'annuncio di riserva. Potresti farlo l'1% delle volte, ad esempio se questo è un buon livello per assicurarti che la riserva rimanga oltre la soglia.

Di recente si è parlato di altri modi in cui le cose potrebbero funzionare, quindi se hai dei casi d'uso in cui questo meccanismo potrebbe rappresentare un problema, continua a parlare pubblicamente di come l'API potrebbe migliorare.

Tutti i riferimenti all'API Protected Audience

API reference guides are available:

Developer guide for the Protected Audience API.
Ad buyer guide to Protected Audience interest groups and bid generation.
Ad seller guide to Protected Audience ad auctions.
Guide to reporting auction results
Best practices for Protected Audience ad auction latency
Troubleshoot Protected Audience

The Protected Audience API explainer also provides detail about feature support and constraints.