Guida per gli sviluppatori dell'API FLEDGE

A chi è rivolto questo articolo?

Questo post è un riferimento tecnico all'iterazione corrente 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 da non poter essere utilizzata da terze parti per monitorare il comportamento di navigazione degli utenti tra i 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.

Protected Audience è il primo esperimento da implementare 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 faccio a provare Protected Audience?

Demo di Protected Audience

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

Il video dimostrativo spiega come funziona il codice di esempio e mostra come utilizzare Chrome DevTools per il debug di Protected Audience.

Partecipare a una prova dell'origine di Protected Audience

È stata messa a disposizione una prova dell'origine per la misurazione e la pertinenza 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 ricevere un token di prova dell'origine.

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

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

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

  • Come meta tag in <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 gruppo di interesse, dovrà fornire un token corrispondente alla sua origine.

Dettagli della prima prova dell'origine Protected Audience proposta fornisce ulteriori dettagli sugli obiettivi della prima prova e spiega quali funzionalità sono supportate.

Prova questa API

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

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

Eseguire il rendering degli annunci in iframe o frame delimitati

Gli annunci possono essere visualizzati in un <iframe> o in un <fencedframe>, a seconda dei flag 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 i metodi di generazione di report temporanei per le conversioni di tipo Win/Loss.

L'articolo Eseguire Chromium con i flag descrive come impostare i flag quando esegui Chrome e altri browser basati su Chromium dalla riga di comando. L'elenco completo degli indicatori relativi al pubblico protetto è disponibile su Chromium Code Search.

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

Protected Audience viene reso disponibile dietro i flag delle funzionalità in Chromium come primo sperimentale per testare le seguenti funzionalità della proposta Protected Audience:

  • Gruppi di interesse: memorizzati dal browser, con metadati associati per configurare l'asta e il rendering degli annunci.
  • Offerte sul dispositivo da parte degli acquirenti (DSP o inserzionista): in base ai gruppi di interesse e agli indicatori memorizzati dal 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 logging consentiti per il rendering degli annunci.

L'explainer dell'API fornisce ulteriori dettagli sui vincoli e sul supporto delle funzionalità.

Autorizzazioni dei gruppi di interesse

Il valore predefinito nell'attuale implementazione di Protected Audience è consentire di chiamare joinAdInterestGroup() da qualsiasi punto di una pagina, anche da iframe cross-domain. In futuro, dopo che i proprietari dei siti avranno avuto il tempo di modificare i propri criteri relativi alle autorizzazioni per gli iframe interdominio, è previsto di non consentire le chiamate provenienti da questi elementi, come descritto nella spiegazione.

Servizio coppia chiave-valore

Nell'ambito di un'asta di annunci 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 rimanente della campagna. La proposta Protected Audience obbliga a garantire che questo server "non esegua registrazioni a livello di evento e non abbia altri effetti collaterali in base a queste richieste".

Il codice del servizio Protected Audience Key/Value è ora disponibile in un repository GitHub di Privacy Sandbox. Questo servizio può essere utilizzato dagli sviluppatori di Chrome e Android. Consulta il post del blog relativo all'annuncio per l'aggiornamento dello stato. Scopri di più sul servizio Protected Audience Key/Value dall'explainer dell'API e dall'explainer del modello di attendibilità.

Per i test iniziali, viene utilizzato il modello "Bring Your Own Server". A lungo termine, le aziende di ad tech dovranno utilizzare i servizi chiave/valore open source di Protected Audience in ambienti di esecuzione attendibili per recuperare i dati in tempo reale.

Per garantire all'ecosistema tempo sufficiente per i test, non prevediamo di richiedere l'utilizzo dei servizi Key/Value o dei TEE open source fino a qualche tempo dopo il ritiro dei cookie di terze parti. 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 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 in qualità di proprietario del sito o di singolo utente.

In che modo i siti possono controllare l'accesso?

