Definisci i dati relativi al pubblico

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

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

Gruppi di interesse 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 del gruppo di interesse agiscono come acquirente nell'asta dell'annuncio dell'API Protected Audience. L'appartenenza al gruppo di interesse viene memorizzata dal browser sul dispositivo dell'utente e non viene condivisa con il fornitore del browser o con nessun altro.

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 membri del browser.

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

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 di interesse di proprietà di dsp.example.com senza che dsp.example.com abbia concesso l'autorizzazione.

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 di interesse 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);

Le dimensioni dell'oggetto interestGroup passato alla funzione non devono superare i 50 kiB, altrimenti la chiamata avrà esito negativo. Il secondo parametro specifica la durata del gruppo basato sugli interessi, con un limite di 30 giorni. Le chiamate successive sovrascrivono 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 gestite tramite URL HTTPS. Come utilizzare HTTPS per lo sviluppo locale spiega come fare 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 di interesse.

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 per WebAssembly basato su codice da biddingLogicUrl.

updateUrl²

Esempio: https://dsp.example/bid/custom-bikes/update

Ruolo: URL che restituisce 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 di coppie chiave-valore al servizio chiave/valore attendibile dell'offerente.

trustedBiddingSignalsKeys

Esempio: ['key1', 'key2' ...]

Ruolo: chiavi per le richieste al servizio chiavi/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 di interesse.

adComponents

Esempio: [customBike1, customBike2, bikePedal, bikeFrame1, bikeFrame2]

Ruolo: componenti per annunci composti da più parti.

¹ Le proprietà biddingLogicUrl e ads sono facoltative, ma necessarie per partecipare a un'asta. Ci possono essere casi d'uso per creare 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 pubblicata o per altri utilizzi futuri 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 essere un vincolo a lungo termine e gli URL ads e adComponents non hanno questo vincolo.

Specifica 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 dal proprio elenco di appartenenza.

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

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

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 del 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 sistemi di protezione e non devono essere raggiunti nel funzionamento regolare.

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

Come indicato nel spiegamento pubblico, poiché un singolo gruppo di interesse può includere più annunci possibili che potrebbe essere mostrato, il gruppo avrà l'opportunità di ripetere l'offerta per un altro dei suoi annunci in modo che agisca come "annuncio di riserva" ogni volta che la sua scelta più preferita è inferiore alla soglia. Ciò significa che un annuncio di piccole dimensioni specializzato che è ancora al di sotto della soglia di k-anonymity potrebbe comunque scegliere di partecipare alle aste e il suo gruppo di interesse ha la possibilità di optare per un annuncio più generico fino a quando quello più specializzato non avrà un pubblico sufficientemente ampio.

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

• Per fare in modo che un nuovo annuncio inizi a essere pubblicato, inizia a utilizzare le offerte nei casi in cui vuoi che venga pubblicato. Non devi fare altro.
• Puoi avere un annuncio di riserva da utilizzare quando i nuovi annunci non sono k-anon. Esiste il rischio che il tuo annuncio di riserva non venga considerato k-anon, pertanto, a volte, potresti valutare la possibilità di fare offerte solo con l'annuncio di riserva. Esegui questa operazione l'1% delle volte, ad esempio, se si tratta di un buon livello per assicurarti che il fallback mantenga una soglia superiore.

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

Tutti i riferimenti dell'API Protected Audience

Sono disponibili guide di riferimento API:

• Guida per gli sviluppatori relativa all'API Protected Audience.
• Guida per gli acquirenti di annunci ai gruppi di interesse e alla generazione di offerte di Protected Audience.
• Guida per i venditori di annunci alle aste degli annunci di Protected Audience.
• Guida per generare report sui risultati dell'asta
• Best practice per la latenza dell'asta dell'annuncio di Protected Audience
• Risolvere i problemi relativi a Protected Audience

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