Guida per gli sviluppatori dell'API FLEDGE

A chi è destinato questo articolo?

Questo post è un riferimento tecnico all'attuale iterazione dell'API Protected Audience sperimentale.

Che cos'è Protected Audience?

L'API Protected Audience è una proposta di Privacy Sandbox per la pubblicazione di 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 tra i 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.

Protected Audience è il primo esperimento implementato in Chromium all'interno della famiglia di proposte TURTLEDOVE.

Il diagramma seguente fornisce una panoramica del ciclo di vita di FLEDGE:

Illustrazione che fornisce una panoramica di ogni fase del ciclo di vita di FLEDGE
Ciclo di vita di FLEDGE.

Come posso provare Protected Audience?

Demo di Protected Audience

Una procedura dettagliata dell'implementazione di base di Protected Audience nei siti di inserzionisti e publisher è disponibile all'indirizzo secure-audience-demo.web.app.

Il video della demo spiega come funziona il codice demo e come utilizzare Chrome DevTools per il debug di Protected Audience.

Partecipare a una prova dell'origine di Protected Audience

È stata resa disponibile una prova dell'origine di pertinenza e misurazione di Privacy Sandbox in Chrome beta 101.0.4951.26 e versioni successive su computer per le API Protected Audience, Topics e Attribution Reporting.

Per partecipare, registrati per un token di prova dell'origine.

Dopo aver effettuato la registrazione alla prova, puoi provare l'API JavaScript Protected Audience nelle pagine che forniscono un token della prova valido: ad esempio, per chiedere al browser di unirti a uno o più gruppi di interesse e poi di eseguire un'asta dell'annuncio per selezionare e visualizzare un annuncio.

La demo di Protected Audience fornisce un esempio base di implementazione end-to-end di Protected Audience.

Fornisci un token di prova per ogni pagina su cui vuoi eseguire il codice dell'API Protected Audience:

  • Come meta tag nella sezione <head>:

    <meta http-equiv="origin-trial" content="TOKEN_GOES_HERE">

  • Come intestazione HTTP:

    Origin-Trial: TOKEN_GOES_HERE

  • Fornendo un token in modo programmatico:

    const otMeta = document.createElement('meta');
otMeta.httpEquiv = 'origin-trial';
otMeta.content = 'TOKEN_GOES_HERE';
document.head.append(otMeta);

Un iframe che esegue il codice Protected Audience, ad esempio una chiamata navigator.joinAdInterestGroup() da parte di un proprietario di un gruppo di interesse, dovrà fornire un token che corrisponda alla sua origine.

Proposti dettagli della prima prova dell'origine di Protected Audience fornisce maggiori dettagli sugli obiettivi della prima prova e spiega quali funzionalità sono supportate.

Testa questa API

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

  • Attivando tutte le API di privacy per gli annunci in chrome://settings/adPrivacy
  • Impostando i flag dalla riga di comando.

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 attivare i metodi di debug temporaneo per segnalare la perdita/la vittoria.

L'opzione Esegui Chromium con flag spiega come impostare i flag durante l'esecuzione di Chrome e di altri browser basati su Chromium dalla riga di comando. L'elenco completo delle segnalazioni Protected Audience è disponibile in Chromium Code Search.

Quali funzionalità sono supportate nell'ultima versione di Chrome?

Protected Audience verrà reso disponibile in Chromium dietro le segnalazioni di funzionalità come primo esperimento per testare le seguenti funzionalità della proposta Protected Audience:

  • Gruppi di interesse: memorizzati dal browser, con metadati associati per configurare le offerte per gli annunci e il rendering.
  • Offerte on-device da parte degli acquirenti (DSP o inserzionista): in base ai gruppi di interesse memorizzati e agli indicatori del venditore.
  • Selezione degli 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 rilassata dei frame recintati: con accesso alla rete e logging consentiti per il rendering degli annunci.

La pagina esplicativa dell'API fornisce maggiori dettagli sul supporto e sui vincoli delle funzionalità.

Autorizzazioni per i gruppi di interesse

L'impostazione predefinita nell'attuale implementazione di Protected Audience è di consentire la chiamata 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 modificare le norme sulle autorizzazioni degli iframe interdominio, pianificheranno di non consentire le chiamate da iframe cross-domain, come descritto nel video esplicativo.

Servizio chiave/valore

Nell'ambito di un'asta dell'annuncio Protected Audience, il browser può accedere a un servizio chiave/valore che restituisce semplici coppie chiave-valore per fornire informazioni a un acquirente di annunci, ad esempio il budget della campagna rimanente. La proposta Protected Audience impone che questo server "non esegua log a livello di evento e non abbia altri effetti collaterali basati su queste richieste".

