API Protected Audience: guida per gli sviluppatori

Guida per gli sviluppatori per le aste di annunci on-device per pubblicare annunci di remarketing e custom audience, senza monitoraggio cross-site di terze parti.

Per chi non ha familiarità con l'API Protected Audience, leggi la panoramica dell'API Protected Audience per una spiegazione di alto livello dell'API.

Questo post è stato scritto per gli sviluppatori come riferimento tecnico per l'ultima iterazione dell'API Protected Audience sperimentale. È disponibile una demo di un'implementazione di base dell'API Protected Audience, nonché riferimenti API per acquirenti e venditori di annunci.

Stato dell'implementazione

• La proposta dell'API Protected Audience è ora in fase di disponibilità generale. Fare domande e seguire la discussione.
• Stato in attesa delle funzionalità dell'API Protected Audience dettagli modifiche e miglioramenti all'API Protected Audience e alle funzionalità.
• Stato di Blink
• Stato della piattaforma Chrome dell'API Protected Audience: specifico per l'API Protected Audience su Chrome.
• Stato della piattaforma Chrome API Ads: una raccolta di API per facilitare la pubblicità: API Protected Audience, Topics, Fenced Frames e Attribution Reporting.

Per ricevere una notifica delle modifiche di stato nell'API, iscriviti alla mailing list per gli sviluppatori.

Che cos'è l'API Protected Audience?

L'API Protected Audience è un'API Privacy Sandbox progettata per pubblicare casi d'uso di remarketing e pubblico personalizzato, progettata in modo che non possa essere utilizzata da terze parti per monitorare il comportamento di navigazione degli utenti sui vari siti. L'API consente 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 da implementare 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 API specifici:

• Guida per gli acquirenti di joinAdInterestGroup() e generateBid().
• Guida per i venditori per l'API Protected Audience runAdAuction()
• Guida per gli acquirenti di reportWin() e guida per i venditori di reportResult()
• Risolvere i problemi relativi all'API Protected Audience

Puoi anche leggere le best practice per la latenza dell'asta dell'API Protected Audience.

Demo dell'API Protected Audience

Una procedura dettagliata di un'implementazione di base dell'API Protected Audience nei siti di inserzionisti e publisher è disponibile all'indirizzo protected-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:

• Abilita tutte le API per la privacy degli annunci in chrome://settings/adPrivacy.
• Imposta i flag dalla riga di comando. L'elenco completo dei flag dell'API Protected Audience disponibili è disponibile nella ricerca del codice di Chromium.

Eseguire il rendering degli annunci in iframe o frame isolati

Gli annunci possono essere visualizzati in un <iframe> o in un <fencedframe>, a seconda dei flag impostati.

Per utilizzare <fencedframe> per il rendering degli annunci:

--enable-features=InterestGroupStorage,AdInterestGroupAPI,Fledge,FencedFrames

Per utilizzare <iframe> per il rendering degli annunci:

--enable-features=InterestGroupStorage,AdInterestGroupAPI,Fledge,AllowURNsInIframes --disable-features=FencedFrames

Includi il flag BiddingAndScoringDebugReportingAPI per attivare metodi temporanei di segnalazione di debug di vincita/perdita.

Funzionalità supportate

L'API Protected Audience dietro i flag delle funzionalità in Chromium è un primo esperimento per testare le seguenti funzionalità dell'API Protected Audience:

• Gruppi basati sugli interessi: memorizzati dal browser, con metadati associati per configurare l'offerta e il rendering degli annunci.
• Offerte on-device degli acquirenti (DSP o inserzionista): in base ai gruppi di interesse e agli indicatori memorizzati del venditore.
• Selezione degli annunci sul dispositivo da parte del venditore (SSP o publisher): in base a offerte all'asta e metadati degli acquirenti.
• Rendering degli annunci in una versione temporaneamente meno restrittiva di Fenced Frame: 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 dei gruppi basati sugli interessi

L'implementazione attuale dell'API Protected Audience consente di chiamare joinAdInterestGroup() da qualsiasi punto di una pagina, anche da iframe cross-domain.

In futuro, una volta che i proprietari dei siti avranno avuto il tempo di aggiornare le proprie norme relative alle funzionalità degli iframe interdominio, l'intenzione è di vietare le chiamate dagli iframe interdominio.

Servizio coppia 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 potrebbero essere utilizzate in diversi modi:

• Gli acquirenti potrebbero voler calcolare il budget rimanente in una campagna pubblicitaria.
• I venditori potrebbero essere tenuti a controllare le creatività pubblicitarie in base alle norme dei publisher.

Il codice del servizio chiave/valore dell'API Protected Audience è ora disponibile. Per l'aggiornamento dello stato, consulta il post del blog relativo all'annuncio.

