API Protected Audience: guida per gli sviluppatori

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.

Aggiornamento: FLEDGE è stato rinominato API Protected Audience. Per saperne di più sul cambio di nome, leggi il post del blog.

Punto chiave: la prova dell'origine di Pertinenza e Misurazione dell'origine di Privacy Sandbox è terminata il 20 settembre 2023 e le API sono ora disponibili per il 99% degli utenti di Chrome e la registrazione alla prova dell'origine è stata chiusa. Per stare al passo con la percentuale di utenti per cui è abilitata ogni API, consulta i grafici di stato di Chrome.

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() e generateBid().
• Guida per il venditore all'API Protected Audience runAdAuction()
• Guida per gli acquirenti a reportWin() e guida per i venditori a reportResult()
• 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/.

Guarda questo deployment end-to-end per scoprire come funziona il codice demo dell'API Protected Audience e come utilizzare Chrome DevTools per il debug.

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.

Nota:questa è una versione in corso dell'API Protected Audience per i primi test. Non deve essere considerata completa o indicativa dell'implementazione finale. Lo stato e lo stato dell'API Protected Audience sono discussi nelle normali riunioni WICG. La cronologia di Privacy Sandbox fornisce le tempistiche di implementazione dell'API Protected Audience e di altre API Privacy Sandbox.

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');

Attenzione:il supporto delle funzionalità nella pagina corrente non garantisce che un'API sia utilizzabile. L'utente potrebbe aver disattivato l'API tramite le impostazioni del browser oppure avere altre impostazioni che ne impediscono l'utilizzo. Per proteggere la privacy degli utenti, non c'è modo di controllare questa funzionalità in modo programmatico.

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.

Avviso:non tutte le funzionalità descritte in questo post sono state implementate (o completamente implementate) nella versione dell'API Protected Audience attualmente testata in Chrome. La sezione Test con flag delle funzionalità spiega quali funzionalità dell'API Protected Audience sono attualmente disponibili per i test in Chrome eseguiti dalla riga di comando.

Nel tempo verranno aggiunte funzionalità dell'API Protected Audience man mano che l'implementazione procede.

1. Un utente visita il sito di un inserzionista

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

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.

Nota: l'origine del contesto di chiamata per joinAdInterestGroup() deve corrispondere all'origine del proprietario del gruppo di interesse. joinAdInterestGroup() deve essere chiamato da un iframe di proprietà del proprietario del gruppo di interesse (ad esempio, da una DSP). Se l'origine del documento corrente corrisponde a quella del proprietario del gruppo di interesse (ad esempio, un sito web con i propri gruppi di interesse), non è necessario alcun iframe.

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

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

È 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.

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 da trustedBiddingSignalsKeys.

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.

Punto chiave:nella fase sperimentale iniziale di test dell'API Protected Audience, trustedBiddingSignalsUrl deve avere la stessa origine del proprietario del gruppo di interesse. Per saperne di più, consulta Bring Your Own Server.

6. Viene visualizzato l'annuncio vincente

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.

Nota: l'oggetto FencedFrameConfig viene restituito solo se il flag resolveToConfig è impostato su true nella configurazione dell'asta. Se il flag non è impostato o è false, verrà restituita una URN opaca che può essere visualizzata solo in un iframe.

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

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.

---

Questo diagramma illustra ogni fase di un'asta dell'API Protected Audience.

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 a navigator.runAdAuction()
• userBiddingSignals, una proprietà dell'oggetto di configurazione del gruppo di interesse trasferito a navigator.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.