In futuro, Protected Audience richiederà ai siti di impostare un criterio relativo alle autorizzazioni per consentire la disponibilità della funzionalità. In questo modo, contribuirai a garantire che terze parti arbitrarie non possano utilizzare l'API senza اطلاع del sito. Tuttavia, per semplificare i test durante la prima prova dell'origine, questo requisito viene rinunciato per impostazione predefinita. I siti che vogliono disattivare esplicitamente la funzionalità Protected Audience durante il periodo di test possono utilizzare le Norme relative alle autorizzazioni pertinenti per bloccare l'accesso.

Esistono due criteri di autorizzazione 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 sul dispositivo

L'accesso alle API Protected Audience può essere disattivato completamente nei contesti proprietari specificando il seguente criterio di autorizzazione in un'intestazione di 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 per la prima prova dell'origine Protected Audience proposta 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. È 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" da chrome://settings/cookies.
  • Utilizza la modalità di navigazione in incognito.

Lo Spiegabile di Protected Audience fornisce ulteriori dettagli sugli elementi di progettazione dell'API e descrive in che modo l'API cerca di raggiungere gli obiettivi relativi alla privacy.

Eseguire il debug dei worklet Protected Audience

Da Chrome Canary 98.0.4718.0 è possibile eseguire il debug dei worklet Protected Audience in Chrome DevTools.

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

Screenshot di DevTools in Chrome Canary che evidenzia il riquadro Punti di interruzione listener di eventi nel riquadro Origini. Inizio della fase di offerta da parte degli offerenti è selezionato 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 a livello superiore dello script del worklet. Puoi utilizzare breakpoint o comandi di passaggio regolari per accedere alla funzione di offerta/punteggio/report stessa.

Gli script dei worklet in tempo reale verranno visualizzati anche nel riquadro Thread.

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

Poiché alcuni worklet possono essere eseguiti in parallelo, più thread potrebbero trovarsi nello stato "in pausa". Puoi utilizzare l'elenco dei thread per passare da un thread all'altro e riprenderli o ispezionarli più da vicino, se opportuno.

Osservare gli eventi Protected Audience

Dal riquadro Applicazione in Chrome DevTools, puoi osservare gli eventi di asta e del gruppo di interessi Protected Audience.

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

Il riquadro App di DevTools in Chrome Canary, che mostra informazioni su un evento di partecipazione a un gruppo di interesse Protected Audience.

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

Il riquadro App di Strumenti per sviluppatori in Chrome Canary, che mostra informazioni sulle offerte e sugli eventi di assegnazione dell&#39;asta Protected Audience.

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 visualizza un annuncio di 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 suo laptop.

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 nella 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

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

Sezione informativa: 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 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 descritta nel passaggio 4. 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.

joinAdInterestGroup() richiede l'autorizzazione di:

  • Il sito visitato
  • Il proprietario del gruppo di interesse

Ad esempio, non deve essere possibile per malicious.example 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'intestazione del criterio di autorizzazione di Protected Audience join-ad-interest-group per disattivare le chiamate joinAdInterestGroup().

Multiorigine: la chiamata a joinAdInterestGroup() da origini diverse dalla pagina corrente può essere eseguita correttamente solo se il sito visitato ha impostato un criterio di autorizzazione che consenta le chiamate a joinAdInterestGroup() da iframe multiorigine.

Autorizzazione del proprietario del gruppo di interesse

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

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

Utilizzo di navigator.joinAdInterestGroup()

Ecco un esempio di come potrebbe essere utilizzata l'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 dimensioni superiori a 50 KiB, altrimenti la chiamata non andrà a buon fine. Il secondo parametro specifica la durata del gruppo di interesse, con un limite di 30 giorni. Le chiamate successive sovrascrivono 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 di interesse.
biddingLogicUrl** Facoltativo* 'https://dsp.example/bid/custom-bikes/bid.js' URL per l'esecuzione di JavaScript per le offerte nel worklet.
biddingWasmHelperUrl** Facoltativo* 'https://dsp.example/bid/custom-bikes/bid.wasm' URL per il codice WebAssembly eseguito da biddingLogicUrl.
dailyUpdateUrl** Facoltativo 'https://dsp.example/bid/custom-bikes/update' URL che restituisce JSON per aggiornare gli attributi del gruppo di interesse. (vedi Aggiornare il gruppo di interesse).
trustedBiddingSignalsUrl** Facoltativo 'https://dsp.example/trusted/bidding-signals' URL di base per le richieste di chiavi e valori al server attendibile dell'offerente.
trustedBiddingSignalsKeys Facoltativo ['key1', 'key2' ...] Chiavi per le richieste al server attendibile con coppia 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 interessi.
adComponents Facoltativo [customBike1, customBike2, bikePedal, bikeFrame1, bikeFrame2] Componenti per annunci composti da più elementi.

