API Protected Audience: guida per gli sviluppatori

bookmark_border Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

Guida per gli sviluppatori per le aste di annunci on-device per la pubblicazione di annunci di remarketing e per pubblico personalizzato, senza il monitoraggio di terze parti cross-site.

Se non hai dimestichezza con l'API Protected Audience, consulta la panoramica dell'API Protected Audience per una spiegazione generale dell'API.

Questo post è rivolto agli 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, così come i riferimenti API per acquirenti e venditori di annunci.

Stato dell'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 scenari di utilizzo del remarketing e dei segmenti di pubblico personalizzati, in modo che non possa essere utilizzata da terze parti per monitorare il comportamento di navigazione degli utenti sui siti. L'API consente le aste on-device tramite il 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.

Provare 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 per joinAdInterestGroup() e generateBid().
• Guida per i venditori per l'API Protected Audience runAdAuction()
• Guida per gli acquirenti su reportWin() e guida per i venditori su reportResult()
• Risolvere i problemi relativi all'API Protected Audience

Puoi anche leggere le best practice sulla latenza dell'asta di annunci dell'API Protected Audience.

Demo dell'API Protected Audience

Una procedura dettagliata per il deployment di un'API Protected Audience di base sui siti di inserzionisti e publisher è disponibile all'indirizzo protected-audience-demo.web.app/.

Prova 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 di privacy per gli annunci in chrome://settings/adPrivacy.
• Imposta i flag dalla riga di comando. L'elenco completo dei flag dell'API Protected Audience disponibili è disponibile in Chromium Code Search.

Eseguire il rendering degli annunci in iframe o frame delimitati

Gli annunci possono essere visualizzati in un <iframe> o in un <fencedframe>, a seconda di quali indicatori sono impostati.

Per utilizzare <fencedframe> per visualizzare gli annunci:

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

Per utilizzare <iframe> per visualizzare gli annunci:

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

Includi il flag BiddingAndScoringDebugReportingAPI per attivare metodi di generazione di report temporanei su win/loss per il debug.

Funzionalità supportate

L'API Protected Audience dietro i flag 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 l'asta e il rendering degli annunci.
• Offerte on-device da parte degli acquirenti (DSP o inserzionista): in base ai gruppi di interesse memorizzati e agli indicatori del venditore.
• Selezione di annunci sul dispositivo da parte del venditore (SSP o publisher): in base alle offerte dell'asta e ai metadati degli acquirenti.
• Rendering degli annunci in una versione temporaneamente meno restrittiva dei frame delimitati: con accesso alla rete e registrazione consentiti per il rendering degli annunci.

Scopri di più sul supporto delle funzionalità e sui vincoli nell'articolo esplicativo sull'API Protected Audience.

Autorizzazioni dei gruppi di interesse

Il valore predefinito per l'attuale implementazione dell'API Protected Audience è consentire 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 norme relative alle autorizzazioni degli iframe interdominio, è previsto di non consentire le chiamate da iframe interdominio.

Servizio coppia chiave-valore

Per supportare l'asta di annunci dell'API Protected Audience, il browser può accedere a un servizio chiave/valore per recuperare informazioni in tempo reale che supportano l'asta di annunci dell'API Protected Audience. Queste informazioni possono essere utilizzate in diversi modi:

• Gli acquirenti potrebbero voler calcolare il budget rimanente di una campagna pubblicitaria.
• I venditori potrebbero dover verificare la conformità delle creatività degli annunci alle norme del publisher.

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

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 in ambienti di esecuzione attendibili.

Per aggiornamenti sulle tempistiche, consulta il post del blog sui servizi dell'API Protected Audience. Prima che questa transizione venga eseguita, daremo agli sviluppatori un preavviso sufficiente per iniziare i test e l'adozione.

Rileva il supporto delle funzionalità

Prima di utilizzare l'API, controlla se è supportata dal browser e se è 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 visita il sito web di un produttore di biciclette personalizzate, poi visita un sito web di notizie e gli viene mostrato un annuncio di una nuova bicicletta del produttore.

Le funzionalità dell'API Protected Audience verranno aggiunte nel tempo man mano che procede il lavoro di 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 trascorra un po' di tempo sulla pagina di prodotto di una bicicletta 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 di interesse

La Demand-Side Platform (DSP) dell'inserzionista (o l'inserzionista stesso) chiama navigator.joinAdInterestGroup() per chiedere al browser di aggiungere un gruppo di interessi all'elenco dei gruppi di cui il browser fa parte.

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 di annunci 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 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à dell'annuncio e, facoltativamente, metadati arbitrari che possono essere utilizzati al momento dell'asta. Ad esempio:

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

In che modo gli acquirenti fanno offerte?

generateBid() viene chiamato per ogni gruppo di interesse di cui fa parte il browser, 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

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

4. Viene eseguita un'asta di annunci nel browser