Per i test iniziali, è stato introdotto un modello "Bring Your Own Server". A lungo termine, le tecnologie pubblicitarie dovranno utilizzare i servizi chiave/valore dell'API Protected Audience open source eseguiti in ambienti di esecuzione attendibili.

Consulta il post del blog sui servizi dell'API Protected Audience per gli aggiornamenti della cronologia. Prima di questa transizione, forniremo un preavviso sostanziale agli sviluppatori per iniziare i test e l'adozione.

Rilevare il supporto delle funzionalità

Prima di utilizzare l'API, verifica se è 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 sul sito web di un produttore di biciclette personalizzate, poi visita un sito web di notizie e visualizza un annuncio di una nuova bicicletta del produttore.

Le funzionalità dell'API Protected Audience verranno aggiunte nel tempo man mano che il lavoro di 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 di prodotto di una bicicletta in acciaio fatta a mano. In questo modo, il produttore di biciclette ha 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 basato sugli interessi all'elenco dei gruppi di cui il browser è membro.

In questo esempio, il gruppo si chiama custom-bikes e il proprietario è dsp.example. Il proprietario del gruppo di interesse (in questo caso, la DSP) sarà un acquirente 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.

• Leggi la spiegazione dell'API Protected Audience: I browser registrano i gruppi di interesse.
• Leggi la guida all'API: acquirenti e DSP, scopri come joinAdInterestGroup() e generare offerte.

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
}

Come fanno gli acquirenti a fare offerte?

generateBid() viene chiamato per ogni gruppo di interesse di cui il browser è membro, se il proprietario del gruppo di interesse è invitato a fare un'offerta.

Leggi la documentazione per gli sviluppatori di generatedBid().

3. L'utente visita un sito che vende spazio pubblicitario

In un secondo momento, l'utente visita un sito che vende spazi pubblicitari, in questo esempio un sito web di notizie. Il sito dispone di un inventario pubblicitario che vende in modo programmatico con offerte in tempo reale.

4. Nel browser viene eseguita un'asta dell'annuncio

