Guida per gli sviluppatori dell'API FLEDGE

A chi è rivolto questo articolo?

Questo post contiene 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 gestire casi d'uso di remarketing e segmenti di pubblico personalizzati, progettata in modo da non essere utilizzata da terze parti per monitorare il comportamento di navigazione degli utenti su più siti. L'API consente alle aste on-device dal browser di scegliere annunci pertinenti per i siti web che l'utente ha precedentemente visitato.

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

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

Illustrazione che offre 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 per il deployment di base di Protected Audience sui siti di inserzionisti e publisher è disponibile all'indirizzo protect-audience-demo.web.app.

Il video dimostrativo 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 desktop per le API Protected Audience, Topics e Attribution Reporting.

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

Dopo esserti registrato 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 partecipare a uno o più gruppi di interesse e poi di eseguire un'asta dell'annuncio per selezionare e mostrare un annuncio.

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

Fornisci un token della 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 a navigator.joinAdInterestGroup() da parte di un proprietario di gruppo di interesse, dovrà fornire un token corrispondente alla sua origine.

Nella sezione Dettagli della prova dell'origine del primo pubblico protetto proposta vengono forniti ulteriori dettagli sugli obiettivi della prima prova e vengono spiegate le funzionalità supportate.

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

Puoi testare Protected Audience per un singolo utente in Chrome Beta 101.0.4951.26 e versioni successive su computer: * Attivando chrome://flags/#privacy-sandbox-ads-apis. * Impostando i flag dalla riga di comando.

Visualizzare gli annunci in iframe o frame protetti

Gli annunci possono essere visualizzati in <iframe> o <fencedframe>, a seconda dei flag impostati.

Per utilizzare <fencedframe> per il rendering degli annunci:

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

Per utilizzare <iframe> per il rendering degli annunci:

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

Includi il flag BiddingAndScoringDebugReportingAPI per attivare i metodi di generazione di report perdita di debug/win temporaneo.

L'opzione Esegui Chromium con flag spiega come impostare i flag durante l'esecuzione di Chrome e altri browser basati su Chromium dalla riga di comando. L'elenco completo dei flag di Protected Audience è disponibile nella Ricerca Codice Chromium.

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

Protected Audience verrà resa disponibile dietro i flag delle funzionalità in Chromium come primo esperimento per testare le seguenti funzionalità della proposta Protected Audience:

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

Il messaggio esplicativo dell'API fornisce ulteriori dettagli sul supporto e sui vincoli delle funzionalità.

Autorizzazioni gruppo di interesse

L'impostazione predefinita nell'attuale implementazione di Protected Audience è 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 relative alle autorizzazioni per gli iframe interdominio, il piano prevede di non consentire le chiamate dagli iframe interdominio, come descritto nel testo esplicativo.

Servizio chiavi/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 dell'annuncio, come il budget della campagna rimanente. La proposta Protected Audience prevede che questo server "non esegua il logging a livello di evento e non abbia altri effetti collaterali basati su queste richieste".

Il codice del servizio chiave/valore di Protected Audience è 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 dell'annuncio per informazioni sull'aggiornamento dello stato. Scopri di più sul servizio chiave/valore Protected Audience nel messaggio esplicativo dell'API e nella spiegazione del modello di attendibilità.

Per i test iniziali, viene utilizzato il modello "Bring Your Own Server". A lungo termine, le tecnologie pubblicitarie dovranno utilizzare i servizi chiave/valore del pubblico protetto open source in esecuzione in ambienti di esecuzione attendibili per recuperare dati in tempo reale.

Per garantire che l'ecosistema abbia tempo sufficiente per eseguire i test, non prevediamo di richiedere l'utilizzo di servizi chiave/valore open source o TEE fino a qualche tempo dopo il ritiro dei cookie di terze parti. Informeremo gli sviluppatori in modo sostanziale all'inizio dei test e dell'adozione prima che la transizione abbia luogo.

Supporto delle funzionalità di rilevamento

Prima di utilizzare l'API, verifica 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 come proprietario del sito o come singolo utente.