È probabile che l'asta di annunci venga eseguita dal fornitore lato fornitore (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 fa parte il browser, nonché i dati degli acquirenti e dei venditori di spazi pubblicitari dei servizi Key/Value.

• Leggi la spiegazione dell'API Protected Audience: I venditori pubblicano aste on-device
• Leggi la guida all'API: i venditori possono scoprire di più su runAdAuction() e sulle best practice per la latenza delle aste di annunci.

5. Il venditore e gli acquirenti partecipanti richiedono dati in tempo reale dal servizio Key/Value

Durante un'asta di annunci, il venditore può richiedere dati in tempo reale su creatività pubblicitarie specifiche 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 preso 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 Apri il codice sorgente del servizio chiave/valore dell'API Protected Audience.

6. Viene visualizzato l'annuncio vincente

La promessa restituita da runAdAuction() si risolve in un oggetto di configurazione del frame recintato (FencedFrameConfig) quando il flag resolveToConfig è impostato su true nella configurazione dell'asta. La configurazione del frame viene utilizzata da un frame recintato per passare all'annuncio vincente, ma l'URL dell'annuncio non è visibile a chi ha incorporato il frame.

L'oggetto di configurazione del frame recintato è disponibile a partire da M114. Per saperne di più sull'oggetto FencedFrameConfig, consulta l'articolo del blog di Chrome.

• Leggi l'articolo esplicativo sull'API Protected Audience: i browser visualizzano l'annuncio vincente

7. Il risultato dell'asta viene registrato

Il piano a lungo termine è consentire al browser di segnalare i risultati dell'asta per il venditore e gli acquirenti utilizzando le API di aggregazione privata.

Come meccanismo temporaneo per la 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(). Questa funzione accetta un singolo argomento: una stringa rappresentante un URL recuperato al termine dell'asta, che codifica le informazioni a livello di evento da registrare.

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

8. Viene registrato un clic sull'annuncio

Viene registrato un clic su un annuncio visualizzato in un frame delimitato. Per scoprire di più su come funziona, consulta Report sugli annunci con frame delimitati.

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 generali di TURTLEDOVE. In passato, la pubblicità online si basava sulla visualizzazione di un annuncio a una persona potenzialmente interessata che aveva interagito in precedenza con l'inserzionista o la rete pubblicitaria. In passato, questo metodo funzionava grazie al riconoscimento da parte dell'inserzionista di una persona specifica mentre navigava sui siti web, un problema fondamentale per la privacy sul web di oggi.

L'obiettivo di TURTLEDOVE è offrire una nuova API per risolvere questo caso d'uso, offrendo al contempo alcuni importanti progressi in termini di privacy:

• Il browser, non l'inserzionista, detiene le informazioni su ciò che l'inserzionista ritiene che una persona sia interessata.
• Gli inserzionisti possono pubblicare annunci in base a un interesse, ma non possono combinare questo interesse con altre informazioni su una persona, in particolare sulla sua identità o sulla pagina che sta visitando.

L'API Protected Audience è nata da TURTLEDOVE e da una raccolta di proposte correlate per modifiche al fine di 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 Trusted Execution Environment (TEE). L'API Protected Audience include un utilizzo più limitato delle TEE, per la ricerca dei 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 degli annunci dell'API Protected Audience si basa su questo lavoro.
• Le modifiche apportate da RTB House a TURTLEDOVE in base ai risultati e a livello di prodotto 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 in esecuzione in un TEE tra il browser e i fornitori di tecnologia pubblicitaria per anonimizzare le richieste di annunci e applicare le proprietà della privacy. L'API Protected Audience non ha adottato questo modello di proxy. Stiamo allineando le API JavaScript per PARAKEET e l'API Protected Audience, in supporto 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 sapere quali annunci vengono visualizzati da una persona. Prevediamo di modificare l'API in modo che diventi 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 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 ha intenzione 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 per le tecnologie Privacy Sandbox stesse, le impostazioni utente possono evolversi in base al feedback di utenti, 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 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 del sito.

I worklet Protected Audience sono 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 determinazione del punteggio degli annunci e di generazione di report del venditore, vengono memorizzate nella cache dal browser. Puoi utilizzare l'intestazione Cache-Control per controllare il comportamento della memorizzazione nella cache.

Coinvolgere e condividere feedback

Assistenza

Per fare 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 del codice demo.
• Assistenza per gli sviluppatori: fai domande e partecipa alle discussioni nel repository Privacy Sandbox Developer Support. 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 risolvere un nuovo problema.

Per domande più generali su come soddisfare le tue esigenze con l'API Protected Audience, registra un problema nel repository dell'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 privati 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 privato.

Ricevi aggiornamenti

• Per ricevere notifiche relative alle 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 Guarda nella pagina dell'API su GitHub. Per farlo, devi 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 seconda settimana). Tutti possono partecipare. Per farlo, assicurati prima di partecipare al WICG. Puoi partecipare attivamente o semplicemente ascoltare.