Il codice del servizio chiave/valore Protected Audience è ora disponibile in un repository GitHub di Privacy Sandbox. Questo servizio può essere utilizzato dagli sviluppatori di Chrome e Android. Per l'aggiornamento dello stato, consulta il post del blog dell'annuncio. Scopri di più sul servizio chiave/valore Protected Audience nella spiegazione dell'API e nella spiegazione del modello di attendibilità.

Per il test iniziale, viene utilizzato il modello "Bring Your Own Server". Sul lungo periodo, i tecnici pubblicitari dovranno utilizzare i servizi chiave/valore open source Protected Audience in esecuzione in ambienti di esecuzione attendibili per recuperare dati in tempo reale.

Per garantire che l'ecosistema abbia tempo sufficiente per i test, non prevediamo di richiedere l'utilizzo dei servizi chiave/valore open source o di TEE fino a qualche tempo dopo il ritiro dei cookie di terze parti. Daremo agli sviluppatori un preavviso significativo per iniziare i test e l'adozione prima che avvenga questa 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 faccio a disattivare Protected Audience?

Puoi bloccare l'accesso all'API Protected Audience come proprietario del sito o come singolo utente.

In che modo i siti possono controllare l'accesso?

Protected Audience alla fine richiederà ai siti di impostare norme relative alle autorizzazioni per consentire la disponibilità della funzionalità Protected Audience. In questo modo, avrai la certezza che terze parti arbitrarie non possano utilizzare l'API senza che il sito ne sia a conoscenza. Tuttavia, per facilitare i test durante la prima prova dell'origine, questo requisito viene rinunciato per impostazione predefinita. I siti che vorrebbero disattivare esplicitamente la funzionalità Protected Audience durante il periodo di test possono utilizzare il criterio delle autorizzazioni pertinente per bloccare l'accesso.

Esistono due criteri relativi alle autorizzazioni di Protected Audience che possono essere impostati in modo indipendente:

  • join-ad-interest-group attiva/disattiva la funzionalità per aggiungere un browser ai gruppi di interesse
  • run-ad-auction attiva/disattiva la funzionalità per eseguire un'asta on-device

L'accesso alle API Protected Audience può essere disattivato completamente in contesti proprietari specificando il seguente criterio di autorizzazione in un'intestazione della risposta HTTP:

Permissions-Policy: join-ad-interest-group=(), run-ad-auction=()

Puoi disattivare l'utilizzo delle API in un iframe aggiungendo il seguente attributo allow a un elemento iframe:

<iframe src="https://example.com" allow="join-ad-interest-group 'none'; run-ad-auction 'none'"></iframe>

La sezione Norme relative alle autorizzazioni della prima prova dell'origine del pubblico protetto proposto fornisce ulteriori dettagli.

Disattivazione da parte dell'utente

Un utente può bloccare l'accesso all'API Protected Audience e ad altre funzionalità di Privacy Sandbox utilizzando uno dei seguenti meccanismi:

  • Disattiva le prove di Privacy Sandbox nelle Impostazioni di Chrome: Impostazioni > Sicurezza e privacy > Privacy Sandbox. Questo servizio è accessibile anche all'indirizzo chrome://settings/adPrivacy.
  • Disattiva i cookie di terze parti nelle Impostazioni di Chrome: Impostazioni > Sicurezza e privacy.
  • Imposta Cookie e altri dati dei siti su "Blocca cookie di terze parti" o "Blocca tutti i cookie" in chrome://settings/cookies.
  • Usa la modalità di navigazione in incognito.

Il messaggio esplicativo di Protected Audience fornisce maggiori dettagli sugli elementi di progettazione dell'API e descrive in che modo l'API cerca di raggiungere gli obiettivi di privacy.

Eseguire il debug dei worklet di Protected Audience

A partire dalla versione 98.0.4718.0 di Chrome Canary, puoi eseguire il debug dei worklet Protected Audience all'interno di Chrome DevTools.

Il primo passaggio consiste nell'impostare i punti di interruzione tramite una nuova categoria nel riquadro Punti di interruzione listener di eventi nel riquadro Origini.

Screenshot di DevTools in Chrome Canary, che evidenzia il riquadro Punti di interruzione listener di eventi nel riquadro Origini. La voce Inizio della fase di offerta dell&#39;offerente è selezionata in Worklet dell&#39;asta dell&#39;annuncio.

Quando viene attivato un punto di interruzione, l'esecuzione viene messa in pausa prima della prima istruzione al livello superiore dello script del worklet. Puoi utilizzare punti di interruzione regolari o comandi di passaggio per accedere alla funzione di offerta, punteggio o generazione di report.

Gli script di worklet live verranno visualizzati anche nel riquadro Thread.

Screenshot di DevTools in Chrome Canary, che evidenzia il riquadro Thread nel riquadro Origini, che mostra lo script worklet corrente che è stato messo in pausa.

Poiché alcuni worklet possono essere eseguiti in parallelo, più thread potrebbero finire nello stato "in pausa"; puoi utilizzare l'elenco dei thread per passare da un thread all'altro e riprenderli o ispezionarli in modo più appropriato.