* Tutte le proprietà sono facoltative, ad eccezione di owner e name. Le proprietà biddingLogicUrl e ads sono facoltative, ma necessarie per partecipare a un'asta. Potrebbero esserci casi d'uso per la creazione di un gruppo di interesse senza queste proprietà: ad esempio, un 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 del gruppo di interesse

dailyUpdateUrl specifica un server web che restituisce JSON che definisce le proprietà del gruppo di interesse, corrispondente all'oggetto gruppo di interesse passato a navigator.joinAdInterestGroup(). In questo modo, il proprietario del gruppo ha a disposizione un meccanismo per aggiornare periodicamente gli attributi del gruppo di interesse. Nell'implementazione attuale, è possibile modificare i seguenti attributi:

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

Qualsiasi campo non specificato nel JSON non verrà sovrascritto, ma solo i campi specificati nel JSON vengono aggiornati, mentre la chiamata a navigator.joinAdInterestGroup() sovrascrive qualsiasi gruppo di interesse esistente.

Gli aggiornamenti vengono eseguiti secondo il criterio del massimo impegno e possono non andare a buon fine nelle seguenti condizioni:

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

Gli aggiornamenti possono essere annullati anche se è stato impiegato troppo tempo consecutivo per l'aggiornamento, anche se questo non impone alcuna limitazione di frequenza agli aggiornamenti annullati (rimasti). Gli aggiornamenti sono limitati a un massimo di uno al giorno. Gli aggiornamenti che non riescono a causa di errori di rete vengono riprovati dopo un'ora, mentre quelli che non riescono a causa di una disconnessione da internet vengono riprovati immediatamente al ricoinvolgimento.

Aggiornamenti manuali

Gli aggiornamenti ai gruppi di interesse di proprietà dell'origine del frame corrente possono essere attivati manualmente tramite navigator.updateAdInterestGroups(). Il limite di frequenza impedisce che gli aggiornamenti vengano eseguiti troppo di frequente: le chiamate ripetute a navigator.updateAdInterestGroups() non fanno nulla finché non è trascorso il periodo di limite di frequenza (attualmente un giorno). Il limite di frequenza viene reimpostato se navigator.joinAdInterestGroup() viene richiamato di nuovo per lo stesso gruppo di interesse owner e name.

Aggiornamenti automatici

Tutti i gruppi di interesse caricati per un'asta vengono aggiornati automaticamente al termine dell'asta, in base agli stessi limiti di frequenza degli aggiornamenti manuali. Per ogni proprietario con almeno un gruppo di interessi 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'asta. Ad esempio:

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

In che modo gli acquirenti fanno offerte?

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

