API Protected Audience: guida per gli sviluppatori

Guida per gli sviluppatori relativa alle aste di annunci on-device per la pubblicazione di segmenti di pubblico personalizzati e di remarketing, senza il monitoraggio tra siti di terze parti.

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.

Per chi non ha mai utilizzato l'API Protected Audience, leggi la panoramica dell'API Protected Audience per una spiegazione generale dell'API.

Questo post è scritto per gli sviluppatori come riferimento tecnico per la versione più recente dell'API Protected Audience sperimentale. È disponibile una demo di un deployment di base dell'API Protected Audience e i riferimenti API per venditori e acquirenti 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 Privacy Sandbox progettata per gestire casi d'uso di remarketing e segmenti di pubblico personalizzati, concepita in modo da non essere utilizzata da terze parti per monitorare il comportamento di navigazione degli utenti sui siti. L'API consente alle aste on-device dal browser di scegliere annunci pertinenti per i siti web che l'utente ha precedentemente visitato.

L'API Protected Audience è il primo esperimento a essere 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 specifici dell'API:

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

Puoi anche leggere le best practice relative alla latenza dell'asta degli annunci dell'API Protected Audience.

Demo dell'API Protected Audience

Una procedura dettagliata del deployment di base dell'API Protected Audience sui siti di inserzionisti e publisher è disponibile all'indirizzo protect-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.

Esegui il test con chrome://flags o flag funzionalità

Puoi testare l'API Protected Audience per un singolo utente in Chrome Beta 101.0.4951.26 e versioni successive su computer:

• Attiva chrome://flags/#privacy-sandbox-ads-apis.
• Imposta i flag dalla riga di comando. L'elenco completo dei flag disponibili dell'API Protected Audience è disponibile in Ricerca Codice Chromium.

Visualizzare gli annunci in iframe o frame protetti

Gli annunci possono essere visualizzati in <iframe> o <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 i metodi di generazione di report per la perdita di debug temporanea/l'acquisizione.

Nota: questa è una versione in corso dell'API Protected Audience per i test preliminari. Non deve essere considerata completa o indicativa dell'implementazione finale. L'avanzamento e lo stato dell'API Protected Audience sono discussi nelle riunioni regolari del 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 i flag funzionalità in Chromium è un primo esperimento per testare le seguenti funzionalità dell'API Protected Audience:

• Gruppi di interesse: memorizzati dal browser, con i metadati associati per configurare le offerte e il rendering per gli 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 on-device da parte del venditore (SSP o publisher): in base alle offerte in asta e ai metadati degli acquirenti.
• Rendering dell'annuncio in una versione temporaneamente semplificata di Fenced Frames: con accesso alla rete e logging consentiti per il rendering dell'annuncio.

Scopri di più sul supporto e sui vincoli delle funzionalità nella spiegazione dell'API Protected Audience.

Autorizzazioni gruppo di interesse

L'impostazione predefinita per l'attuale implementazione dell'API Protected Audience è consentire le chiamate a joinAdInterestGroup() da qualsiasi punto di una 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, il loro piano prevede di non consentire le chiamate dagli iframe interdominio.

Servizio chiavi/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.
• Ai venditori potrebbe essere richiesto di controllare le creatività degli annunci in base alle norme dei publisher.

Il codice di servizio chiave/valore dell'API Protected Audience è ora disponibile. Consulta il post del blog dell'annuncio per informazioni sull'aggiornamento dello stato.

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

Per gli aggiornamenti sulle tempistiche, consulta il post del blog sui servizi dell'API Protected Audience. Avviseremo gli sviluppatori in modo sostanziale all'inizio dei test e dell'adozione prima che la transizione abbia luogo.

Supporto delle funzionalità di rilevamento

Prima di utilizzare l'API, controlla 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');

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

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 per una nuova bicicletta del produttore.

Avviso: non tutte le funzionalità descritte in questo post sono state implementate (o implementate completamente) nella versione dell'API Protected Audience attualmente testata in Chrome. La sezione Test con flag 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 con l'avanzamento dell'implementazione.

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 visiti la pagina del prodotto per una bici in acciaio fatta a mano. Ciò 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 è membro.

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 al gruppo di interesse viene memorizzata dal browser e sul dispositivo dell'utente e non viene condivisa con il fornitore del browser né con altri.

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

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

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 delle offerte. Ad esempio:

{
  renderUrl: 'https://cdn.example/.../bikeAd1.html',
  metadata: bikeAd1metadata // optional
}

In che modo gli acquirenti fanno le offerte?

generateBid() viene richiamato per ogni gruppo di interesse di cui il browser è membro, se il proprietario del gruppo di interesse è invitato a fare offerte.

Leggi la documentazione per gli sviluppatori di generatedBid().

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

Più tardi, l'utente visita un sito che vende uno spazio pubblicitario, in questo esempio un sito web di notizie. Il sito ospita un inventario pubblicitario, che viene venduto in modo programmatico con offerte in tempo reale.