Osservare gli eventi Protected Audience

Dal riquadro Applicazione in Chrome DevTools, puoi osservare gli eventi delle aste e dei gruppi di interesse di Protected Audience.

Se visiti il sito di shopping demo di Protected Audience in un browser con Protected Audience attivato, DevTools mostrerà le informazioni sull'evento join.

Il riquadro dell&#39;applicazione DevTools in Chrome Canary che mostra informazioni su un evento di partecipazione a un gruppo di interesse di Protected Audience.

Ora, se visiti il sito del publisher della demo di Protected Audience in un browser con Protected Audience abilitato, DevTools mostra le informazioni sugli eventi bid e win.

Il riquadro dell&#39;applicazione DevTools in Chrome Canary che mostra informazioni sull&#39;offerta dell&#39;asta di Protected Audience e sugli eventi di vincita.

Come funziona l'API Protected Audience?

In questo esempio, un utente naviga nel sito web di un produttore di biciclette personalizzate e successivamente visita un sito web di notizie e visualizza un annuncio per una nuova bicicletta del produttore.

1. Un utente visita il sito di un inserzionista

Illustrazione che mostra una persona che visita il sito di un produttore di biciclette personalizzate in un browser sul proprio laptop.

Immagina che un utente visiti il sito web di un produttore di biciclette personalizzate (l'inserzionista in questo esempio) e passi del tempo sulla pagina del 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 basato sugli interessi

Illustrazione che mostra una persona che visualizza un sito in un browser sul laptop. Il codice JavaScript joinAdinterestGroup() è in esecuzione nel browser.

Sezione esplicativa: I browser registrano i gruppi 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 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 descritta nel passaggio 4. L'appartenenza ai gruppi di interesse viene memorizzata dal browser sul dispositivo dell'utente e non viene condivisa con il fornitore del browser o con altri utenti.

joinAdInterestGroup() richiede l'autorizzazione di:

  • Il sito visitato
  • Proprietario del gruppo di interesse

Ad esempio: malicious.example non deve poter chiamare joinAdInterestGroup() con dsp.example come proprietario senza l'autorizzazione di dsp.example.

Autorizzazione del sito visitato

Stessa origine: per impostazione predefinita, l'autorizzazione viene concessa implicitamente per le chiamate joinAdInterestGroup() provenienti dalla stessa origine del sito visitato, ovvero dalla stessa origine del frame di primo livello della pagina corrente. I siti possono utilizzare un'istruzione dell'intestazione dei criteri di autorizzazione join-ad-interest-group di Protected Audience per disabilitare le chiamate joinAdInterestGroup().

Cross origin: la chiamata a joinAdInterestGroup() da origini diverse dalla pagina corrente può avere esito positivo solo se il sito visitato ha impostato un criterio delle autorizzazioni che consente chiamate a joinAdInterestGroup() da iframe multiorigine.

Autorizzazione dal proprietario del gruppo di interesse

L'autorizzazione del proprietario del gruppo di interesse viene implicitamente concessa richiamando joinAdInterestGroup() da un iframe con la stessa origine del proprietario del gruppo di interesse. Ad esempio, un iframe di dsp.example può chiamare joinAdInterestGroup() per i gruppi di interesse di proprietà di dsp.example.

La proposta prevede che joinAdInterestGroup() possa essere eseguito in una pagina o in un iframe del dominio del proprietario oppure che possa essere delegata ad altri domini forniti utilizzando un elenco presente in un URL .well-known.

Utilizzo di navigator.joinAdInterestGroup()

Ecco un esempio di utilizzo dell'API:

const interestGroup = {
  owner: 'https://dsp.example',
  name: 'custom-bikes',
  biddingLogicUrl: ...,
  biddingWasmHelperUrl: ...,
  dailyUpdateUrl: ...,
  trustedBiddingSignalsUrl: ...,
  trustedBiddingSignalsKeys: ['key1', 'key2'],
  userBiddingSignals: {...},
  ads: [bikeAd1, bikeAd2, bikeAd3],
  adComponents: [customBike1, customBike2, bikePedal, bikeFrame1, bikeFrame2],
};

navigator.joinAdInterestGroup(interestGroup, 7 * kSecsPerDay);

L'oggetto interestGroup passato alla funzione non deve avere una dimensione superiore a 50 kiB, altrimenti la chiamata non andrà a buon fine. Il secondo parametro specifica la durata del gruppo basato sugli interessi, con un limite massimo di 30 giorni. Le chiamate successive sovrascriveranno i valori memorizzati in precedenza.

Proprietà dei gruppi di interesse

Proprietà Obbligatorio Esempio Ruolo
owner Obbligatorio 'https://dsp.example' Origine del proprietario del gruppo di interesse.
name Obbligatorio 'custom-bikes' Nome del gruppo basato sugli interessi.
biddingLogicUrl** Facoltativo* 'https://dsp.example/bid/custom-bikes/bid.js' URL per l'esecuzione del codice JavaScript per le offerte nel worklet.
biddingWasmHelperUrl** Facoltativo* 'https://dsp.example/bid/custom-bikes/bid.wasm' URL per il codice WebAssembly generato da biddingLogicUrl.
dailyUpdateUrl** Facoltativo 'https://dsp.example/bid/custom-bikes/update' URL che restituisce un file JSON per aggiornare gli attributi dei gruppi di interesse. (Vedi Aggiornare il gruppo basato sugli interessi.)
trustedBiddingSignalsUrl** Facoltativo 'https://dsp.example/trusted/bidding-signals' URL di base per le richieste chiave-valore al server attendibile dell'offerente.
trustedBiddingSignalsKeys Facoltativo ['key1', 'key2' ...] Chiavi per le richieste al server attendibile di coppie chiave-valore.
userBiddingSignals Facoltativo {...} Metadati aggiuntivi che il proprietario può utilizzare durante le offerte.
ads Facoltativo* [bikeAd1, bikeAd2, bikeAd3] Annunci che potrebbero essere visualizzati per questo gruppo di interesse.
adComponents Facoltativo [customBike1, customBike2, bikePedal, bikeFrame1, bikeFrame2] Componenti per annunci composti da più parti.

* Tutte le proprietà sono facoltative, ad eccezione di owner e name. Le proprietà biddingLogicUrl e ads sono facoltative, ma obbligatorie per partecipare a un'asta. Potrebbero verificarsi casi d'uso per la creazione di un gruppo basato sugli interessi senza queste proprietà: ad esempio, il proprietario di un gruppo di interesse potrebbe voler aggiungere un browser a un gruppo di interesse per una campagna non ancora pubblicata o per un altro utilizzo futuro oppure potrebbe aver esaurito temporaneamente il budget pubblicitario.

** Gli URL biddingLogicUrl, biddingWasmHelperUrl, dailyUpdateUrl e trustedBiddingSignalsUrl devono avere la stessa origine del proprietario. Gli URL ads e adComponents non hanno questo vincolo.

Aggiorna gli attributi dei gruppi di interesse

dailyUpdateUrl specifica un server web che restituisce JSON che definisce le proprietà dei gruppi di interesse, corrispondente all'oggetto gruppo di interesse passato a navigator.joinAdInterestGroup(). In questo modo, il proprietario del gruppo può aggiornare periodicamente gli attributi del gruppo di interesse. Nell'implementazione corrente, puoi modificare i seguenti attributi:

  • biddingLogicUrl
  • biddingWasmHelperUrl
  • trustedBiddingSignalsUrl
  • trustedBiddingSignalsKeys
  • ads
  • priority

Tutti i campi non specificati nel file JSON non verranno sovrascritti. Vengono aggiornati solo i campi specificati in JSON. La chiamata a navigator.joinAdInterestGroup() sovrascrive qualsiasi gruppo di interesse esistente.

Gli aggiornamenti fanno del suo meglio e possono non riuscire se presenti le seguenti condizioni:

  • Timeout richiesta di rete (attualmente 30 secondi).
  • Altro errore di rete.
  • Errore di analisi JSON.

Gli aggiornamenti possono essere annullati anche se è stato trascorso troppo tempo contiguo per l'aggiornamento, anche se ciò non impone alcuna limitazione di frequenza per gli aggiornamenti annullati (rimanenti). Gli aggiornamenti sono limitati a una frequenza massima di uno al giorno. Gli aggiornamenti non riusciti a causa di errori di rete vengono tentati di nuovo dopo un'ora, mentre gli aggiornamenti non riusciti a causa della disconnessione da internet vengono tentati di nuovo immediatamente al momento della riconnessione.

Aggiornamenti manuali

Gli aggiornamenti ai gruppi di interesse appartenenti all'origine del frame corrente possono essere attivati manualmente tramite navigator.updateAdInterestGroups(). La limitazione di frequenza impedisce che gli aggiornamenti vengano aggiornati troppo spesso: le chiamate ripetute a navigator.updateAdInterestGroups() non eseguono alcuna azione finché non è trascorso il periodo di limite di frequenza (attualmente un giorno). Il limite di tasso viene reimpostato se navigator.joinAdInterestGroup() viene richiamato per lo stesso gruppo basato sugli interessi owner e name.

Aggiornamenti automatici

Tutti i gruppi di interesse caricati per un'asta vengono aggiornati automaticamente al termine dell'asta, con gli stessi limiti di frequenza degli aggiornamenti manuali. Per ogni proprietario con almeno un gruppo di interesse che partecipa a un'asta, è come se navigator.updateAdInterestGroups() venisse chiamato da un iframe la cui origine corrisponde a quel proprietario.

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?

Lo script all'indirizzo biddingLogicUrl fornito dal proprietario di un gruppo di interesse deve includere una funzione generateBid(). Quando un venditore dello spazio pubblicitario chiama navigator.runAdAuction(), la funzione generatedBid() viene chiamata una volta per ogni gruppo basato sugli interessi di cui il browser fa parte, se il proprietario del gruppo di interessi è invitato a fare un'offerta. In altre parole, generateBid() viene chiamato una volta per ogni annuncio candidato. Il venditore fornisce una proprietà decisionLogicUrl nel parametro di configurazione dell'asta trasmesso a navigator.runAdAuction(). Il codice a questo URL deve includere una funzione scoreAd(), che viene eseguita per ogni offerente nell'asta, per assegnare un punteggio a ciascuna delle offerte restituite da generateBid().

Lo script in biddingLogicUrl fornito da un acquirente di spazio pubblicitario deve includere una funzione generateBid(). Questa funzione viene chiamata una volta per ogni annuncio candidato. runAdAuction() controlla singolarmente ogni annuncio, insieme all'offerta e ai metadati associati, quindi assegna all'annuncio un punteggio di desiderabilità numerico.

generateBid(interestGroup, auctionSignals, perBuyerSignals,
    trustedBiddingSignals, browserSignals) {
  ...
  return {
    ad: adObject,
    bid: bidValue,
    render: renderUrl,
    adComponents: [adComponentRenderUrl1, ...]
   };
}

generateBid() accetta i seguenti argomenti:

  • interestGroup
    L'oggetto passato a joinAdInterestGroup() dall'acquirente dell'annuncio. (Il gruppo basato sugli interessi può essere aggiornato tramite dailyUpdateUrl.)

  • auctionSignals
    Una proprietà dell'argomento configurazione delle aste passata a navigator.runAdAuction() dal venditore dello spazio pubblicitario. Fornisce informazioni sul contesto della pagina (come le dimensioni dell'annuncio e l'ID publisher), il tipo di asta (primo prezzo o secondo prezzo) e altri metadati.

  • perBuyerSignals
    Come per auctionSignals, una proprietà dell'argomento configurazione dell'asta trasferita a navigator.runAdAuction() dal venditore. In questo modo, il server dell'acquirente può fornire indicatori contestuali relativi alla pagina, se il venditore è una SSP che esegue una chiamata per offerte in tempo reale ai server dell'acquirente e restituisce la risposta oppure se la pagina del publisher contatta direttamente il server dell'acquirente. In questo caso, l'acquirente potrebbe voler controllare una firma crittografica di questi indicatori all'interno di generateBid() come protezione dalle manomissioni.

  • trustedBiddingSignals
    Un oggetto le cui chiavi sono le trustedBiddingSignalsKeys per il gruppo di interesse e i cui valori vengono restituiti nella richiesta trustedBiddingSignals.

  • browserSignals
    Un oggetto creato dal browser, che potrebbe includere informazioni sul contesto della pagina (come il hostname della pagina corrente, che il venditore potrebbe altrimenti falsificare) e dati per il gruppo di interesse stesso (ad esempio un record di quando il gruppo ha vinto in precedenza un'asta, per consentire la quota limite on-device).

L'oggetto browserSignals ha le seguenti proprietà:

{
  topWindowHostname: 'publisher.example',
  seller: 'https://ssp.example',
  joinCount: 3,
  bidCount: 17,
  prevWins: [[time1,ad1],[time2,ad2],...],
  wasmHelper: ... /* WebAssembly.Module object based on interest group's biddingWasmHelperUrl. */
  dataVersion: 1, /* Data-Version value from the buyer's Key/Value service response(s). */
}

Per calcolare un valore bid, il codice in generateBid() può utilizzare le proprietà dei parametri della funzione. Ad esempio:

function generateBid(interestGroup, auctionSignals, perBuyerSignals,
    trustedBiddingSignals, browserSignals) {
  return {
    ...
    bid: auctionSignals.is_above_the_fold ? perBuyerSignals.atf_value : perBuyerSignals.btf_value,
    ...
  }
}

generateBid() restituisce un oggetto con quattro proprietà:

  • ad
    Metadati arbitrari sull'annuncio, ad esempio informazioni che il venditore si aspetta di ricevere su questa offerta o sulla creatività dell'annuncio. Il venditore](/privacy-sandbox/resources/glossario#ssp) utilizza queste informazioni nella propria asta e nella propria creatività per la decisione. Il venditore utilizza queste informazioni nella propria logica di asta e decisionale.

  • bid
    Un'offerta numerica che parteciperà all'asta. Il venditore deve essere in grado di confrontare le offerte di acquirenti diversi, pertanto le offerte devono rientrare in alcune unità scelte dal venditore (ad es. "USD per migliaia"). Se l'offerta è zero o negativa, questo gruppo di interesse non parteciperà all'asta del venditore. Con questo meccanismo, l'acquirente può implementare qualsiasi regola dell'inserzionista che determina dove i suoi annunci possono o meno essere pubblicati.

  • render
    Un URL o un elenco di URL che verrà utilizzato per mostrare la creatività se l'offerta vince l'asta. (consulta Annunci composti da più parti nell'spiegazione dell'API.) Il valore deve corrispondere a renderUrl di uno degli annunci definiti per il gruppo di interesse.

  • adComponents
    Un elenco facoltativo di massimo 20 componenti per annunci composti da più parti, tratto dalla proprietà adComponents dell'argomento gruppo di interesse passato a navigator.joinAdInterestGroup().

Chiedere a un browser di abbandonare un gruppo basato sugli interessi

Il proprietario del gruppo di interesse può richiedere la rimozione di un browser da un gruppo di interesse. In altre parole, al browser viene chiesto di rimuovere il gruppo basato sugli interessi dall'elenco dei gruppi di cui fa parte.

navigator.leaveAdInterestGroup({
  owner: 'https://dsp.example',
  name: 'custom-bikes'
});

Se un utente torna sul sito che ha chiesto al browser di aggiungere un gruppo di interesse, il proprietario del gruppo di interesse può chiamare la funzione navigator.leaveAdInterestGroup() per richiedere al browser di rimuovere il gruppo di interesse. Il codice di un annuncio può chiamare questa funzione anche per il relativo gruppo di interesse.

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

Illustrazione che mostra una persona che visita un sito web di notizie in un browser sul laptop. Il sito ha un&#39;area annuncio vuota.

In seguito, l'utente visita un sito che vende spazio pubblicitario, in questo esempio un sito web di notizie. Il sito ha un inventario pubblicitario, che vende in modo programmatico utilizzando le offerte in tempo reale.

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

Illustrazione che mostra una persona che visualizza un sito web di notizie in un browser sul laptop. È in corso un&#39;asta dell&#39;annuncio che utilizza l&#39;API Protected Audience.

Sezione esplicativa: I venditori eseguono aste on-device

È probabile che l'asta dell'annuncio venga gestita dall'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.

Il venditore dello spazio pubblicitario richiede al browser dell'utente di iniziare un'asta dell'annuncio chiamando il numero navigator.runAdAuction().

Ad esempio:

const auctionConfig = {
  seller: 'https://ssp.example',
  decisionLogicUrl: ...,
  trustedScoringSignalsUrl: ...,
  interestGroupBuyers: ['https://dsp.example', 'https://buyer2.example', ...],
  auctionSignals: {...},
  sellerSignals: {...},
  sellerTimeout: 100,
  perBuyerSignals: {
    'https://dsp.example': {...},
    'https://another-buyer.example': {...},
    ...
  },
  perBuyerTimeouts: {
    'https://dsp.example': 50,
    'https://another-buyer.example': 200,
    '*': 150,
    ...
  },
  componentAuctions: [
    {
      'seller': 'https://some-other-ssp.example',
      'decisionLogicUrl': ...,
      ...
    },
    ...
  ]
};

const auctionResultPromise = navigator.runAdAuction(auctionConfig);

runAdAuction() restituisce una promessa che si risolve in un'URN (urn:uuid:<something>) che rappresenta il risultato dell'asta dell'annuncio. Può essere decodificato dal browser solo quando viene passato a un frame recintato per il rendering: la pagina del publisher non può esaminare l'annuncio vincente.

Lo script decisionLogicUrl considera ogni singolo annuncio, insieme all'offerta e ai metadati associati, uno alla volta, quindi assegna un punteggio di desiderabilità numerica.

auctionConfig strutture

Proprietà Obbligatorio Esempio Ruolo
seller Obbligatorio 'https://ssp.example' Origine del venditore.
decisionLogicUrl Obbligatorio 'https://ssp.example/auction-decision-logic.js' URL per il codice JavaScript del worklet dell'asta.
trustedScoringSignalsUrl Facoltativo 'https://ssp.example/scoring-signals' URL del server affidabile del venditore.
interestGroupBuyers* Obbligatorio ['https://dsp.example', 'https://buyer2.example', ...] Le origini di tutti i proprietari di gruppi di interesse a cui è stato chiesto di fare offerte nell'asta.
auctionSignals Facoltativo {...} Informazioni sul venditore relative al contesto della pagina, al tipo di asta e così via.
sellerSignals Facoltativo {...} Informazioni basate sulle impostazioni del publisher, sull'invio di una richiesta di annuncio contestuale e così via.
sellerTimeout Facoltativo 100 Tempo di esecuzione massimo (ms) dello script scoreAd() del venditore.
perBuyerSignals Facoltativo {'https://dsp.example': {...},
  'https://another-buyer.example': {...},
...}		 Indicatori contestuali relativi alla pagina per ogni acquirente specifico, provenienti dal relativo server.
perBuyerTimeouts Facoltativo 50 Tempo di esecuzione massimo (ms) di determinati script generateBid() di un acquirente.
componentAuctions Facoltativo [{'seller': 'https://www.some-other-ssp.com',
  'decisionLogicUrl': ..., ...},
  ...]		 Configurazioni aggiuntive per le aste dei componenti.

* Il venditore può specificare interestGroupBuyers: '*' per consentire a tutti i gruppi di interesse di fare offerte. Gli annunci vengono quindi accettati o rifiutati in base a criteri diversi dall'inclusione del proprietario del gruppo di interesse. Ad esempio, il venditore può esaminare le creatività degli annunci per verificarne la conformità alle proprie norme.

** La funzionalità additionalBids non è supportata nell'attuale implementazione di Protected Audience. Per ulteriori informazioni, leggi la sezione Partecipanti all'asta nella spiegazione di Protected Audience.

Come vengono selezionati gli annunci?

Il codice in decisionLogicUrl (una proprietà dell'oggetto di configurazione dell'asta passato a runAdAuction()) deve includere una funzione scoreAd(). Questa viene eseguita una volta per ogni annuncio al fine di determinarne l'idoneità.

scoreAd(adMetadata, bid, auctionConfig, trustedScoringSignals, browserSignals) {
  ...
  return desirabilityScoreForThisAd;
}

scoreAd() accetta i seguenti argomenti:

  • adMetadata
    Metadati arbitrari forniti dall'acquirente.
  • bid
    Un valore numerico dell'offerta.
  • auctionConfig
    L'oggetto di configurazione dell'asta passato a navigator.runAdAuction().
  • trustedScoringSignals
    Valori recuperati al momento dell'asta dal server attendibile del venditore, che rappresentano l'opinione del venditore sull'annuncio.
  • browserSignals
    Un oggetto creato dal browser, incluse informazioni note a quest'ultimo e che lo script dell'asta del venditore potrebbe voler verificare:
{
  topWindowHostname: 'publisher.example',
  interestGroupOwner: 'https://dsp.example',
  renderUrl: 'https://cdn.example/render',
  adComponents: ['https://cdn.com/ad-component-1', ...],
  biddingDurationMsec: 12,
  dataVersion: 1 /* Data-Version value from the seller's Key/Value service response. */
}

Prima dell'inizio di un'asta, il venditore trova il miglior annuncio contestuale per l'area annuncio disponibile. Parte della sua logica scoreAd() consiste nel rifiutare qualsiasi annuncio che non sia in grado di battere il vincitore contestuale.

5. Il venditore e gli acquirenti partecipanti ricevono i dati in tempo reale dal servizio chiave/valore.

Illustrazione che mostra una persona che visualizza un sito web di notizie in un browser sul laptop. È in corso un&#39;asta dell&#39;annuncio con l&#39;API Protected Audience, con un partecipante che riceve dati dal servizio chiave/valore.

Sezione esplicativa: Recupero dei dati in tempo reale dal servizio chiave/valore Protected Audience.

Durante un'asta dell'annuncio, il venditore dello spazio pubblicitario può ricevere dati in tempo reale su specifiche creatività annuncio inviando una richiesta a un servizio chiave/valore utilizzando la proprietà trustedScoringSignalsUrl dell'argomento configurazione dell'asta passato a navigator.runAdAuction(), insieme alle chiavi delle proprietà renderUrl di tutte le voci nei campi ads e adComponents di tutti i gruppi di interesse nell'asta.

Allo stesso modo, un acquirente dello spazio pubblicitario 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 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.

6. Viene visualizzato l'annuncio vincente

Illustrazione che mostra una persona che visualizza un sito web di notizie in un browser sul laptop. Viene mostrato un annuncio per una bicicletta (20% di sconto), con un lucchetto sopra che indica che l&#39;annuncio viene mostrato in un frame recintato.

Sezione esplicativa: I browser eseguono il rendering dell'annuncio vincente

Come descritto in precedenza, la promessa restituita da runAdAuction() si risolve in un URN che viene passato a un frame recintato per il rendering e il sito visualizza l'annuncio vincente.

7. Il risultato dell'asta viene registrato

Sezione esplicativa: report a livello di evento (per ora)

Risultato dei report del venditore

Sezione esplicativa: Report dei venditori sul rendering

Il codice JavaScript del venditore fornito all'indirizzo decisionLogicUrl (che ha fornito anche scoreAd()) può includere una funzione reportResult(), per segnalare il risultato dell'asta.

reportResult(auctionConfig, browserSignals) {
  ...
  return signalsForWinner;
}

Gli argomenti passati a questa funzione sono:

  • auctionConfig
    L'oggetto di configurazione dell'asta passato a navigator.runAdAuction().

  • browserSignals
    Un oggetto creato dal browser che fornisce informazioni sull'asta. Ad esempio:

    {
  'topWindowHostname': 'publisher.example',
  'interestGroupOwner': 'https://dsp.example',
  'renderUrl': 'https://cdn.example/url-of-winning-creative.wbn',
  'bid:' <bidValue>,
  'desirability': <winningAdScore>
}

Il valore restituito di questa funzione viene utilizzato come argomento sellerSignals per la funzione reportWin() dell'offerente vincente.

Risultato dei report sugli offerenti vincitori

Sezione esplicativa: Report per gli acquirenti su eventi di rendering e degli annunci

Il codice JavaScript dell'offerente vincente (che ha fornito anche generateBid()) può includere una funzione reportWin() per segnalare il risultato dell'asta.

reportWin(auctionSignals, perBuyerSignals, sellerSignals, browserSignals) {
  ...
}

Gli argomenti passati a questa funzione sono:

  • auctionSignals e perBuyerSignals
    Gli stessi valori trasmessi a generateBid() per l'offerente vincente.
  • sellerSignals
    Il valore restituito di reportResult(), che offre al venditore l'opportunità di trasmettere informazioni all'acquirente.

  • browserSignals
    Un oggetto creato dal browser che fornisce informazioni sull'asta. Ad esempio:

    {
  'topWindowHostname': 'publisher.example',
  'seller': 'https://ssp.example',
  'interestGroupOwner': 'https://dsp.example',
  'interestGroupName': 'custom-bikes',
  'renderUrl': 'https://cdn.example/winning-creative.wbn',
  'bid:' <bidValue>
}

Implementazione di report sulle perdite/conquiste temporanee

Esistono due metodi temporaneamente disponibili in Chrome per i report sulle aste:

  • forDebuggingOnly.reportAdAuctionLoss()
  • forDebuggingOnly.reportAdAuctionWin()

Ciascuno di questi metodi utilizza un singolo argomento: un URL da recuperare dopo il completamento dell'asta. Possono essere chiamati più volte, in scoreAd() e generateBid(), con argomenti URL diversi.

Chrome invia report sulla perdita o sulle vincite di debug solo quando un'asta viene eseguita fino al completamento. Se un'asta viene annullata (ad esempio a causa di una nuova navigazione), non verranno generati report.

Questi metodi sono disponibili per impostazione predefinita in Chrome. Per poter testare i metodi, attiva tutte le API di privacy per gli annunci in chrome://settings/adPrivacy. Se esegui Chrome con flag della riga di comando per attivare Protected Audience, dovrai attivare esplicitamente i metodi includendo il flag BiddingAndScoringDebugReportingAPI. Se il flag non è abilitato, i metodi saranno comunque disponibili, ma non faranno nulla.

8. Viene registrato un clic sull'annuncio

Illustrazione che mostra una persona che fa clic su un annuncio relativo a una bicicletta, all&#39;interno di un telaio recintato, su un sito web di notizie, con dati del report rivolti a venditore e acquirenti.

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.


Il diagramma seguente illustra ogni fase di un'asta dell'annuncio Protected Audience:

Illustrazione che fornisce una panoramica di ogni fase di un&#39;asta dell&#39;annuncio Protected Audience


Qual è la differenza tra Protected Audience e TURTLEDOVE?

Protected Audience è il primo esperimento implementato in Chromium all'interno della famiglia di proposte TURTLEDOVE.

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 funzionava perché l'inserzionista riconosceva una persona specifica mentre naviga tra i siti web, un problema di privacy fondamentale 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 relative agli 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 chi è o la pagina che sta visitando.

Protected Audience è nata da TURTLEDOVE e da una raccolta di proposte correlate di 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). Protected Audience comprende un uso più limitato dei TEE, per la ricerca di dati in tempo reale e la generazione di report aggregati.
  • Le proposte TERN e Magnite di NextRoll e PARRROT descrivono i diversi ruoli che acquirenti e venditori avevano nell'asta on-device. Il flusso di offerte/punteggio di 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. Protected Audience non ha adottato questo modello di proxy. Stiamo allineando le API JavaScript per PARAKEET e Protected Audience, a supporto dei lavori futuri per combinare ulteriormente le migliori funzionalità di entrambe le proposte.

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 nel tempo.

Quale 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 di Privacy Sandbox per disattivare 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 per le tecnologie 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 man mano che la proposta Protected Audience procede, in base a test e feedback. In futuro, prevediamo di offrire impostazioni più granulari per gestire 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.



Interagisci e condividi il feedback

Ricevi assistenza

Per domande sulla tua implementazione, sulla demo o sulla documentazione:

Per bug e problemi relativi all'implementazione dell'API Protected Audience in Chrome: * Visualizza i problemi esistenti segnalati per l'API. * Segnala un nuovo problema all'indirizzo crbug.com/new.

Ricevi aggiornamenti

Scopri di più

Foto di Ray Hennessy su Unsplash.