Lo script all'indirizzo 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 di annunci. Il gruppo di interesse può essere aggiornato tramite dailyUpdateUrl.

  • auctionSignals
    Una proprietà dell'argomento config asta passata a navigator.runAdAuction() dal venditore di spazio pubblicitario. Fornisce informazioni sul contesto della pagina (ad es. le dimensioni dell'annuncio e l'ID publisher), sul tipo di asta (al primo prezzo o al secondo prezzo) e su altri metadati.

  • perBuyerSignals
    Come per auctionSignals, una proprietà dell'argomento configurazione dell'asta passata a navigator.runAdAuction() dal venditore. In questo modo, il server dell'acquirente può fornire indicatori contestuali sulla pagina, se il venditore è una SSP che esegue una chiamata di 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 cryptographica di questi indicatori all'interno di generateBid() come protezione contro le manomissioni.

  • trustedBiddingSignals
    Un oggetto le cui chiavi sono i 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 (ad esempio 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 il capping della frequenza sul dispositivo).

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 le informazioni che il venditore si aspetta di ottenere su questa offerta o sulla creatività dell'annuncio. Il venditore](/resources/glossary#ssp) utilizza queste informazioni nelle aste e nelle creatività per le decisioni relative agli annunci. Il venditore utilizza queste informazioni nella sua asta e nella sua logica decisionale.

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

  • render
    Un URL o un elenco di URL che verrà utilizzato per il rendering della creatività se questa offerta vince l'asta. (consulta la sezione Annunci composti da più elementi nella 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ù elementi, tratto dalla proprietà adComponents dell'argomento gruppo di interessi trasmesso a navigator.joinAdInterestGroup().

Chiedere a un browser di abbandonare un gruppo di interesse

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 di interesse dall'elenco di quelli di cui fa parte.

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

Se un utente torna al 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 suo laptop. Il sito ha uno spazio annuncio vuoto.

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 inventario pubblicitario, che vende in modo programmatico utilizzando le offerte in tempo reale.

4. Viene eseguita un'asta di annunci nel browser

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

Sezione informativa: Venditori che pubblicano aste on-device

L'asta di annunci è probabilmente gestita dalla SSP del publisher o dal publisher stesso. Lo scopo dell'asta è selezionare l'annuncio più appropriato per un singolo suo spazio disponibile nella pagina corrente. L'asta prende in considerazione i gruppi di interesse di cui fa parte il browser, insieme ai dati degli acquirenti e dei venditori di spazi pubblicitari dei servizi Key/Value.

Il venditore di spazio pubblicitario invia una richiesta al browser dell'utente per avviare un'asta di annunci chiamando 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 di annunci. Questo può essere decodificato dal browser solo quando viene passato a un frame delimitato per il rendering: la pagina del publisher non può ispezionare l'annuncio vincente.

Lo script decisionLogicUrl prende in considerazione ogni singolo annuncio, insieme all'offerta e ai metadati associati, uno alla volta, per poi assegnargli un punteggio di desiderabilità numerico.

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 attendibile del venditore.
interestGroupBuyers* Obbligatorio ['https://dsp.example', 'https://buyer2.example', ...] Origini di tutti i proprietari di gruppi di interesse a cui è stato chiesto di fare offerte nell'asta.
auctionSignals Facoltativo {...} Informazioni del venditore sul contesto della pagina, sul 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 sulla pagina per ogni acquirente specifico, dal suo server.
perBuyerTimeouts Facoltativo 50 Tempo di esecuzione massimo (ms) degli script generateBid() di un determinato acquirente.
componentAuctions Facoltativo [{'seller': 'https://www.some-other-ssp.com',
  'decisionLogicUrl': ..., ...},
  ...]		 Configurazioni aggiuntive per le aste di 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 potrebbe esaminare le creatività degli annunci per verificare la conformità alle sue norme.

** additionalBids non è supportato nell'attuale implementazione di Protected Audience. Per ulteriori informazioni, leggi la sezione Partecipanti all'asta della spiegazione di Protected Audience.

Come vengono selezionati gli annunci?

Il codice in decisionLogicUrl (una proprietà dell'oggetto di configurazione dell'asta passata a runAdAuction()) deve includere una funzione scoreAd(). Viene eseguito una volta per ogni annuncio per determinarne la desiderabilità.

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

scoreAd() accetta i seguenti argomenti:

  • adMetadata
    Metadati arbitrari forniti dall'acquirente.
  • bid
    Un valore di offerta numerico.
  • 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 le informazioni che il browser conosce 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 l'annuncio contestuale migliore per l'area annuncio disponibile. Parte della logica di scoreAd() è rifiutare qualsiasi annuncio che non riesce a battere l'annuncio vincente contestuale.

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