4. Viene eseguita un'asta dell'annuncio nel browser

È probabile che l'asta dell'annuncio sia gestita dal provider lato offerta 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 è membro il browser, insieme ai dati provenienti dagli acquirenti dello spazio pubblicitario e dai venditori dei servizi chiave/valore.

• Leggi il messaggio esplicativo dell'API Protected Audience: I venditori eseguono aste on-device
• Leggi la guida all'API: i venditori possono saperne 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 chiave/valore

Durante un'asta dell'annuncio, il venditore può richiedere dati in tempo reale su creatività specifiche inviando una richiesta al servizio chiave/valore. Il venditore può richiedere queste informazioni durante il periodo 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 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 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.
• Il parametro hostname viene fornito dal browser.
• Il valore keys proviene da trustedBiddingSignalsKeys.

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

• Leggi il messaggio esplicativo dell'API Protected Audience: Recupero di dati in tempo reale dal servizio chiave/valore dell'API Protected Audience.
• Leggi l'articolo Rendere open source il 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. Scopri di più in Bring Your Own Server.

6. Viene mostrato l'annuncio vincente

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

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

L'oggetto di configurazione del frame Fenced è disponibile a partire dalla versione M114. Per ulteriori informazioni sull'oggetto FencedFrameConfig, consulta l'articolo del blog di Chrome.

• Leggi il messaggio esplicativo 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 di generazione di report temporaneo a livello di evento, il codice che implementa reportResult() per il venditore e reportWin() per l'offerente vincente, può chiamare la funzione sendReportTo(). Questo prevede un singolo argomento: una stringa che rappresenta un URL, che viene recuperato al termine dell'asta, e codifica le informazioni a livello di evento da includere nei report.

• Leggi la guida all'API: scopri di più sui report su venditori e 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 la sezione Report sugli annunci con frame fence.

---

Questo diagramma descrive 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 a essere 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. In passato, questo approccio ha funzionato perché l'inserzionista riconosce una persona specifica mentre naviga su un sito web, un problema di privacy generale nel web odierno.

L'impegno di TURTLEDOVE consiste nell'offrire una nuova API per affrontare questo caso d'uso, offrendo al contempo alcuni importanti progressi in materia di privacy:

• Il browser, non l'inserzionista, contiene le informazioni relative a ciò che l'inserzionista ritiene che una persona sia interessata.
• Gli inserzionisti possono pubblicare gli annunci in base a un interesse, ma non possono combinarlo con altre informazioni su una persona, in particolare chi è o quale pagina visita.

L'API Protected Audience è nata da TURTLEDOVE e da una raccolta di proposte di modifiche correlate per servire meglio gli sviluppatori che userebbero 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 uso più limitato dei TEE per la ricerca dei 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 per gli annunci 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 anonimato 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 eseguito 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 sostegno del 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 apprendere quali annunci vengono visualizzati da un utente. Prevediamo di modificare l'API per renderla più privata nel corso 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 può essere incluso nelle seguenti proprietà:

• auctionSignals, una proprietà dell'oggetto configurazione dell'asta passata a navigator.runAdAuction()
• userBiddingSignals, una proprietà dell'oggetto di configurazione del gruppo di interesse passata 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 i test iniziali, gli utenti potranno utilizzare questa impostazione di Privacy Sandbox di alto livello 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 visitati. Come per le tecnologie di Privacy Sandbox, le impostazioni utente possono evolversi in base al feedback di utenti, enti regolatori e altri.

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 API non possono accedere alle iscrizioni ai gruppi 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 di Protected Audience sono memorizzati nella cache dal browser?

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

Interagisci e condividi feedback

Assistenza

Per porre domande e ricevere assistenza sull'implementazione, sulla demo o sulla documentazione:

• GitHub: leggi l' spiegazione, fai domande e segui la discussione.
• Demo: segnala un problema relativo al repository di codici demo.
• Assistenza per gli sviluppatori: poni domande e partecipa alle discussioni sul 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 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 dell'API. Puoi anche discutere dei casi d'uso del settore nell'Migliorare il Web Advertising Business Group di W3C.

Utilizza il modulo di feedback di Privacy Sandbox per condividere il tuo 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 ricevere notifiche relative alle modifiche dello stato dell'API, iscriviti alla mailing list per gli sviluppatori.
• Per seguire attentamente tutte le discussioni in corso sull'API, fai clic sul pulsante Guarda nella pagina dell'API su GitHub. Questa operazione richiede che tu abbia o crei un account GitHub.
• Per ricevere aggiornamenti generali su Privacy Sandbox, iscriviti al feed RSS [Avanzamento in Privacy Sandbox].
• Partecipa alle chiamate programmate per l'API Protected Audience (ogni seconda settimana). Tutti possono partecipare. Per partecipare, assicurati di partecipare al WICG. Puoi partecipare attivamente o semplicemente ascoltare.