L'asta dell'annuncio verrà probabilmente eseguita dal fornitore lato offerta (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 tiene conto dei gruppi di interesse di cui fa parte il browser, nonché dei dati degli acquirenti di spazi pubblicitari e dei venditori dei servizi chiave/valore.

• Leggi la spiegazione dell'API Protected Audience: I venditori eseguono aste on-device
• Leggi la guida all'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 dati in tempo reale al servizio Key/Value

Durante un'asta dell'annuncio, il venditore può richiedere dati in tempo reale su specifiche creatività dell'annuncio inviando una richiesta al proprio servizio Key/Value. Il venditore può richiedere queste informazioni durante runAdAuction() tramite la 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 dal proprio servizio Key/Value utilizzando le proprietà trustedBiddingSignalsUrl e trustedBiddingSignalsKeys dell'argomento del gruppo di interesse passato a navigator.joinAdInterestGroup().

Quando viene chiamato runAdAuction(), il browser effettua una richiesta al server attendibile di ogni acquirente di annunci. L'URL della richiesta potrebbe avere il seguente aspetto:

https://kv-service.example/getvalues?hostname=publisher.example&keys=key1,key2

• L'URL di base proviene da trustedBiddingSignalsUrl.
• hostname è fornito dal browser.
• Il valore keys viene estratto da trustedBiddingSignalsKeys.

La risposta a questa richiesta è un oggetto JSON che fornisce valori per ciascuna delle chiavi.

• Leggi la spiegazione dell'API Protected Audience: Recupero di dati in tempo reale dal servizio chiave/valore dell'API Protected Audience.
• Leggi open source del servizio chiave/valore dell'API Protected Audience.

6. Viene visualizzato l'annuncio vincente

La promessa restituita da runAdAuction() viene risolta in un oggetto di configurazione del frame isolato (FencedFrameConfig) quando il flagresolveToConfig è impostato su true nella configurazione dell'asta. La configurazione del frame viene utilizzata da un frame recintato per indirizzare il frame all'annuncio vincente, ma l'URL dell'annuncio non è visibile all'incorporatore del frame.

L'oggetto di configurazione del frame recintato è disponibile a partire dalla versione M114. Per saperne di più 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 segnalato

Il piano a lungo termine prevede di consentire al browser di generare report sui risultati dell'asta 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(). Questo accetta un singolo argomento: una stringa che rappresenta un URL recuperato al termine dell'asta, che codifica le informazioni a livello di evento da segnalare.

• Leggi la guida all'API: scopri di più sui report per venditori e acquirenti

8. Viene segnalato un clic sull'annuncio

Viene registrato un clic su un annuncio visualizzato in un frame recintato. Per saperne di più su come potrebbe funzionare, consulta Report sugli annunci Fenced Frames.

Qual è la differenza tra l'API Protected Audience e TURTLEDOVE?

L'API Protected Audience è il primo esperimento da implementare in Chromium all'interno della famiglia di proposte TURTLEDOVE.

L'API Protected Audience segue i principi di alto livello di TURTLEDOVE. Alcune pubblicità online si basano sulla visualizzazione di un annuncio a una persona potenzialmente interessata che ha interagito in precedenza con l'inserzionista o la rete pubblicitaria. Storicamente, questo è stato possibile perché l'inserzionista riconosceva una persona specifica mentre navigava su vari siti web, un problema fondamentale per la privacy sul web di oggi.

L'iniziativa TURTLEDOVE mira a offrire una nuova API per gestire questo caso d'uso e al contempo offrire alcuni importanti progressi in termini di privacy:

• Il browser, non l'inserzionista, contiene le informazioni su ciò che l'inserzionista ritiene che interessi a una persona.
• Gli inserzionisti possono pubblicare annunci in base a un interesse, ma non possono combinare questo interesse con altre informazioni su una persona, in particolare chi è o quale pagina sta visitando.

L'API Protected Audience è nata da TURTLEDOVE e da una raccolta di proposte correlate per modifiche per servire meglio gli sviluppatori che avrebbero utilizzato l'API:

• In SPARROW: Criteo ha proposto l'aggiunta di un modello di servizio ("Gatekeeper") in esecuzione in un Trusted Execution Environment (TEE). L'API Protected Audience include un utilizzo più limitato degli TEE per la ricerca di dati in tempo reale e la generazione di report aggregati.
• Le proposte TERN di NextRoll e PARRROT di Magnite descrivevano i diversi ruoli di acquirenti e venditori nell'asta on-device. Il flusso di offerta/punteggio dell'annuncio dell'API Protected Audience si basa su questo lavoro.
• Le modifiche basate sui risultati e a livello di prodotto di TURTLEDOVE 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 per supportare il lavoro futuro 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 sapere quali annunci vede una persona. Prevediamo di modificare l'API per renderla più privata nel 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 informazione contestuale da un venditore o un offerente. Un argomento può 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 passato 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 Privacy Sandbox di alto livello per disattivare l'API Protected Audience. Chrome ha in programma di consentire agli utenti di visualizzare e gestire l'elenco dei gruppi di interesse a cui sono stati aggiunti nei siti web che hanno visitato. Come per le tecnologie Privacy Sandbox, le impostazioni utente potrebbero evolversi in base al feedback di utenti, enti normativi e altri soggetti.

Continueremo ad aggiornare le impostazioni disponibili in Chrome in base a 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 al gruppo quando gli utenti navigano in modalità di navigazione in incognito e l'appartenenza viene rimossa quando gli utenti cancellano i dati dei siti.

I worklet Protected Audience vengono memorizzati nella cache dal browser?

Le risorse che contengono i worklet Protected Audience, ovvero i worklet di generazione delle offerte e di generazione di report dell'acquirente e i worklet di assegnazione del punteggio e di generazione di report dell'inserzionista, vengono memorizzate nella cache del browser. Puoi utilizzare l'intestazione Cache-Control per controllare il comportamento di memorizzazione nella cache.

Partecipare e condividere feedback

Assistenza

Per porre domande e ricevere assistenza per l'implementazione, la demo o la documentazione:

• GitHub: leggi l'explainer, poni domande e segui la discussione.
• Demo: segnala un problema nel repository di codice demo.
• Implementazione di Chrome: per bug o problemi relativi all'implementazione dell'API Protected Audience in Chrome, 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 API. Puoi anche discutere dei casi d'uso del settore nell'Improving Web Advertising Business Group del 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.

Disattiva

Vuoi disattivare l'API Protected Audience? Scopri come bloccare l'accesso all'API Protected Audience, in qualità di proprietario del sito o utente individuale.

Ricevi aggiornamenti

• Per ricevere notifiche sulle modifiche dello stato dell'API, iscriviti alla mailing list per gli sviluppatori.
• Per seguire da vicino tutte le discussioni in corso sull'API, fai clic sul pulsante Segui nella pagina dell'API su GitHub. Per questa operazione è necessario avere o creare un account GitHub.
• Per ricevere aggiornamenti generali su Privacy Sandbox, iscriviti al feed RSS [Progress in the Privacy Sandbox].
• Partecipa alle chiamate pianificate per l'API Protected Audience (ogni due settimane). Tutti sono invitati a partecipare. Per farlo, assicurati di unirti al WICG. Puoi partecipare attivamente o semplicemente ascoltare.