In che modo i siti possono controllare l'accesso?

Protected Audience richiederà ai siti di impostare un criterio di autorizzazione per consentire la disponibilità della funzionalità Protected Audience. Ciò contribuirà a garantire che terze parti arbitrarie non possano utilizzare l'API senza che il sito sia a conoscenza. Tuttavia, per facilitare i test durante la prima prova dell'origine, questo requisito è rilasciato per impostazione predefinita. I siti che vogliono disattivare esplicitamente la funzionalità Protected Audience durante il periodo di test possono utilizzare il criterio relativo alle autorizzazioni pertinente per bloccare l'accesso.

Esistono due criteri relativi alle autorizzazioni Protected Audience che possono essere impostati separatamente: * 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 disabilitato completamente nei 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 Criterio di autorizzazione della 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. È accessibile anche da 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.
  • Usare la modalità di navigazione in incognito.

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

Eseguire il debug dei worklet di Protected Audience

A partire da Chrome Canary 98.0.4718.0, è possibile eseguire il debug dei worklet di Protected Audience in 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, in cui è evidenziato il riquadro Punti di interruzione listener di eventi nel riquadro Origini. L&#39;inizio della fase di offerta dell&#39;offerente è selezionato nel 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 di worklet. Puoi utilizzare punti di interruzione o comandi di passaggio regolari per accedere alla funzione di offerta/scoring/report in sé.

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

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

Poiché alcuni worklet possono essere eseguiti in parallelo, più thread potrebbero restare nello stato "in pausa"; puoi utilizzare l'elenco di thread per passare da un thread all'altro e riprendere o ispezionarli più da vicino nel modo opportuno.

Osservare gli eventi di Protected Audience

Nel riquadro Applicazione in Chrome DevTools puoi osservare gli eventi delle aste e del gruppo di interesse di Protected Audience.

Se visiti il sito di shopping dimostrativo 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 le informazioni sull&#39;evento di partecipazione a un gruppo di interesse di Protected Audience.

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

Il riquadro dell&#39;applicazione DevTools in Chrome Canary, che mostra informazioni sull&#39;offerta per l&#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, poi 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 visiti la 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 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 di gruppi di cui il browser è membro. In questo esempio, il gruppo è denominato custom-bikes e il proprietario è dsp.example. Il proprietario del gruppo di interesse (in questo caso, la DSP) sarà un acquirente nell'asta dell'annuncio descritta nel passaggio 4. L'appartenenza al gruppo di interesse viene memorizzata dal browser sul dispositivo dell'utente e non viene condivisa con il fornitore del browser o con nessun altro.

joinAdInterestGroup() richiede l'autorizzazione a: * Il sito visitato * Il 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 dal 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 di intestazione del criterio di autorizzazione join-ad-interest-group Protected Audience per disattivare le joinAdInterestGroup() chiamate.

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 di autorizzazione che consente le chiamate a joinAdInterestGroup() da iframe multiorigine.

Autorizzazione del 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, 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 iframe nel dominio del proprietario o delegata ad altri domini forniti utilizzando un elenco a 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);

Le dimensioni dell'oggetto interestGroup passato alla funzione non devono superare i 50 kiB, altrimenti la chiamata avrà esito negativo. 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à gruppo 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** Facoltativa* 'https://dsp.example/bid/custom-bikes/bid.js' URL per l'esecuzione di JavaScript per le offerte nel worklet.
biddingWasmHelperUrl** Facoltativa* '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 JSON per aggiornare gli attributi dei gruppi di interesse. Consulta la sezione Aggiornare il gruppo di interesse.
trustedBiddingSignalsUrl** Facoltativo 'https://dsp.example/trusted/bidding-signals' URL di base per le richieste di coppie chiave-valore 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 Facoltativa* [bikeAd1, bikeAd2, bikeAd3] Annunci che potrebbero essere visualizzati per questo gruppo di interesse.
adComponents Facoltativo [customBike1, customBike2, bikePedal, bikeFrame1, bikeFrame2] Componenti per gli annunci composti da più parti.

