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 casi d'uso di remarketing e di segmenti di pubblico personalizzati, concepiti in modo da non poter essere utilizzati per monitorare il comportamento di navigazione degli utenti tra i siti. L'API attiva le aste on-device browser, per scegliere annunci pertinenti per i siti web visitati in precedenza dall'utente.

Protected Audience è il primo esperimento implementato in Chromium all'interno del 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 protected-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 eseguita una prova dell'origine di pertinenza e misurazione di Privacy Sandbox reso disponibile in Chrome Beta 101.0.4951.26 e versioni successive su computer per Protected Audience. Topics e API Attribution Reporting.

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

Dopo aver effettuato la registrazione alla prova, puoi provare l'API Protected Audience JavaScript nelle pagine che forniscono un token di prova valido, ad esempio per chiedere al browser di iscriversi a uno o più gruppi basati sugli interessi e poi eseguire un'asta dell'annuncio per selezionare e pubblicare 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 codice Protected Audience, ad esempio navigator.joinAdInterestGroup() chiamata da un proprietario di un gruppo di interesse, dovrà fornire un token corrispondente alla sua origine.

Informazioni proposte sulla prima prova dell'origine del pubblico protetto Fornisce ulteriori 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.

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

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

La funzionalità Protected Audience verrà resa disponibile inizialmente in Chromium dietro le segnalazioni di funzionalità per testare le seguenti funzionalità della proposta Protected Audience:

  • Gruppi di interesse: memorizzati dal browser, con metadati associati per configurare le offerte pubblicitarie e il rendering.
  • Offerte on-device dagli acquirenti (DSP o inserzionista): in base a gruppi di interesse e indicatori memorizzati dal venditore.
  • Selezione degli annunci sul dispositivo da parte del venditore (SSP o publisher): in base alle offerte dell'asta e metadati dagli acquirenti.
  • Rendering dell'annuncio in una versione temporaneamente rilassata dei frame recintati: con accesso alla rete e di accesso consentito per il rendering degli annunci.

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

Autorizzazioni per i gruppi di interesse

L'impostazione predefinita nell'attuale implementazione di Protected Audience è consentire la chiamata a joinAdInterestGroup() da in qualsiasi punto della pagina, anche dagli iframe interdominio. In futuro, una volta che i proprietari dei siti avranno avuto tempo regolare le norme sulle autorizzazioni degli iframe interdominio, il piano prevede di non consentire le chiamate iframe interdominio, come descritto in 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, come le budget della campagna. La proposta Protected Audience prescrive che questo server "non esegua log a livello di evento e non abbia altri effetti collaterali basati su questi 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 rendere disponibile la funzionalità Protected Audience. In questo modo, avrai la certezza che terze parti arbitrarie non possano utilizzare l'API senza il conoscenze. Tuttavia, per facilitare i test durante la prima prova dell'origine, questo requisito è esclusa per impostazione predefinita. I siti che vorrebbero disattivare esplicitamente la funzionalità Protected Audience durante il periodo di test possono utilizzare i criteri relativi alle autorizzazioni 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 quanto segue criterio relativo alle autorizzazioni 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 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 una delle i 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" da 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 con l&#39;evidenziazione del 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 si attiva un punto di interruzione, l'esecuzione viene messa in pausa prima della prima istruzione al livello superiore dell'istruzione script di worklet. Puoi utilizzare punti di interruzione regolari o comandi di passaggio per accedere a offerte, punteggi e report della funzione stessa.

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

Screenshot di DevTools in Chrome Canary con l&#39;evidenziazione del riquadro Thread nel riquadro Origini, che mostra lo stato attuale script di worklet che è stato messo in pausa.

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

Osservare gli eventi Protected Audience

Nel riquadro Applicazione in Chrome DevTools puoi osservare l'asta e il gruppo di interesse di Protected Audience eventi.

Se visiti il sito di shopping dimostrativo di Protected Audience. In un browser con Protected Audience abilitata, DevTools mostrerà le informazioni sull'evento join.

La Riquadro Applicazione DevTools in Chrome Canary che mostra informazioni su un gruppo di interesse Protected Audience partecipa all&#39;evento.

Ora, se visiti il sito della demo di Protected Audience per i publisher. In un browser con Protected Audience è attivato, DevTools mostra le informazioni sugli eventi bid e win.

La Riquadro dell&#39;applicazione DevTools in Chrome Canary che mostra informazioni sull&#39;offerta dell&#39;asta Protected Audience e vincere eventi.

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 viene mostrato 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 su un laptop.