Illustrazione che mostra una persona che visualizza un sito web di notizie in un browser sul suo laptop. È in corso un&#39;asta di annunci che utilizza l&#39;API Protected Audience, con un partecipante che riceve dati dal servizio Key/Value.

Sezione informativa: Recupero dei dati in tempo reale dal servizio Protected Audience Key/Value.

Durante un'asta di annunci, il venditore di spazi pubblicitari può ottenere dati in tempo reale su creatività specifiche inviando una richiesta a un servizio Key/Value 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.

Analogamente, un acquirente di spazio pubblicitario può richiedere dati in tempo reale dal servizio Key/Value 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.
  • 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.

6. Viene visualizzato l'annuncio vincente

Illustrazione che mostra una persona che visualizza un sito web di notizie in un browser sul suo laptop. Viene visualizzato un annuncio per una bicicletta (20% di sconto) con un lucchetto sopra per indicare che l&#39;annuncio è visualizzato in un riquadro delimitato.

Sezione informativa: I browser visualizzano l'annuncio vincente

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

7. Il risultato dell'asta viene registrato

Sezione di spiegazione: Report a livello di evento (per il momento)

Risultato dei report del venditore

Sezione informativa: Report del venditore sul rendering

Il codice JavaScript del venditore fornito all'indirizzo decisionLogicUrl (che ha fornito anche scoreAd()) può includere una funzione reportResult() per segnalare l'esito 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 da questa funzione viene utilizzato come argomento sellerSignals per la funzione reportWin() dell'offerente vincente.

L'offerente vincente segnala l'esito

Sezione informativa: Report per i buyer sugli eventi di rendering e sugli annunci

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

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

Gli argomenti passati a questa funzione sono:

  • auctionSignals e perBuyerSignals
    Gli stessi valori passati a generateBid() per l'offerente vincente.
  • sellerSignals
    Il valore restituito di reportResult(), che offre al venditore un'opportunità per 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 temporanea dei report sulle perdite/vittorie

In Chrome sono disponibili temporaneamente due metodi per i report sulle aste:

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

Questi metodi accettano ciascuno un singolo argomento: un URL da recuperare al termine dell'asta. Possono essere chiamati più volte, sia in scoreAd() che in generateBid(), con argomenti URL diversi.

Chrome invia report di debug su perdita/vittoria solo quando un'asta viene completata. 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, abilita 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 è attivato, 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 di una bicicletta, all&#39;interno di un riquadro delimitato, su un sito web di notizie, con i dati dei report inviati a venditori e acquirenti.

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


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

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


Qual è la differenza tra Protected Audience e TURTLEDOVE?

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

Protected Audience segue i principi generali di TURTLEDOVE. Alcuni tipi di 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. In passato, questo approccio ha funzionato perché l'inserzionista riconosceva una persona specifica mentre navigava sui siti web, un problema fondamentale per la privacy sul web di oggi.

L'iniziativa TURTLEDOVE mira a 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, contiene le informazioni su ciò che l'inserzionista ritiene sia di interesse di 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 sulla sua identità o sulla pagina che sta visitando.

Protected Audience è nato 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 ambiente di esecuzione affidabile (TEE). 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 di Protected Audience si basa su questo lavoro.
  • Le modifiche di TURTLEDOVE di RTB House 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. Protected Audience non ha adottato questo modello di proxy. Stiamo allineando le API JavaScript per PARAKEET e Protected Audience, in vista di un lavoro futuro volto a combinare ulteriormente le migliori funzionalità di entrambe le proposte.

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.

Quali configurazioni del browser sono disponibili?

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 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 stesse, le impostazioni utente possono evolversi in base al feedback di utenti, regolatori e altri.

Continueremo ad aggiornare le impostazioni disponibili in Chrome man mano che la proposta Protected Audience avanza, 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 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.



Coinvolgere e condividere feedback

Assistenza

Per fare una domanda 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. * Apri un nuovo problema all'indirizzo crbug.com/new.

Ricevi aggiornamenti

Scopri di più

Foto di Ray Hennessy su Unsplash.