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.
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
2- 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
2- 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
1- 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.
1 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.
2 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à.