Per aiutare gli sviluppatori a iniziare a sperimentare con l'API Protected App Signals, Questo documento descrive tutte le API all'interno della piattaforma API, descrive nel dettaglio come impostare un ambiente di test e fornire esempi della configurazione e script.
Cronologia delle versioni
Gennaio 2024
Prima versione della guida per gli sviluppatori che supporta la release PAS MVP
Marzo 2024
Modifiche all'API per supportare la release M-2024-05 dell'API Android e Release di aprile 2024 dei componenti lato server. Modifiche più importanti:
- Sono stati aggiunti dettagli sulle autorizzazioni richieste per l'API on-device
- Sono stati aggiunti dettagli sulla gestione della quota di indicatori on-device
- Firma di
generateBidaggiornata con modifiche correlate al contesto il recupero di annunci e il supporto al traffico in uscita - Documentazione aggiornata di
reportWin, incluso il supporto del traffico in uscita - Aggiornamento della documentazione dell'API Ad Retrieval sulla rimozione del supporto per il recupero di annunci BYOS e documentare la funzione definita dall'utente per il recupero di annunci
Panoramica dell'API
La piattaforma dell'API Protected Signals include diversi sottoinsiemi di API su diversi sistemi:
- API Android:
- API Signal Curation, composta da:
- API Update Signals
- API Signals Encoding
- API Protected Asta Support: utilizzata dagli SDK per eseguire l'API su server per le offerte e le aste che utilizzano l'app protetta Indicatori.
- API lato server:
- API Protected Auction: una serie di script JS in esecuzione nell'API Bidding e Server delle aste. Questa API consente a venditori e acquirenti di scrivere la logica per implementare l'asta protetta.
- API Ad Retrieval: responsabile della fornitura di un elenco di annunci candidati le informazioni contestuali e sugli utenti messe a disposizione dell'acquirente o server web.
Client Android
Sul lato client, la sezione Indicatori dell'app protetta è composta da tre API diverse:
- Aggiorna indicatori: un'API Android System per consentire la selezione degli indicatori su del dispositivo.
- Codifica segnali: un'API JavaScript per preparare i segnali da inviare allo server durante l'asta.
- Supporto dell'asta protetta: un'API per supportare l'esecuzione di un'asta protetta Asta sui server delle offerte e delle aste. Questa API non è specifica per Indicatori dell'app Protected e viene utilizzato anche per supportare le aste per il gruppo API Audience.
API Update Signals
L'API Update Signals fornisce ai tecnici pubblicitari la possibilità di registrare utenti e indicatori relativi all'app per conto di un acquirente. L'API funziona sulla base di un modello di delega. Il chiamante fornisce un URI da cui il framework recupera i contenuti corrispondenti e la logica per codificare questi indicatori da utilizzare nell'asta.
L'API richiede l'android.permission.ACCESS_ADSERVICES_PROTECTED_SIGNALS
autorizzazione.
L'API updateSignals() recupererà un oggetto JSON
dall'URI che descrive quali indicatori aggiungere o rimuovere e come prepararsi
questi indicatori per l'asta.
Executor executor = Executors.newCachedThreadPool();
ProtectedSignalsManager protectedSignalsManager
= ProtectedSignalsManager.get(context);
// Initialize a UpdateSignalsRequest
UpdateSignalsRequest updateSignalsRequest = new
UpdateSignalsRequest.Builder(Uri.parse("https://example-adtech1.com/signals"))
.build();
OutcomeReceiver<Object, Exception> outcomeReceiver = new OutcomeReceiver<Object, Exception>() {
@Override
public void onResult(Object o) {
//Post-success actions
}
@Override
public void onError(Exception error) {
//Post-failure actions
};
// Call updateSignals
protectedSignalsManager.updateSignals(updateSignalsRequest,
executor,
outcomeReceiver);
La piattaforma invia una richiesta https all'URI fornito nella richiesta di recupero l'indicatore si aggiorna. Insieme agli aggiornamenti degli indicatori, la risposta può includere una endpoint che ospita la logica di codifica per convertire i segnali non elaborati con codifica del payload. Gli aggiornamenti degli indicatori dovrebbero essere sotto forma di JSON e può avere le seguenti chiavi:
Le chiavi di livello superiore per l'oggetto JSON devono corrispondere a uno dei cinque comandi:
chiave |
Descrizione |
|
Aggiunge un nuovo indicatore, sovrascrivendo quelli esistenti con la stessa chiave. Il valore per questo è un oggetto JSON in cui le chiavi sono stringhe in base 64 corrispondenti alla chiave da inserire e i valori sono stringhe in base 64 corrispondenti al valore da inserire. |
|
Consente di aggiungere nuovi indicatori/indicatori a una serie temporale di indicatori, rimuovendo quelli meno recenti per fare spazio a quelli nuovi se le dimensioni della serie superano il limite massimo stabilito. Il valore è un oggetto JSON in cui le chiavi sono stringhe di base 64 corrispondenti alla chiave da aggiungere e i valori sono oggetti con due campi: "values" e "maxSignals". "values": un elenco di stringhe in base 64 corrispondenti ai valori degli indicatori da aggiungere alla serie temporale. "maxSignals": il numero massimo di valori consentiti in questa serie temporale. Se il numero attuale di indicatori associati alla chiave supera il valore di maxSignals, gli indicatori meno recenti verranno rimossi. Tieni presente che puoi aggiungere elementi a una chiave aggiunta tramite put. Tieni presente che l'aggiunta di un numero di valori superiore a quello massimo comporterà un errore. |
|
Aggiunge un nuovo indicatore solo se non esistono indicatori con la stessa chiave. Il valore è un oggetto JSON in cui le chiavi sono stringhe in base 64 corrispondenti alla chiave da inserire e i valori sono stringhe in base 64 corrispondenti al valore da inserire. |
|
Rimuove il segnale per una chiave. Il valore è un elenco di stringhe in base 64 corrispondenti alle chiavi degli indicatori che devono essere eliminate. |
|
Fornisce un'azione per aggiornare l'endpoint e un URI che può essere utilizzato per recuperare una logica di codifica. La sottochiave per fornire un'azione di aggiornamento è "azione" e ai attualmente supportati è solo "REGISTER" che registrerà l'endpoint del codificatore, se fornito per la prima volta, o sovrascriverà quello esistente con l'endpoint appena fornito. È necessario fornire l'endpoint per il "REGISTER" action.La sottochiave per fornire un endpoint del codificatore è "endpoint" e il valore è l'URI stringa per l'endpoint. |
Una richiesta JSON di esempio potrebbe essere simile alla seguente:
{
"put": {
"AAAAAQ==": "AAAAZQ==",
"AAAAAg==": "AAAAZg=="
},
"append": {
"AAAAAw==": {
"values": [
"AAAAZw=="
],
"max_signals": 3
}
},
"put_if_not_present": {
"AAAABA==": "AAAAaQ==",
"AAAABQ==": "AAAAag=="
},
"update_encoder": {
"action": "REGISTER",
"endpoint": "https://adtech1.com/Protected App Signals_encode_script.js"
}
}
Gli indicatori avranno una quota sul dispositivo nell'ordine di 10-15 kB. Una volta che la quota viene superato, PPAPI rimuoverà gli indicatori utilizzando una strategia FIFO. La procedura di eliminazione consente di superare leggermente la quota per brevi intervalli di tempo in per ridurre la frequenza degli espulsioni.
API Signals Encoding
Gli Acquirenti devono fornire una funzione JavaScript da utilizzare per codificare il i segnali memorizzati sul dispositivo da inviare al server durante Asta. Gli acquirenti possono fornire questo script aggiungendo l'URL dove può essere recuperato dall'utilizzo della chiave "update_encoder" in qualsiasi risposta a un Richiesta API UpdateSignal. Lo script avrà la seguente firma:
function encodeSignals(signals, maxSize) {
let result = new Uint8Array(maxSize);
// first entry will contain the total size
let size = 1;
let keys = 0;
for (const [key, values] of signals.entries()) {
keys++;
// In this encoding we only care about the first byte
console.log("key " + keys + " is " + key)
result[size++] = key[0];
result[size++] = values.length;
for(const value of values) {
result[size++] = value.signal_value[0];
}
}
result[0] = keys;
return { 'status': 0, 'results': result.subarray(0, size)};
}
Il parametro signals è una mappa da chiavi sotto forma di UInt8Array di dimensione 4
a elenchi di oggetti Indicatori di app protetti. Ogni oggetto Indicatori di app protetti ha
tre campi:
signal_value: un UInt8Array che rappresenta il valore dell'indicatore.creation_time: un numero che rappresenta l'ora di creazione degli indicatori in epoche secondi.package_name: una stringa che rappresenta il nome del pacchetto che è stato creato il segnale.
Il parametro maxSize è un numero che descrive la dimensione massima consentita dell'array
per l'output.
La funzione dovrebbe restituire un oggetto con due campi:
status: deve essere 0 se lo script viene eseguito correttamente.results: deve essere un UInt8Array di lunghezza inferiore o uguale a maxSize. Questo array verrà inviato al server durante le aste e preparato ScriptprepareDataForAdRetrieval.
La codifica fornisce agli ad tech una fase iniziale di feature engineering, in cui possono eseguire trasformazioni come la compressione di indicatori non elaborati le versioni concatenate in base alla loro logica personalizzata. Tieni presente che durante Asta protetta in esecuzione nei Trusted Execution Environment (TEE), ad tech la logica personalizzata avrà accesso in lettura ai payload di indicatori generati codifica. La logica personalizzata, nota come Funzione definita dall'utente, eseguita nel TEE B&A dell'acquirente avrà accesso in lettura agli indicatori codificati e ad altri indicatori di contesto forniti dall'app del publisher per eseguire la selezione degli annunci (recupero e offerte).
Codifica degli indicatori
Ogni ora, gli acquirenti che hanno fornito logica di codifica con i loro verranno codificati in un payload dell'asta.I byte per il payload dell'asta è persistente sul dispositivo, è criptato verranno raccolti dai venditori come parte dei dati di selezione degli annunci da includere come parte di un'asta protetta. Per i test, puoi attivare questa codifica al di fuori la sua frequenza oraria eseguendo questo comando:
adb shell cmd jobscheduler run -f com.google.android.adservices.api 29
Controllo delle versioni della logica dell'encoder
Quando viene effettuata una richiesta di download della logica del codificatore personalizzato per la tecnologia ad tech, endpoint può rispondere con un numero di versione nelle intestazioni della risposta. Questa versione sia persistente insieme alla logica dell'encoder sul dispositivo. Quando gli indicatori non elaborati sono codificati, il payload codificato viene mantenuto insieme alla versione utilizzata codifica. Questa versione viene inviata anche al server di B&A durante una sessione in un'asta, in modo che i tecnici pubblicitari possano allineare la logica di offerta e codifica in base la versione.
Response header for providing encoder version : X_ENCODER_VERSION
API di assistenza per le aste protette
Per quanto riguarda i dispositivi, l'esecuzione di un'asta per gli indicatori di app protette è è come eseguire un'asta per segmenti di pubblico protetti.
Servizi di offerte e aste
Le API lato server includono:
- API Protected Asta: una serie di funzioni JS o funzioni definite dall'utente che acquirenti e venditori possono implementare nei componenti B&A di loro proprietà al fine di determinare le offerte e la logica dell'asta.
- API Ad Retrieval: gli acquirenti possono implementare questa API implementando un endpoint REST che sarà responsabile di fornire una serie di annunci candidati per l'asta Protected App Signal.
API Protected Asta
L'API Protected Auction è composta da API JS o funzioni definite dall'utente che acquirenti e venditori possono per implementare la logica di asta e offerta.
UDF ad tech dell'acquirente
Funzione definita dall'utente prepareDataForAdRetrieval
Prima che gli indicatori dell'app protetta possano essere utilizzati per recuperare gli annunci candidati dal TEE
Servizio di recupero degli annunci, gli acquirenti devono decodificare e preparare gli indicatori dell'app protetta
e altri dati forniti dal venditore. L'output della funzione definita dall'utente prepareDataForAdRetrieval degli acquirenti è
passati al servizio di recupero degli annunci
recuperare i primi k annunci candidati per l'asta.
// Inputs
// ------
// encodedOnDeviceSignals: A Uint8Array of bytes from the device.
// encodedOnDeviceSignalsVersion: An integer representing the encoded
// version of the signals.
// sellerAuctionSignals: Information about auction (ad format, size) derived
// contextually.
// contextualSignals: Additional contextual signals that could help in
// generating bids.
//
// Outputs
// -------
// Returns a JSON structure to be used for retrieval.
// The structure of this object is left to the adtech.
function prepareDataForAdRetrieval(encodedOnDeviceSignals,encodedOnDeviceSignalsVersion,sellerAuctionSignals,contextualSignals) {
return {};
}
funzione definita dall'utente generateBid
Una volta restituiti i primi k annunci candidati, questi ultimi vengono passati alla
logica delle offerte personalizzate dell'acquirente, generateBid UDF:
// Inputs
// ------
// ads: Data string returned by the ads retrieval service. This can include Protected App Signals
// ads and related ads metadata.
// sellerAuctionSignals: Information about the auction (ad format, size),
// derived contextually
// buyerSignals: Any additional contextual information provided by the buyer
// preprocessedDataForRetrieval: This is the output of this UDF.
function generateBid(ads, sellerAuctionSignals, buyerSignals,
preprocessedDataForRetrieval,
rawSignals, rawSignalsVersion) {
return { "ad": <ad Value Object>,
"bid": <float>,
"render": <render URL string>,
'adCost': <optional float ad cost>,
"egressPayload": <limitedEgressPayload>,
"temporaryUnlimitedEgressPayload": <temporaryUnlimitedEgressPayload>
};
}
L'output di questa funzione corrisponde a una singola offerta per un candidato di annuncio, rappresentata
come JSON equivalente
ProtectedAppSignalsAdWithBidMetadata
La funzione può anche restituire due array che verranno poi passati a reportWin
per abilitare l'addestramento del modello (per ulteriori dettagli sul traffico in uscita e
consulta la sezione sui report nel messaggio esplicativo PAS)
UDF reportWin
Al termine di un'asta, il servizio genera URL di report per
gli acquirenti e registrare i beacon utilizzando la funzione definita dall'utente reportWin (si tratta della
funzione reportWin utilizzata per i segmenti di pubblico protetti).
Verrà inviato un ping dal dispositivo una volta eseguito il rendering dell'annuncio dal client.
La firma di questo metodo è quasi uguale a quella di Protected Audience
version tranne che per i due parametri aggiuntivi egressPayload e
temporaryUnlimitedEgressPayload utilizzati per abilitare l'addestramento del modello
compilati con i risultati di generateBid.
// Inputs / Outputs
// ----------------
// See detailed documentation here.
function reportWin(auctionSignals, perBuyerSignals, signalsForWinner,
buyerReportingSignals,
egressPayload, temporaryUnlimitedEgressPayload) {
// ...
}
UDF Ad tech del venditore
funzione definita dall'utente
Questa funzione definita dall'utente viene utilizzata dai venditori per selezionare quali annunci hanno ricevuto degli acquirenti vinceranno l'asta.
function scoreAd(adMetadata, bid, auctionConfig,
trustedScoringSignals, bid_metadata) {
// ...
return {desirability: desirabilityScoreForThisAd,
allowComponentAuction: true_or_false};
}
funzione definita dall'utente reportResult
Questa funzione definita dall'utente consente al venditore di (alla fine) eseguire a livello di evento con le informazioni relative all'annuncio vincente.
function reportResult(auctionConfig, reporting_metadata) {
// ...
registerAdBeacon({"click", clickUrl,"view", viewUrl});
sendReportTo(reportResultUrl);
return signalsForWinner;
}
API Ad Retrieval
Nella versione MVP , il servizio di recupero degli annunci sarà gestito dall'acquirente e il servizio di offerte recupera i candidati per gli annunci da questo servizio. A partire da aprile 2024, il server di recupero degli annunci deve essere eseguito in un account Execution Environment (TEE) ed esporrà un'interfaccia GRPC/proto. Ad tech le aziende devono configurare questo server e fornire il relativo URL nell'ambito del B&A e il deployment dello stack. Un'implementazione di questo servizio in esecuzione nel TEE è disponibile nel GitHub Privacy Sandbox e nel resto dei documentazione presupponiamo che questo sia il codice utilizzato nel deployment.
A partire da aprile 2024, le versioni B&A supportano l'annuncio con percorso contestuale recupero. In questo caso, il server delle offerte riceverà un elenco identificatori di annunci inviati dal server RTB durante la parte contestuale dell'asta. Gli identificatori verranno inviati a un server TEE KV per recuperare tutti gli annunci informazioni correlate da utilizzare durante la fase di offerta (ad esempio ad-render-url, metadati e incorporamenti di annunci da utilizzare nella top-k). Questo secondo percorso non richiede una logica specifica del deployment, quindi documenteremo qui solo come configurare il TEE di recupero degli annunci.
Funzione definita dall'utente HandleRequest
function HandleRequest(requestMetadata, preparedDataForAdRetrieval,
deviceMetadata, contextualSignals) {
return adsMetadataString;
}
Dove:
requestMetadata: JSON. Metadati del server per richiesta alla funzione definita dall'utente. Vuoto per il momento.preparedDataForAdRetrieval: il contenuto di questo campo dipende dall'annuncio strategia di recupero. Nel caso di recupero di annunci contestuali , questo parametro conterrà i segnali non elaborati provenienti dal dispositivo e trasmessi dal di offerta. Nel caso del recupero di annunci TEE mediante il server di recupero annunci, questo parametro conterrà il risultato della funzione definita dall'utenteprepareDataForAdRetrieval. Nota: in questa fase gli indicatori delle app protette vengono decodificati e non criptati.deviceMetadata: oggetto JSON contenente metadati del dispositivo inoltrati dal servizio pubblicitario del venditore. Per ulteriori dettagli, consulta la documentazione relativa a B&A.X-Accept-Language: lingua utilizzata sul dispositivo.X-User-Agent: user agent utilizzato sul dispositivo.X-BnA-Client-IP: indirizzo IP del dispositivo.
contextualSignals: stringa arbitraria che ha avuto origine dall'offerta contestuale gestito dallo stesso DSP. La funzione definita dall'utente deve essere in grado di decodificare e la useremo. Gli indicatori di contesto possono contenere qualsiasi informazione, ad esempio ML le informazioni sulla versione del modello per l'incorporamento protetto passate utilizzando Indicatori delle app protette.
Se l'operazione è riuscita, la funzione definita dall'utente dovrebbe restituire una stringa. La stringa viene restituita
server di offerte, che poi lo passa alla funzione definita dall'utente generateBid. Sebbene
stringa può essere solo una stringa semplice, molto probabilmente la stringa dovrebbe essere una
oggetto serializzato il cui schema è definito autonomamente da ciascuna tecnologia pubblicitaria.
Non esiste alcun vincolo allo schema purché l'generateBid dell'ad tech
la logica può riconoscere e utilizzare la stringa.
Configura il sistema per lo sviluppo
Android
Per configurare il tuo ambiente di sviluppo Android, devi effettuare le seguenti operazioni:
- Crea un emulatore (opzione preferita) o un dispositivo fisico su cui è in esecuzione l'immagine dell'Anteprima per gli sviluppatori 10
- Esegui questo comando:
adb shell am start -n com.google.android.adservices.api/com.android.adservices.ui.settings.activities.AdServicesSettingsMainActivity
Poi seleziona l'opzione mostrata per dare il consenso agli annunci suggeriti dalle app.
- Esegui questo comando per abilitare le API pertinenti. Potrebbe essere necessario eseguire di nuovo questa operazione di tanto in tanto, poiché la configurazione predefinita dell'opzione "Disattivata" verrà sincronizzata periodicamente.
adb shell device_config put adservices fledge_custom_audience_service_kill_switch false; adb shell device_config put adservices fledge_select_ads_kill_switch false; adb shell device_config put adservices fledge_on_device_auction_kill_switch false; adb shell device_config put adservices fledge_auction_server_kill_switch false; adb shell "device_config put adservices disable_fledge_enrollment_check true"; adb shell device_config put adservices ppapi_app_allow_list '\*'; adb shell device_config put adservices fledge_auction_server_overall_timeout_ms 60000;
- Riavvia il dispositivo.
- Esegui l'override delle chiavi dell'asta del dispositivo in modo che puntino al server delle chiavi dell'asta. È importante eseguire questo passaggio prima di tentare di eseguire un'asta per evitare che le chiavi errate vengano memorizzate nella cache.
Offerte e Servizi di aste
Per configurare i server B&A, consulta le documentazione relativa alla configurazione self-service.
Questo documento spiega come configurare i server specifici dell'acquirente, non sono previste modifiche per i venditori.
Prerequisiti
Prima di eseguire il deployment di uno stack di servizi B&A, il reparto ad tech dell'acquirente deve:
- Assicurarsi di aver implementato il proprio servizio di recupero degli annunci TEE (consulta il sezione pertinente).
- Assicurati che la tecnologia pubblicitaria disponga di tutte le funzioni definite dall'utente necessarie
(
prepareDataForAdRetrieval,generateBid,reportWineHandleRequest) definiti e ospitati.
Comprendere come funziona l'asta protetta con Protected Audience Anche il B&A sarà utile, ma non è obbligatorio.
Configurazione di Terraform
Per utilizzare gli indicatori di app protetti, i tecnici pubblicitari devono:
- Attiva il supporto degli indicatori di app protetti in B&A.
- Fornisci gli endpoint URL da cui è possibile recuperare le nuove funzioni definite dall'utente per
prepareDataForAdRetrieval, generateBidereportWin.
Inoltre, questa guida presuppone che i tecnici pubblicitari che desiderano utilizzare B&A per remarketing continuerà a impostare tutti i flag di configurazione esistenti per dell'asta di remarketing come di consueto.
Configurazione della tecnologia pubblicitaria dell'acquirente
Usando questo file dimostrativo come esempio, gli acquirenti devono impostare i seguenti flag:
- Attiva indicatori delle app protette: questa opzione è abilitata per raccogliere gli indicatori delle app protette. e i dati di Google Cloud.
- URL degli indicatori delle app protetti: impostati sugli URL degli indicatori delle app protette. server web.
I tecnici pubblicitari devono sostituire gli URL corretti nei segnaposto con i seguenti elementi campi:
module "buyer" {
# ... More config here.
runtime_flags = {
# ... More config here.
ENABLE_PROTECTED_APP_SIGNALS = "true"
PROTECTED_APP_SIGNALS_GENERATE_BID_TIMEOUT_MS = "60000"
TEE_AD_RETRIEVAL_KV_SERVER_ADDR = "<service mesh address of the instance>"
AD_RETRIEVAL_TIMEOUT_MS = "60000"
BUYER_CODE_FETCH_CONFIG = <<EOF
{
"protectedAppSignalsBiddingJsUrl": "<URL to Protected App Signals generateBid UDF>",
"urlFetchTimeoutMs": 60001, # This has to be > 1 minute.
"urlFetchPeriodMs": 13000000,
"prepareDataForAdsRetrievalJsUrl": "<URL to the UDF>"
}
EOF
} # runtime_flags
} # Module "buyer"
Configurazione della tecnologia pubblicitaria del venditore
Utilizzando questo file demo come esempio, i venditori devono impostare il i seguenti flag. Nota: è evidenziata solo la configurazione correlata agli indicatori delle app protette qui). I tecnici pubblicitari devono assicurarsi di sostituire gli URL corretti nel segnaposto:
module "seller" {
# ... More config here.
runtime_flags = {
# ... More config here.
ENABLE_PROTECTED_APP_SIGNALS = "true"
SELLER_CODE_FETCH_CONFIG = <<EOF
{
"urlFetchTimeoutMs": 60001, # This has to be > 1 minute.
"urlFetchPeriodMs": 13000000,
"protectedAppSignalsBuyerReportWinJsUrls": {"<Buyer Domain>": "URL to reportWin UDF"}
}
EOF
} # runtime_flags
} # Module "seller"
Servizi di recupero di valori chiave e annunci
In base alle strategie scelte per supportare il recupero degli annunci, il sistema
richiedono il deployment di una o due istanze del servizio KV. Faremo riferimento
all'istanza KV utilizzata per il recupero di annunci basati su TEE come
Ad Retrieval Server e all'istanza per supportare il supporto contestuale basato su percorso
recupero come KV Lookup Server.
In entrambi i casi il deployment dei server segue la documentazione disponibile nel
GitHub server KV, la differenza tra i due casi è che il sistema di ricerca
è pronta all'uso senza alcuna configurazione aggiuntiva, mentre
il recupero uno richiede il deployment della funzione definita dall'utente HandleRequest per implementare
la logica di recupero. Per ulteriori dettagli, dai un'occhiata al server KV
guida alle operazioni preliminari. Nota che B&A prevede che entrambi i servizi
distribuite all'interno dello stesso mesh di servizi
del servizio di asta.
Configurazione di esempio
Considera il seguente scenario: utilizzo dell'API Protected App Signals, una tecnologia pubblicitaria Archivia indicatori pertinenti in base all'utilizzo dell'app da parte dell'utente. Nel nostro esempio, gli indicatori archiviati che rappresentano acquisti in-app da diverse app. Durante un di un'asta, gli indicatori criptati vengono raccolti e trasferiti in un'asta protetta in esecuzione in B&A. Le funzioni definite dall'acquirente pubblicate in B&A utilizzano gli indicatori per recuperare l'annuncio candidati e calcolano un'offerta.
[Acquirente] Esempi di indicatori
Aggiunge un indicatore con una chiave pari a 0 e un valore pari a 1.
{
"put": {
"AA==": "AQ=="
},
"update_encoder": {
"action": "REGISTER",
"endpoint": "https://example.com/example_script"
}
}
Aggiunge un indicatore con una chiave di 1 e un valore di 2.
{
"put": {
"AQ==": "Ag=="
},
"update_encoder": {
"action": "REGISTER",
"endpoint": "https://example.com/example_script"
}
}
Esempio di codifica di [acquirente]
Codifica ogni segnale in due byte, dove il primo byte è il primo byte la chiave di segnale e il secondo byte è il primo byte del valore del segnale.
function encodeSignals(signals, maxSize) {
// if there are no signals don't write a payload
if (signals.size === 0) {
return {};
}
let result = new Uint8Array(signals.size * 2);
let index = 0;
for (const [key, values] of signals.entries()) {
result[index++] = key[0];
result[index++] = values[0].signal_value[0];
}
return { 'status': 0, 'results': result};
}
[Acquirente] Esempio di prepareDataForAdRetrieval
/**
* `encodedOnDeviceSignals` is a Uint8Array and would contain
* the app signals emanating from device. For purpose of the
* demo, in our sample example, we assume that device is sending
* the signals with pair of bytes formatted as following:
* "<id><In app spending>". Where id corresponds to an ad category
* that user uses on device, and the in app spending is a measure
* of how much money the user has spent in this app category
* previously. In our example, id of 0 will correspond to a
* fitness ad category and a non-zero id will correspond to
* food app category -- though this info will be useful
* later in the B&A pipeline.
*
* Returns a JSON object indicating what type of ad(s) may be
* most relevant to the user. In a real setup ad techs might
* want to decode the signals as part of this script.
*
* Note: This example script makes use of only encoded device signals
* but adtech can take other signals into account as well to prepare
* the data that will be useful down stream for ad retrieval and
* bid generation. The max length of the app signals used in this
* sample example is arbitrarily limited to 4 bytes.
*/
function prepareDataForAdRetrieval(encodedOnDeviceSignals,
encodedOnDeviceSignalsVersion,
sellerAuctionSignals,
contextualSignals) {
if (encodedOnDeviceSignals.length === 0 || encodedOnDeviceSignals.length > 4 ||
encodedOnDeviceSignals.length % 2 !== 0) {
throw "Expected encoded signals length to be an even number in (0, 4]";
}
var preparedDataForAdRetrieval = {};
for (var i = 0; i < encodedOnDeviceSignals.length; i += 2) {
preparedDataForAdRetrieval[encodedOnDeviceSignals[i]] = encodedOnDeviceSignals[i + 1];
}
return preparedDataForAdRetrieval;
}
[Acquirenti] Funzionalità definita dall'utente per il recupero di annunci di esempio
Nel nostro esempio, il server di recupero degli annunci invia i metadati (ovvero l'ID per ogni annuncio in questo esempio, ma può contenere per ognuno altri dati che possono essere utili generando le offerte in un secondo momento) per ciascuno dei primi k candidati di annunci.
function HandleRequest(requestMetadata, protectedSignals, deviceMetadata,
contextualSignals) {
return "[{\"adId\":\"0\"},{\"adId\":\"1\"}]"
[Acquirenti] Esempio di generateBid
/**
* This script receives the data returned by the ad retrieval service
* in the `ads` argument. This argument is supposed to contain all
* the Protected App Signals related ads and the metadata obtained from the retrieval
* service.
*
* `preparedDataForAdRetrieval` argument contains the data returned
* from the `prepareDataForAdRetrieval` UDF.
*
* This script is responsible for generating bids for the ads
* collected from the retrieval service and ad techs can decide to
* run a small inference model as part of this script in order to
* decide the best bid given all the signals available to them.
*
* For the purpose of the demo, this sample script assumes
* that ad retrieval service has sent us most relevant ads for the
* user and this scripts decides on the ad render URL as well as
* what value to bid for each ad based on the previously decoded
* device signals. For simplicity sake, this script only considers
* 2 types of app categories i.e. fitness and food.
*
* Note: Only one bid is returned among all the
* input ad candidates.
*/
function generateBid(ads, sellerAuctionSignals, buyerSignals, preparedDataForAdRetrieval) {
if (ads === null) {
console.log("No ads obtained from the ad retrieval service")
return {};
}
const kFitnessAd = "0";
const kFoodAd = "1";
const kBuyerDomain = "https://buyer-domain.com";
let resultingBid = 0;
let resultingRender = kBuyerDomain + "/no-ad";
for (let i = 0 ; i < ads.length; ++i) {
let render = "";
let bid = 0;
switch (ads[i].adId) {
case kFitnessAd:
render = kBuyerDomain + "/get-fitness-app";
bid = preparedDataForAdRetrieval[kFitnessAd];
break;
case kFoodAd:
render = kBuyerDomain + "/get-fastfood-app";
bid = preparedDataForAdRetrieval[kFoodAd];
break;
default:
console.log("Unknown ad category");
render = kBuyerDomain + "/no-ad";
break;
}
console.log("Existing bid: " + resultingBid + ", incoming candidate bid: " + bid);
if (bid > resultingBid) {
resultingBid = bid;
resultingRender = render;
}
}
return {"render": resultingRender, "bid": resultingBid};
}
Esempio di reportWin [Acquirenti]
La funzione definita dall'utente reportWin segnala all'acquirente che ha vinto l'asta.
function reportWin(auctionSignals, perBuyerSignals, signalsForWinner,
buyerReportingSignals, directFromSellerSignals,
egressPayload,
temporaryUnlimitedEgressPayload) {
sendReportTo("https://buyer-controlled-domain.com/");
registerAdBeacon({"clickEvent":"https://buyer-controlled-domain.com/clickEvent"});
return;
}
[Venditore] Configurazione del server di valori chiave
I venditori devono configurare un server di valori-chiave per gli indicatori di punteggio in modo che sia disponibile una mappatura
disponibili dall'annuncio per il rendering degli URL negli indicatori di punteggio corrispondenti, ad esempio:
se https:/buyer-domain.com/get-fitness-app e
L'acquirente doveva restituire https:/buyer-domain.com/get-fastfood-app,
il venditore può avere la risposta degli indicatori di punteggio del seguente esempio quando viene interrogato da
SFE utilizzando un GET su https://key-value-server-endpoint.com?client_type=1&renderUrls=<render-url-returned-by-the-buyer>:
{
"renderUrls" : {
"https:/buyer-domain.com/get-fitness-app" : [
"1",
"2"
],
"https:/buyer-domain.com/get-fastfood-app" : [
"3",
"4"
]
}
}
Esempio di scoreAd per [venditore]
/**
* This module generates a random desirability score for the Protected App
* Signals ad in this example. In a production deployment,
* however, the sellers would want to use all the available signals to generate
* a score for the ad.
*/
function getRandomInt(max) {
return Math.floor(Math.random() * max);
}
function scoreAd(adMetadata, bid, auctionConfig,
trustedScoringSignals, deviceSignals,
directFromSellerSignals) {
return {
"desirability": getRandomInt(10000),
"allowComponentAuction": false
};
}
Esempio reportResult [venditore]
function reportResult(auctionConfig, sellerReportingSignals, directFromSellerSignals){
let signalsForWinner = {};
sendReportTo("https://seller-controlled-domain.com");
registerAdBeacon({"clickEvent":
"https://seller-controlled-domain.com/clickEvent"});
return signalsForWinner;
}
App di esempio
Ecco un esempio di come l'API può essere utilizzata per creare un'app che impiega una semplice come descritto sopra, abbiamo creato un'app di esempio Protected App Signals disponibile in questo repository di esempio.