* Tutte le proprietà sono facoltative, tranne owner e name. Le proprietà biddingLogicUrl e ads sono facoltative, ma obbligatorie per partecipare a un'asta. Potrebbero esserci casi d'uso per creare un gruppo di interesse senza queste proprietà. Ad esempio, il proprietario di un gruppo di interesse potrebbe aggiungere un browser a un gruppo di interesse per una campagna non ancora pubblicata o per altri utilizzi futuri 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 un file 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 può aggiornare periodicamente gli attributi del gruppo di interesse. Nell'implementazione attuale, possono essere modificati i seguenti attributi:

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

I campi non specificati nel JSON non verranno sovrascritti (solo i campi specificati nel JSON verranno aggiornati), mentre la chiamata a navigator.joinAdInterestGroup() sovrascriverà qualsiasi gruppo di interesse esistente.

Gli aggiornamenti vengono eseguiti secondo il criterio del "best effort" e possono non riuscire se si verificano le seguenti condizioni: * Timeout della richiesta di rete (attualmente pari a 30 secondi). * Altri errori di rete. * Errore di analisi JSON.

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

Aggiornamenti manuali

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

Aggiornamenti automatici

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

Specifica gli annunci per un gruppo di interesse

Gli oggetti ads e adComponents includono un URL per una creatività dell'annuncio e, facoltativamente, metadati arbitrari che possono essere utilizzati al momento dell'offerta. Ad esempio:

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

In che modo gli acquirenti fanno le offerte?

