Definire i dati sul pubblico

Scopri come definire un segmento di pubblico creando un gruppo di interesse utilizzando l'API Protected Audience. Leggi la guida per gli sviluppatori per l'intero ciclo di vita dell'API Protected Audience e consulta la spiegazione dell'API Protected Audience per una proposta dettagliata su come i browser registrano i gruppi di interesse.

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

Gruppi basati sugli interessi dell'API Protected Audience

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

I proprietari dei gruppi di interesse agiscono come acquirenti nell'asta dell'API Protected Audience. L'appartenenza al gruppo basato sugli interessi viene archiviata dal browser sul dispositivo dell'utente e non viene condivisa con il fornitore del browser o 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 di appartenenza del browser.

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

joinAdInterestGroup() richiede l'autorizzazione di:

  • Il sito visitato
  • Il proprietario del gruppo basato sugli interessi

Ciò significa che malicious.example non può chiamare joinAdInterestGroup() per un gruppo basato sugli interessi di proprietà di dsp.example.com senza che dsp.example.com conceda l'autorizzazione.

Autorizzazione del sito visitato

L'autorizzazione può essere concessa dalla stessa origine o da origini diverse. Per impostazione predefinita, l'autorizzazione viene concessa per le chiamate joinAdInterestGroup() 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 farne parte.

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 superare i 50 KiB, altrimenti la chiamata non andrà a buon fine. Il secondo parametro specifica la durata del gruppo di interesse, con un limite di 30 giorni. Le chiamate successive sovrascrivono i valori memorizzati in precedenza.

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 di interesse.

Proprietà facoltative

Le proprietà rimanenti sono facoltative:

biddingLogicUrl1, 2
Esempio: https://dsp.example/bid/custom-bikes/bid.js
Ruolo: URL per l'esecuzione di JavaScript per le offerte nel worklet.
biddingWasmHelperUrl1, 2
Esempio: https://dsp.example/bid/custom-bikes/bid.wasm
Ruolo: URL del codice WebAssembly derivato da biddingLogicUrl.
updateUrl2
Esempio: https://dsp.example/bid/custom-bikes/update
Ruolo: URL che restituisce JSON per aggiornare gli attributi del gruppo di interesse. (Consulta la sezione Aggiornare i dati dei segmenti di pubblico e aggiornare gli annunci).
trustedBiddingSignalsUrl2
Esempio: https://dsp.example/trusted/bidding-signals
Ruolo: URL di base per le richieste di coppie chiave-valore al servizio chiavi/valori 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 l'offerta.
ads1
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ù parti.

1 Le proprietà biddingLogicUrl e ads sono facoltative, ma obbligatorie per partecipare a un'asta. Potrebbero esistere casi d'uso per la creazione di un gruppo di interesse 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 in esecuzione o per un altro utilizzo futuro oppure potrebbe aver esaurito temporaneamente il budget pubblicitario.

2 Nell'implementazione attuale 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 presentano questo vincolo.

Specificare gli annunci per un gruppo di interesse

Gli oggetti ads e adComponents includono un URL per una creatività pubblicitaria 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 dal suo elenco di membri.

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

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

Il codice di un annuncio può anche chiamare questa funzione per il suo 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 basati sugli interessi per proprietario e fino a 1000 proprietari di gruppi basati sugli interessi. Questi limiti sono pensati come misure di protezione, non per essere raggiunti durante il normale funzionamento.

Come faccio a massimizzare gli annunci dei gruppi di interesse che soddisfano le soglie di 𝑘-anonimato?

Come indicato nella spiegazione pubblica, poiché un singolo gruppo di interesse può contenere più annunci possibili da mostrare, il gruppo avrà l'opportunità di fare un'offerta per un altro dei suoi annunci in modo che funga da "annuncio di riserva" ogni volta che la sua scelta preferita è al di sotto della soglia. Ciò significa che un annuncio piccolo e specializzato che non ha ancora raggiunto la soglia di k-anonimato può comunque scegliere di partecipare alle aste e il suo gruppo di interesse ha un modo per ripiegare su un annuncio più generico finché quello più specializzato non ha un pubblico sufficientemente ampio.

Da un punto di vista tattico, puoi prendere in considerazione quanto segue:

  • Per iniziare a pubblicare un nuovo annuncio, inizia a fare offerte per l'annuncio nei casi in cui vuoi che venga mostrato. Non devi fare altro.
  • Puoi avere un annuncio di riserva da utilizzare quando i nuovi annunci non sono 𝑘-anonimi. Esiste un certo rischio che l'annuncio di riserva non sia 𝑘-anon, quindi potresti prendere in considerazione l'idea di fare offerte direttamente con l'annuncio di riserva. Ad esempio, puoi farlo l'1% delle volte, se questo è un buon livello per assicurarti che il fallback rimanga al di sopra della soglia.

Di recente si è discusso di altri modi in cui le cose potrebbero funzionare, quindi se hai un caso d'uso per il quale questo meccanismo potrebbe rappresentare un problema, continua a partecipare alla conversazione pubblica sui modi in cui l'API potrebbe migliorare.

Tutti i riferimenti all'API Protected Audience

Sono disponibili guide di riferimento API:

Il messaggio esplicativo dell'API Protected Audience fornisce anche dettagli sul supporto e sui vincoli delle funzionalità.