Guida per gli sviluppatori per aste degli annunci on-device, al fine di raggiungere segmenti di pubblico personalizzati e per il remarketing senza il monitoraggio di terze parti tra siti.
Se non conosci l'API Protected Audience, leggi la panoramica dell'API Protected Audience per una spiegazione generale dell'API.
Questo post è rivolto agli sviluppatori come riferimento tecnico per l'iterazione più recente dell'API Protected Audience sperimentale. È disponibile una demo di un deployment di base dell'API Protected Audience, così come i riferimenti API per gli acquirenti e i venditori di annunci.
Stato implementazione
- La proposta dell'API Protected Audience sta ora passando alla disponibilità generale. Fai domande e segui la discussione.
- Lo stato dell'API Protected Audience delle funzionalità in attesa descrive in dettaglio le modifiche e i miglioramenti all'API e alle funzionalità dell'API Protected Audience.
- Stato della spia lampeggiante
- Stato della piattaforma Chrome dell'API Protected Audience: specifico per l'API Protected Audience su Chrome.
- Stato della piattaforma Chrome dell'API Ads: una raccolta di API per facilitare la pubblicità: API Protected Audience, Topics, Fenced Frame e Attribution Reporting.
Per ricevere notifiche sui cambiamenti di stato nell'API, unisciti alla mailing list per gli sviluppatori.
Che cos'è l'API Protected Audience?
L'API Protected Audience è un'API di Privacy Sandbox progettata per gestire casi d'uso di remarketing e segmenti di pubblico personalizzati, progettata in modo che non possa essere utilizzata da terze parti per monitorare il comportamento di navigazione degli utenti sui siti. L'API attiva le aste on-device da parte del browser per scegliere annunci pertinenti per i siti web che l'utente ha visitato in precedenza.
L'API Protected Audience è il primo esperimento implementato in Chromium all'interno della famiglia di proposte TURTLEDOVE.
Prova l'API Protected Audience
Riferimento API disponibile
Questo documento offre una panoramica dell'API Protected Audience. Se stai cercando metodi e parametri dell'API specifici:
- Guida per gli acquirenti per
joinAdInterestGroup()
egenerateBid()
. - Guida per il venditore all'API Protected Audience
runAdAuction()
- Guida per gli acquirenti a
reportWin()
e guida per i venditori areportResult()
- Risolvere i problemi relativi all'API Protected Audience
Puoi anche leggere le best practice relative alla latenza dell'asta dell'annuncio dell'API Protected Audience.
Demo dell'API Protected Audience
Una panoramica dell'implementazione di base dell'API Protected Audience nei siti di inserzionisti e publisher è disponibile all'indirizzo secure-audience-demo.web.app/.
Testa questa API
Puoi testare l'API Protected Audience per un singolo utente in Chrome Beta 101.0.4951.26 e versioni successive su computer:
- Attiva tutte le API di privacy per gli annunci in
chrome://settings/adPrivacy
. - Imposta i flag dalla riga di comando. L'elenco completo delle segnalazioni dell'API Protected Audience è disponibile in Ricerca codice di Chromium.
Visualizzare gli annunci in iframe o frame esclusi
Gli annunci possono essere visualizzati in <iframe>
o
<fencedframe>
, a seconda dei
flag impostati.
Per utilizzare <fencedframe>
al fine di eseguire il rendering degli annunci:
--enable-features=InterestGroupStorage,AdInterestGroupAPI,Fledge,FencedFrames
Per utilizzare <iframe>
al fine di eseguire il rendering degli annunci:
--enable-features=InterestGroupStorage,AdInterestGroupAPI,Fledge,AllowURNsInIframes --disable-features=FencedFrames
Includi il flag BiddingAndScoringDebugReportingAPI
per abilitare i
metodi di segnalazione della perdita/delle vittorie per il debug temporaneo.
Funzionalità supportate
L'API Protected Audience dietro le segnalazioni di funzionalità in Chromium è un primo esperimento per testare le seguenti funzionalità dell'API Protected Audience:
- Gruppi di interesse: memorizzati dal browser, con metadati associati per configurare le offerte e il rendering degli annunci.
- Offerte on-device da parte degli acquirenti (DSP o inserzionista): in base ai gruppi di interesse e agli indicatori del venditore memorizzati.
- Selezione degli annunci sul dispositivo da parte del venditore (SSP o publisher): in base alle offerte per l'asta e ai metadati degli acquirenti.
- Rendering degli annunci in una versione temporaneamente rilassata dei frame recintati: con accesso alla rete e logging consentiti per il rendering degli annunci.
Scopri di più sul supporto e sui vincoli delle funzionalità nella spiegazione dell'API Protected Audience.
Autorizzazioni per i gruppi di interesse
L'impostazione predefinita per l'attuale implementazione dell'API Protected Audience è consentire le chiamate a joinAdInterestGroup()
da qualsiasi punto della pagina, anche da iframe interdominio.
In futuro, una volta che i proprietari dei siti avranno avuto il tempo di aggiornare le norme sulle autorizzazioni degli iframe interdominio, prevediamo di non consentire le chiamate da iframe interdominio.
Servizio chiave/valore
Per supportare l'asta dell'annuncio dell'API Protected Audience, il browser può accedere a un servizio chiave/valore per recuperare informazioni in tempo reale che supportano l'asta dell'annuncio dell'API Protected Audience. Queste informazioni possono essere utilizzate in vari modi:
- Gli acquirenti potrebbero voler calcolare il budget rimanente in una campagna pubblicitaria.
- Ai venditori potrebbe essere richiesto di verificare la conformità delle creatività degli annunci alle norme dei publisher.
Ora è disponibile il codice del servizio chiave/valore dell'API Protected Audience. Per l'aggiornamento dello stato, consulta il post del blog dell'annuncio.
Per il test iniziale, è stato introdotto un modello "Bring Your Own Server". Nel lungo periodo, i tecnici pubblicitari dovranno utilizzare i servizi chiave/valore open source dell'API Protected Audience in esecuzione in ambienti di esecuzione attendibili.
Per gli aggiornamenti sulle tempistiche, consulta il post del blog sui servizi dell'API Protected Audience. Daremo agli sviluppatori un preavviso significativo per iniziare i test e l'adozione prima della transizione.
Supporto delle funzionalità di Detect
Prima di utilizzare l'API, verifica che sia supportata dal browser e disponibile nel documento:
'joinAdInterestGroup' in navigator &&
document.featurePolicy.allowsFeature('join-ad-interest-group') &&
document.featurePolicy.allowsFeature('run-ad-auction') ?
console.log('navigator.joinAdInterestGroup() is supported on this page') :
console.log('navigator.joinAdInterestGroup() is not supported on this page');
Come funziona l'API Protected Audience?
In questo esempio, un utente naviga nel sito web di un produttore di biciclette personalizzate, poi visita un sito web di notizie e visualizza un annuncio per una nuova bicicletta del produttore.
Nel tempo verranno aggiunte funzionalità dell'API Protected Audience man mano che l'implementazione procede.
1. Un utente visita il sito di un inserzionista
![Una persona che visita il sito di un produttore di biciclette personalizzate in un browser sul laptop.](https://developers.google.cn/static/privacy-sandbox/assets/images/a-person-visiting-custom-2ca7094e57259.png?authuser=6&hl=it)
Immagina che un utente visiti il sito web di un produttore di biciclette personalizzate (l'inserzionista) in questo esempio e trascorra del tempo sulla pagina del prodotto di una bicicletta in acciaio fatta a mano. Questo offre al produttore di biciclette un'opportunità di remarketing.
2. Al browser dell'utente viene chiesto di aggiungere un gruppo basato sugli interessi
![Un utente apre un browser sul laptop e visita un sito. Il codice JavaScript per partecipare ai gruppi basati sugli interessi degli annunci viene eseguito nel browser.](https://developers.google.cn/static/privacy-sandbox/assets/images/a-user-opens-browser-th-6c2a4e6d97af7.png?authuser=6&hl=it)
La Demand-Side Platform (DSP) dell'inserzionista (o l'inserzionista stesso) chiama
navigator.joinAdInterestGroup()
per chiedere al browser di aggiungere un gruppo di interesse
all'elenco dei gruppi di cui il browser fa parte.
In questo esempio, il gruppo è denominato custom-bikes
e il proprietario è dsp.example
. Il proprietario del gruppo di interesse (in questo caso, la DSP) sarà un acquirente
nell'asta dell'annuncio dell'API Protected Audience. L'appartenenza ai gruppi di interesse viene archiviata dal browser sul dispositivo dell'utente e non viene condivisa con il fornitore del browser né con altri.
- Leggi l'articolo esplicativo dell'API Protected Audience: Browsers Record Interest Groups.
- Leggi la guida alle API: acquirenti e DSP, scopri come
joinAdInterestGroup()
e come generare offerte.
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
}
In che modo gli acquirenti fanno le offerte?
generateBid()
viene chiamato per ogni gruppo basato sugli interessi di cui il browser fa parte
se il proprietario del gruppo basato sugli interessi è invitato a fare offerte.
Leggi la documentazione per gli sviluppatori di generatedBid()
.
3. L'utente visita un sito che vende spazio pubblicitario
![Una persona visita un sito web di notizie in un browser sul laptop. Il sito ha un'area annuncio vuota.](https://developers.google.cn/static/privacy-sandbox/assets/images/a-person-visits-news-web-3209fc4021a42.png?authuser=6&hl=it)
In seguito, l'utente visita un sito che vende spazio pubblicitario, in questo esempio un sito web di notizie. Il sito dispone di un inventario pubblicitario che vende in modo programmatico tramite le offerte in tempo reale.
4. Nel browser viene eseguita un'asta dell'annuncio
![Una persona visualizza un sito web di notizie in un browser sul laptop. Viene eseguita un'asta dell'annuncio dell'API Protected Audience per scegliere un annuncio per lo spazio pubblicitario disponibile.](https://developers.google.cn/static/privacy-sandbox/assets/images/a-person-views-news-webs-32cbfd93dc442.png?authuser=6&hl=it)
È probabile che l'asta dell'annuncio venga gestita dal Supply-Side Provider (SSP) del publisher o dal publisher stesso. Lo scopo dell'asta è selezionare l'annuncio più appropriato per una singola area annuncio disponibile nella pagina corrente. L'asta prende in considerazione i gruppi di interesse di cui il browser fa parte, oltre ai dati degli acquirenti dello spazio pubblicitario e dei venditori dei servizi chiave/valore.
- Leggi la spiegazione dell'API Protected Audience: I venditori eseguono aste sul dispositivo
- Leggi la guida alle API: i venditori possono scoprire di più su
runAdAuction()
e sulle best practice per la latenza dell'asta dell'annuncio.
5. Il venditore e gli acquirenti partecipanti richiedono i dati in tempo reale al servizio chiave/valore.
![L'utente visualizza un sito web di notizie in un browser sul laptop. È in corso un'asta dell'annuncio con l'API Protected Audience, con un partecipante che riceve dati dal servizio chiave/valore.](https://developers.google.cn/static/privacy-sandbox/assets/images/the-user-views-news-webs-6969c01094b4.png?authuser=6&hl=it)
Durante un'asta dell'annuncio, il venditore può richiedere dati in tempo reale su specifiche creatività pubblicitarie
inviando una richiesta al proprio servizio chiave/valore.
Il venditore può richiedere queste informazioni durante
runAdAuction()
dalla proprietà trustedScoringSignalsUrl
,
insieme alle chiavi delle proprietà renderUrl
di tutte le voci nei campi ads
e adComponents
di tutti i gruppi di interesse nell'asta.
Un acquirente può richiedere dati in tempo reale al proprio servizio chiave/valore utilizzando le proprietà trustedBiddingSignalsUrl
e trustedBiddingSignalsKeys
dell'argomento gruppo di interesse passato a navigator.joinAdInterestGroup()
.
Quando viene chiamato runAdAuction()
, il browser invia una richiesta al server affidabile di ogni acquirente di annunci. L'URL della richiesta potrebbe essere simile al seguente:
https://kv-service.example/getvalues?hostname=publisher.example&keys=key1,key2
- L'URL di base proviene da
trustedBiddingSignalsUrl
. hostname
viene fornito dal browser.- Il valore
keys
deriva datrustedBiddingSignalsKeys
.
La risposta a questa richiesta è un oggetto JSON che fornisce i valori per ciascuna delle chiavi.
- Leggi la spiegazione dell'API Protected Audience: Recupero dei dati in tempo reale dal servizio chiave/valore dell'API Protected Audience.
- Leggi l'articolo sull'open source del servizio chiave/valore dell'API Protected Audience.
6. Viene visualizzato l'annuncio vincente
![Una persona visualizza un sito web di notizie in un browser sul laptop. Un annuncio
per uno sconto del 20% su una bicicletta è mostrato in un telaio sicuro e recintato.](https://developers.google.cn/static/privacy-sandbox/assets/images/a-person-views-news-webs-2dc1236041c17.png?authuser=6&hl=it)
La promessa restituita da runAdAuction() si risolve in un oggetto di configurazione di frame recintati (FencedFrameConfig
) quando il flag resolveToConfig
è impostato su true
nella configurazione delle aste. La configurazione del frame viene utilizzata da un frame recintato per passare all'annuncio vincente, ma l'URL dell'annuncio non è visibile all'incorporamento del frame.
L'oggetto di configurazione del frame protetto è disponibile a partire dalla versione M114. Per ulteriori informazioni sull'oggetto FencedFrameConfig
, consulta l'articolo del blog di Chrome.
- Leggi la spiegazione dell'API Protected Audience: i browser eseguono il rendering dell'annuncio vincente
7. Il risultato dell'asta viene registrato
Il piano a lungo termine prevede che il browser possa generare report sui risultati delle aste per il venditore e gli acquirenti utilizzando le API Private Aggregation.
Come meccanismo temporaneo di generazione di report a livello di evento, il codice che implementa
reportResult()
per il venditore e reportWin()
per l'offerente vincente può
chiamare la funzione sendReportTo()
. Prende un singolo argomento: una stringa che rappresenta un URL recuperato al termine dell'asta, che codifica le informazioni a livello di evento da inserire nel report.
- Leggi la guida alle API: scopri di più sui report sui venditori e sugli acquirenti
8. Viene registrato un clic sull'annuncio
![Una persona fa clic su un annuncio relativo a una bicicletta incorporata in un telaio recintato in un sito web di notizie. I dati del report vengono inviati al venditore e agli acquirenti.](https://developers.google.cn/static/privacy-sandbox/assets/images/a-person-clicks-an-ad-a-be2111724646f.png?authuser=6&hl=it)
Viene segnalato un clic su un annuncio visualizzato in un frame recintato. Per ulteriori informazioni su come potrebbe funzionare, consulta Report sugli annunci relativi a frame schermati.
![Una panoramica di ogni fase di un'asta dell'annuncio dell'API Protected Audience](https://developers.google.cn/static/privacy-sandbox/assets/images/an-overview-each-stage-c8bac3c2c070f.png?authuser=6&hl=it)
Qual è la differenza tra l'API Protected Audience e TURTLEDOVE?
L'API Protected Audience è il primo esperimento implementato in Chromium all'interno della famiglia di proposte TURTLEDOVE.
L'API Protected Audience segue i principi generali di TURTLEDOVE. Alcune pubblicità online si basano sulla pubblicazione di un annuncio per una persona potenzialmente interessata che ha precedentemente interagito con l'inserzionista o la rete pubblicitaria. Storicamente, a questo scopo l'inserzionista riconosceva una persona specifica mentre naviga tra i siti web, una preoccupazione fondamentale della privacy nel web di oggi.
L'impegno di TURTLEDOVE consiste nell'offrire una nuova API per affrontare questo caso d'uso, offrendo al contempo alcuni progressi chiave in materia di privacy:
- Il browser, non l'inserzionista, contiene le informazioni sugli interessi di una persona secondo cui l'inserzionista.
- Gli inserzionisti possono pubblicare annunci in base a un interesse, ma non possono combinarlo con altre informazioni su una persona, in particolare il suo nome o la pagina che sta visitando.
L'API Protected Audience è nata da TURTLEDOVE e da una raccolta di proposte correlate per le modifiche per offrire un servizio migliore agli sviluppatori che avrebbero utilizzato l'API:
- In SPARROW: Criteo ha proposto l'aggiunta di un modello di servizio ("Gatekeeper") in esecuzione in un ambiente di esecuzione affidabile (TEE). L'API Protected Audience include un uso più limitato dei TEE, per la ricerca di dati in tempo reale e la generazione di report aggregati.
- Le proposte TERN e PARRROT di NextRoll descrivevano i diversi ruoli di acquirenti e venditori nell'asta on-device. Il flusso di offerta/punteggio dell'API Protected Audience si basa su questo lavoro.
- Le modifiche TURTLEDOVE basate sui risultati e a livello di prodotto di RTB House hanno migliorato il modello di anonimizzazione e le funzionalità di personalizzazione dell'asta on-device
- PARAKEET è la proposta di Microsoft per un servizio pubblicitario simile a TURTLEDOVE che si basa su un server proxy in esecuzione in un TEE tra il browser e i fornitori di tecnologia pubblicitaria, per anonimizzare le richieste di annunci e applicare le proprietà di privacy. L'API Protected Audience non ha adottato questo modello di proxy. Stiamo allineando le API JavaScript per PARAKEET e l'API Protected Audience, a supporto dei lavori futuri per combinare ulteriormente le migliori funzionalità di entrambe le proposte.
L'API Protected Audience non impedisce ancora alla rete pubblicitaria di un sito web di apprendere quali annunci vengono visualizzati da una persona. Prevediamo di modificare l'API per renderla più privata con il passare del tempo.
L'API Topics può essere utilizzata con l'API Protected Audience?
Sì, Un argomento osservato per l'utente corrente, fornito dall'API Topics, potrebbe essere utilizzato come informazioni contestuali da un venditore o offerente. Un argomento potrebbe essere incluso nelle seguenti proprietà:
auctionSignals
, una proprietà dell'oggetto di configurazione dell'asta passato anavigator.runAdAuction()
userBiddingSignals
, una proprietà dell'oggetto di configurazione del gruppo di interesse trasferito anavigator.joinAdInterestGroup()
Configurazione del browser disponibile
Gli utenti possono modificare la propria partecipazione alle prove di Privacy Sandbox in Chrome
attivando o disattivando l'impostazione di primo livello in
chrome://settings/adPrivacy
.
Durante il test iniziale, gli utenti potranno utilizzare questa impostazione di alto livello Privacy Sandbox per disattivare l'API Protected Audience. Chrome prevede di consentire agli utenti di visualizzare e gestire l'elenco dei gruppi di interesse a cui sono stati aggiunti sui siti web che hanno visitato. Come con le stesse tecnologie Privacy Sandbox, le impostazioni utente possono evolversi con il feedback di utenti, enti regolatori e altri.
Continueremo ad aggiornare le impostazioni disponibili in Chrome sulla base di test e feedback. In futuro, prevediamo di offrire impostazioni più granulari per gestire l'API Protected Audience e i dati associati.
I chiamanti dell'API non possono accedere all'appartenenza ai gruppi quando gli utenti navigano in modalità di navigazione in incognito, e l'iscrizione viene rimossa quando gli utenti cancellano i dati dei loro siti.
I worklet di Protected Audience vengono memorizzati nella cache dal browser?
Le risorse che contengono i worklet Protected Audience (la generazione dell'offerta dell'acquirente e i worklet di reporting, nonché i worklet di reporting e di valutazione degli annunci del venditore) vengono memorizzati nella cache dal browser. Puoi utilizzare l'intestazione Cache-Control
per controllare il comportamento di memorizzazione nella cache.
Interagisci e condividi il feedback
Ricevi assistenza
Per porre domande e ricevere assistenza in merito all'implementazione, alla demo o alla documentazione:
- GitHub: leggi l'spiegatore, solleva le domande e segui la discussione.
- Demo: segnala un problema relativo al repository di codice demo.
- Assistenza per gli sviluppatori: poni domande e partecipa alle discussioni nel repository di assistenza per gli sviluppatori di Privacy Sandbox. Seleziona il modello di problema per l'API Protected Audience.
- Implementazione di Chrome: per bug o problemi relativi all'implementazione di Chrome dell'API Protected Audience, puoi visualizzare i problemi esistenti o segnalare un nuovo problema.
Per domande più generali su come soddisfare le tue esigenze con l'API Protected Audience, segnala un problema nel repository dell'API. Puoi anche discutere dei casi d'uso del settore nel Miglioramento della pubblicità Web del Gruppo di W3C.
Utilizza il modulo di feedback di Privacy Sandbox per condividere feedback in privato con il team di Chrome al di fuori dei forum pubblici.
Disattivazione
Vuoi disattivare l'API Protected Audience? Scopri come bloccare l'accesso all'API Protected Audience come proprietario del sito o come singolo utente.
Ricevi aggiornamenti
- Per le notifiche relative alle modifiche dello stato delle API, unisciti alla mailing list per sviluppatori.
- Per seguire attentamente tutte le discussioni in corso sull'API, fai clic sul pulsante Guarda nella pagina dell'API su GitHub. A questo scopo, devi avere o creare un account GitHub.
- Per ricevere aggiornamenti generali su Privacy Sandbox, iscriviti al feed RSS [Progressi in Privacy Sandbox].
- Partecipa alle chiamate programmate per l'API Protected Audience (ogni seconda settimana). Tutti possono partecipare, prima assicurati di unirti al WICG. Puoi partecipare attivamente o semplicemente ascoltare.