Lo script su biddingLogicUrl fornito dal proprietario di un gruppo di interesse deve includere una funzione generateBid(). Quando un venditore di uno spazio pubblicitario chiama navigator.runAdAuction(), la funzione generatedBid() viene richiamata una volta per ogni gruppo di interesse di cui il browser è membro, 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 nel parametro di configurazione dell'asta trasmesso a navigator.runAdAuction(). Il codice di questo URL deve includere una funzione scoreAd(), che viene eseguita 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 dello spazio pubblicitario deve includere una funzione generateBid(). Questa funzione viene richiamata una volta per ogni annuncio candidato. runAdAuction() controlla singolarmente ogni annuncio, insieme all'offerta e ai metadati associati, poi 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 trasmesso a joinAdInterestGroup() dall'acquirente dell'annuncio. Il gruppo basato sugli interessi può essere aggiornato tramite dailyUpdateUrl.

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

  • perBuyerSignals
    Come per auctionSignals, una proprietà dell'argomento configurazione dell'asta trasmessa a navigator.runAdAuction() dal venditore. Ciò può fornire indicatori contestuali sulla pagina dal server dell'acquirente, se il venditore è un'SSP che esegue una chiamata per le offerte in tempo reale ai server dell'acquirente e inoltra la risposta, oppure se la pagina del publisher contatta direttamente il server dell'acquirente. In tal caso, l'acquirente potrebbe voler controllare una firma crittografica di tali indicatori all'interno di generateBid() come protezione contro le manomissioni.

  • trustedBiddingSignals
    Un oggetto le cui chiavi sono 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 altrimenti il venditore potrebbe falsificare) e dati relativi al gruppo di interesse stesso (ad esempio una registrazione della data in cui il gruppo ha vinto in precedenza un'asta, per consentire la quota limite 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 creatività dell'annuncio. Il venditore](/privacy-sandbox/resources/glossary#ssp) utilizza queste informazioni nell'asta e nella creatività dell'annuncio decisionale. Il venditore utilizza queste informazioni nell'asta e nella logica decisionale.

  • bid
    Un'offerta numerica che parteciperà all'asta. Il venditore deve essere in grado di confrontare le offerte di diversi acquirenti, pertanto le offerte devono essere in alcune unità scelte dal venditore, ad esempio "USD per mille". Se l'offerta è pari a zero o negativa, questo gruppo di interesse non parteciperà affatto all'asta del venditore. Con questo meccanismo, l'acquirente può implementare qualsiasi regola per gli inserzionisti in base alla posizione in cui i suoi annunci possono o meno essere pubblicati.

  • render
    Un URL o un elenco di URL, che verranno utilizzati per visualizzare la creatività se l'offerta vince l'asta. (Vedi Annunci composti da più parti nel messaggio esplicativo dell'API.) Il valore deve corrispondere al valore renderUrl di uno degli annunci definiti per il gruppo di interesse.

  • adComponents
    Un elenco facoltativo di massimo 20 componenti per gli annunci composti da più parti, ricavato 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 di interesse dall'elenco dei gruppi di interesse 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 la rimozione del gruppo da parte del browser. 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 proprio laptop. Il sito ha un&#39;area annuncio vuota.

Successivamente, l'utente visita un sito che vende uno spazio pubblicitario, in questo esempio un sito web di notizie. Il sito dispone dell'inventario pubblicitario, che vende in modo programmatico utilizzando le offerte in tempo reale.

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

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

Sezione esplicativa: I venditori eseguono aste on-device

È probabile che l'asta dell'annuncio sia 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 tiene conto dei gruppi di interesse di cui è membro il browser, oltre ai dati provenienti dagli acquirenti di spazi pubblicitari e dai venditori dei servizi chiave/valore.

Il venditore dello spazio pubblicitario invia una richiesta al browser dell'utente per iniziare 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 un URN (urn:uuid:<something>) che rappresenta il risultato dell'asta dell'annuncio. Questo 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 prende in considerazione uno alla volta ogni singolo annuncio, l'offerta e i metadati associati, e assegna a quest'ultimo 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 del 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 un'offerta nell'asta.
auctionSignals Facoltativo {...} Informazioni sul venditore sul contesto della pagina, sul tipo di asta e così via.
sellerSignals Facoltativo {...} Informazioni basate sulle impostazioni del publisher, 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 Runtime massimo (ms) degli script generateBid() di un acquirente specifico.
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 basati sugli interessi 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 rivedere le creatività degli annunci per verificare che rispettino le proprie norme.

** additionalBids non è supportato nell'attuale implementazione di Protected Audience. Per ulteriori informazioni, leggi la sezione Partecipanti all'asta nel messaggio esplicativo 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(). Questo viene eseguito 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 in merito all'annuncio. * browserSignals
Un oggetto creato dal browser, incluse le informazioni note al browser e che potrebbero essere verificate dallo script di asta del venditore:

{
  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 che inizi un'asta, il venditore trova il miglior annuncio contestuale per l'area annuncio disponibile. Parte della sua logica scoreAd() consiste nel rifiutare gli annunci che non possono battere l'elemento vincente contestuale.

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

Illustrazione che mostra una persona che visualizza un sito web di notizie in un browser sul proprio laptop. È in corso un&#39;asta dell&#39;annuncio che utilizza l&#39;API Protected Audience e un partecipante ottiene i dati dal servizio chiavi/valore.

Sezione esplicativa: Recupero dei dati in tempo reale dal servizio chiavi/valori protetti di Audience.

Durante un'asta dell'annuncio, il venditore dello spazio pubblicitario può ottenere dati in tempo reale su creatività pubblicitarie specifiche inviando una richiesta a un servizio chiave/valore utilizzando la proprietà trustedScoringSignalsUrl dell'argomento configurazione dell'asta passata a navigator.runAdAuction(), insieme alle chiavi delle proprietà renderUrl di tutte le voci nei campi ads e adComponents di tutti i gruppi di interesse dell'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 del gruppo di interesse passato a navigator.joinAdInterestGroup().

Quando viene chiamato runAdAuction(), il browser invia una richiesta al server attendibile di ogni acquirente dell'annuncio. L'URL della richiesta potrebbe avere il seguente aspetto:

https://kv-service.example/getvalues?hostname=publisher.example&keys=key1,key2
  • L'URL di base proviene da trustedBiddingSignalsUrl.
  • Il parametro hostname viene fornito dal browser.
  • Il valore keys proviene da trustedBiddingSignalsKeys.

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

6. Viene mostrato l'annuncio vincente

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

Sezione esplicativa: i browser visualizzano l'annuncio vincente

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

7. Il risultato dell'asta viene segnalato

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

Risultato delle segnalazioni venditore

Sezione esplicativa: Report dei venditori sul rendering

Il codice JavaScript del venditore fornito su 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 sullo strumento di offerta vincente

Sezione esplicativa: Report degli acquirenti su rendering ed eventi relativi agli 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 dei report su perdita/successo temporanea

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

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

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

Chrome invia report su perdita/successo del debug solo quando un'asta viene completata 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 se chrome://flags/#privacy-sandbox-ads-apis è abilitato. Tuttavia, se esegui Chrome con flag della riga di comando per abilitare Protected Audience, dovrai abilitare i metodi in modo esplicito includendo il flag BiddingAndScoringDebugReportingAPI. Se il flag non è abilitato, i metodi saranno comunque disponibili, ma non eseguono alcuna operazione.

8. Viene registrato un clic sull'annuncio

Illustrazione che mostra una persona che fa clic su un annuncio per una bicicletta, all&#39;interno di un telaio recintato, su un sito web di notizie, con i dati di un report inviati al venditore e agli 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 con frame fecondati.


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

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


Qual è la differenza tra Protected Audience e TURTLEDOVE?

Protected Audience è il primo esperimento a essere 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 ha funzionato riconoscendo una persona specifica mentre naviga su siti web, un problema fondamentale della privacy del web odierno.

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

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

Protected Audience è cresciuta a partire da TURTLEDOVE e da una raccolta di proposte di modifica correlate per servire meglio gli sviluppatori che avrebbero usato l'API:

  • In SPARROW: Criteo ha proposto l'aggiunta di un modello di servizio ("Gatekeeper") in esecuzione in un Trusted Execution Environment (TEE). Protected Audience include un uso più limitato dei TEE per la ricerca di dati in tempo reale e la generazione di report aggregati.
  • Le proposte TERN e PARRROT di NextRoll hanno descritto i diversi ruoli di acquirenti e venditori nell'asta on-device. Il flusso di offerta/punteggio di Protected Audience per gli annunci si basa su questo lavoro.
  • Le modifiche alla TURTLEDOVE basate sui risultati e a livello di prodotto di RTB House hanno migliorato il modello di anonimato e le capacità di personalizzazione dell'asta on-device
  • PARAKEET è la proposta di Microsoft per un servizio pubblicitario simile a TURTLEDOVE che si basa su un server proxy eseguito in un TEE tra il browser e i fornitori di tecnologia pubblicitaria per anonimizzare le richieste di annunci e applicare le proprietà di privacy. Protected Audience non ha adottato questo modello di proxy. Stiamo allineando le API JavaScript per PARAKEET e Protected Audience a supporto del lavoro futuro 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 un utente. Prevediamo di modificare l'API per renderla più privata nel corso del 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 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 visitati. Come per le tecnologie Privacy Sandbox, le impostazioni utente possono evolvere in base al feedback di utenti, enti regolatori e altri.

Continueremo ad aggiornare le impostazioni disponibili in Chrome con l'avanzamento della proposta Protected Audience, in base a test e feedback. In futuro, prevediamo di offrire impostazioni più granulari per gestire Protected Audience e i dati associati.

I chiamanti API non possono accedere all'appartenenza ai gruppi quando gli utenti navigano in modalità di navigazione in incognito e l'appartenenza viene rimossa quando gli utenti cancellano i dati dei loro siti.



Interagisci e condividi feedback

Assistenza

Per porre una domanda sulla tua implementazione, sulla demo o sulla documentazione: * Apri un nuovo problema nel repository privacy-sandbox-dev-support. Assicurati di selezionare il modello di problema per Protected Audience. * Solleva un problema sul repository del codice demo su GitHub. * Per domande più generali su come soddisfare i tuoi casi d'uso con l'API, segnala un problema nel repository delle proposte.

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.