Immagina che un utente visiti il sito web di un produttore di biciclette personalizzate (l'inserzionista in questo esempio) e trascorre del tempo sulla pagina del prodotto di una bicicletta in acciaio fatta a mano. Ciò fornisce produttore di biciclette con 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. JavaScript il codice joinAdInterestGroup() sia in esecuzione nel browser.

Sezione esplicativa: I browser registrano i gruppi di interesse

La Demand-Side Platform (DSP) dell'inserzionista (o l'inserzionista stessa) chiama navigator.joinAdInterestGroup() per chiedere al browser di aggiungere un gruppo basato sugli interessi 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 basato sugli interessi (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 chiunque altro.

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 è concessa implicitamente per le chiamate joinAdInterestGroup() da la stessa origine del sito visitato, ossia dalla stessa origine del frame di primo livello del pagina corrente. I siti possono utilizzare un'intestazione dei criteri relativi alle autorizzazioni di Protected Audience join-ad-interest-group per disattivare le chiamate joinAdInterestGroup().

Cross origin: chiamata a joinAdInterestGroup() da origini diverse da quella attuale può avere esito positivo solo se il sito visitato ha impostato un criterio di autorizzazione che consente le chiamate a joinAdInterestGroup() da iframe multiorigine.

Autorizzazione dal proprietario del gruppo di interesse

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

La proposta prevede che joinAdInterestGroup() possa essere eseguito in una pagina o iframe nel dominio del proprietario oppure essere delegati ad altri domini forniti utilizzando un elenco 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 il valore 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. biddingLogicUrl e ads sono facoltative, ma obbligatorie per partecipare a un'asta. Potrebbero esserci casi d'uso per creando un gruppo di interesse senza queste proprietà: ad esempio, il proprietario di un gruppo di interesse potrebbe Vuoi aggiungere un browser a un gruppo basato sugli interessi per una campagna non ancora pubblicata o per alcune per altri utilizzi futuri oppure potrebbero 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(). Questo offre al proprietario del gruppo un meccanismo per aggiornare periodicamente gli attributi del gruppo basato sugli interessi. Nell'implementazione attuale, è possibile modificare i seguenti attributi:

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

Tutti i campi non specificati nel file JSON non verranno sovrascritti: solo i campi specificati nel file JSON vengono recuperati aggiornato, mentre la chiamata a navigator.joinAdInterestGroup() sovrascrive qualsiasi gruppo basato sugli interessi 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, sebbene non impone alcuna limitazione di frequenza per gli aggiornamenti annullati (rimanenti). La frequenza degli aggiornamenti è limitata a un al massimo uno al giorno. Gli aggiornamenti non riusciti a causa di errori di rete vengono ritentati dopo un'ora. gli aggiornamenti che non riescono a causa della disconnessione da internet vengono ritentati 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 eseguiti troppo spesso: le chiamate ripetute a navigator.updateAdInterestGroups() non fanno nulla fino al limite di frequenza (attualmente un giorno). Il limite di frequenza viene reimpostato se navigator.joinAdInterestGroup() viene richiamata di nuovo 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 basato sugli interessi che partecipano a un'asta, è come se navigator.updateAdInterestGroups() venisse chiamato 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, una metadati utilizzabili al momento dell'asta. 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 un generateBid() personalizzata. Quando un venditore di spazio pubblicitario chiama navigator.runAdAuction(), il generatedBid() viene chiamata una volta per ogni gruppo di interesse di cui il browser fa parte, se il proprietario del gruppo è invitato a fare offerte. In altre parole, generateBid() viene chiamato una volta per ogni candidato annuncio. Il venditore fornisce una proprietà decisionLogicUrl sul parametro di configurazione dell'asta trasmesso a navigator.runAdAuction(). Il codice a questo URL deve includere una funzione scoreAd(), che è verranno pubblicati per ogni offerente nell'asta, in modo da 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, poi assegna all'annuncio una il punteggio di desiderabilità numerica.

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 potrebbe essere aggiornata 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 (ad esempio, la dimensione dell'annuncio e l'ID publisher), il tipo di asta (primo prezzo o secondo prezzo) e altri metadati.

  • perBuyerSignals
    Come per auctionSignals, una proprietà della configurazione dell'asta passato a navigator.runAdAuction() dal venditore. Questo può fornire informazioni indicatori dal server dell'acquirente in merito alla pagina, se il venditore è una SSP che effettua una chiamata di offerta in tempo reale ai server dell'acquirente e restituisce la risposta oppure se il publisher contatta direttamente il server dell'acquirente. In tal caso, l'acquirente potrebbe voler controllare una crittografia di questi indicatori all'interno di generateBid() come protezione contro le manomissioni.

  • trustedBiddingSignals
    Un oggetto le cui chiavi sono le trustedBiddingSignalsKeys per gruppo basato sugli interessi e i cui valori vengono restituiti nella richiesta trustedBiddingSignals.

  • browserSignals
    Un oggetto costruito dal browser, che potrebbe includere informazioni sulla pagina contesto (come hostname della pagina corrente, che il venditore potrebbe altrimenti falsificare) e dati per il gruppo di interesse stesso (ad esempio una registrazione 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à della funzione parametri. 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 creatività dell'annuncio. Il venditore](/privacy-sandbox/resources/glossario#ssp) utilizza queste informazioni nella propria asta e nella propria decisione creatività dell'annuncio. Il venditore utilizza queste informazioni nella propria asta e nella propria decisione logica.

  • bid
    Un'offerta numerica che parteciperà all'asta. Il venditore deve essere in grado di fare un confronto 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 basato sugli interessi non parteciperà al dell'asta del venditore. Con questo meccanismo, l'acquirente può implementare qualsiasi regola dell'inserzionista per la posizione i loro annunci possono essere o meno pubblicati.

  • render
    Un URL o un elenco di URL che verrà utilizzato per mostrare la creatività se l'offerta vince l'asta. Vedi Annunci composti da più parti. nel messaggio esplicativo dell'API. Il valore deve corrispondere a renderUrl di uno dei 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 di quelli di cui fa parte.

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

Se un utente torna sul sito e ha chiesto al browser di aggiungere un gruppo basato sugli interessi, il proprietario del gruppo basato sugli interessi 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 inventario pubblicitario, che vende in modo programmatico utilizzando 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. Annuncio utilizzando 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 oppure l'editore stesso. Lo scopo dell'asta è selezionare l'annuncio più appropriato per un singolo area annuncio disponibile sulla pagina corrente. L'asta prende in considerazione i gruppi di interesse del browser, insieme ai dati degli acquirenti dello spazio pubblicitario e dei venditori dei servizi chiave/valore.

Il venditore dello spazio pubblicitario invia al browser dell'utente una richiesta di inizio di un'asta dell'annuncio 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 una URN (urn:uuid:<something>) che rappresenta la dell'asta dell'annuncio. Può essere decodificato dal browser solo quando viene passata a un frame recintato. per il rendering: la pagina del publisher non può esaminare l'annuncio vincente.

Lo script decisionLogicUrl prende in considerazione ogni singolo annuncio, insieme all'offerta associata metadati, uno alla volta, quindi assegna loro 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. Leggi l'asta Partecipanti del Per saperne di più, consulta il messaggio esplicativo 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 per determinarne l'appetibilità.

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 le informazioni che quest'ultimo e quale 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 di la sua logica scoreAd() consiste nel rifiutare qualsiasi annuncio in cui non sia possibile 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. Annuncio utilizzando l&#39;API Protected Audience. Un partecipante riceve i 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 creatività specifiche. una richiesta a un servizio chiave/valore utilizzando la proprietà trustedScoringSignalsUrl Argomento configurazione dell'asta passato a navigator.runAdAuction(), insieme alle chiavi dalle proprietà renderUrl di tutte le voci nei campi ads e adComponents di tutte gruppi basati sugli interessi nell'asta.

Allo stesso modo, un acquirente dello spazio pubblicitario può richiedere dati in tempo reale al servizio chiave/valore utilizzando il metodo 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. La 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 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. Annuncio per una bicicletta (20% di sconto), con un lucchetto sopra che indica che l&#39;annuncio è 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 viene visualizzato 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ò includono 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 e
    Un oggetto costruito 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 l'offerente vincente Funzione reportWin().

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 un 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 reportResult(), che offre al venditore una l'opportunità di passare informazioni all'acquirente.

  • browserSignals
    Un oggetto costruito 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 richiamato 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 si tratta di un'asta annullati (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: abilitare esplicitamente i metodi includendo il flag BiddingAndScoringDebugReportingAPI. Se non è abilitato, i metodi saranno ancora disponibili, ma non eseguono alcuna operazione.

8. Viene registrato un clic sull'annuncio

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

Viene segnalato un clic su un annuncio visualizzato in un frame recintato. Per ulteriori informazioni su come potrebbe funzionare, consulta la sezione Report sugli annunci 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 su ciò che l'inserzionista pensa come di tuo interesse.
  • Gli inserzionisti possono pubblicare annunci in base a un interesse, ma non possono combinarlo con altri informazioni su una persona, in particolare la sua identità 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 una ("Gatekeeper") in esecuzione in un Trusted Execution Environment (TEE). Protected Audience comprende un uso più limitato dei TEE, per la ricerca di dati in tempo reale e la generazione di report aggregati.
  • TERN di NextRoll e Magnite PARROTTO proposte descriveva i diversi ruoli di acquirenti e venditori nell'asta on-device. Il flusso di offerte/punteggio di Protected Audience si basa su questo lavoro.
  • Le metriche basate sui risultati e TURTLEDOVE a livello di prodotto le modifiche 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 far rispettare la privacy proprietà. Protected Audience non ha adottato questo modello di proxy. Stiamo introducendo le API JavaScript per PARAKEET e Protected Audience in allineamento, a sostegno dei lavori futuri volti a combinare ulteriormente i le caratteristiche 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 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 puoi 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 sul web siti visitati. Come per le tecnologie Privacy Sandbox stesse, le impostazioni utente possono a evolversi con il 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 su 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 rimossi quando gli utenti cancellano i dati dei loro siti.



Interagisci e condividi il feedback

Assistenza

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

Per bug e problemi relativi all'implementazione dell'API Protected Audience in Chrome: * Visualizzare 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.