Guida all'API Seller e riferimenti per l'asta dell'annuncio dell'API Protected Audience.
Questo articolo fornisce un riferimento tecnico per l'asta dell'annuncio, come utilizzato nell'attuale iterazione dell'API Protected Audience sperimentale.
Leggi la guida per gli sviluppatori per l'utilizzo completo ciclo di API Protected Audience e fai riferimento al messaggio esplicativo dell'API Protected Audience per una discussione approfondita su in che modo i venditori svolgono le aste on-device.
Non sei uno sviluppatore? Consulta la panoramica dell'API Protected Audience.
Che cos'è l'asta dell'annuncio dell'API Protected Audience?
Un'asta dell'annuncio con l'API Protected Audience è una raccolta di piccoli programmi JavaScript che browser viene eseguito sul dispositivo dell'utente per scegliere un annuncio. Per preservare la privacy, tutti gli annunci dell'asta dal venditore e dagli acquirenti viene eseguito in codice JavaScript isolato worklet che non possono comunicare con esterno.
![Sei fasi di un'asta dell'annuncio dell'API Protected Audience](https://developers-dot-devsite-v2-prod.appspot.com/static/privacy-sandbox/assets/images/six-stages-a-protected-a-3e1dd6fdeddbe.png?authuser=19&hl=it)
- Un utente visita un sito che visualizza annunci.
- Il codice del venditore esegue
navigator.runAdAuction()
. In questo modo viene specificato spazio pubblicitario è in vendita e chi può fare offerte. I venditori devono includere anche uno script che assegna un punteggio a ciascuna offerta,scoreAd()
. - Il codice dell'acquirente invitato viene eseguito per generare un'offerta, un URL per un annuncio pertinente creatività e altri dati. Lo script di offerta può eseguire query per ottenere dati in tempo reale, ad esempio il budget rimanente della campagna pubblicitaria, Servizio chiave/valore.
- Il codice del venditore assegna un punteggio a ciascuna offerta e seleziona un vincitore. Questa logica utilizza il valore dell'offerta e altri dati restituiscono l'attrattiva di un'offerta. Annunci che non possono battere vengono rifiutate. Il venditore può utilizzare i propri Servizio chiave/valore per dati in tempo reale.
- L'annuncio vincente viene restituito come un valore opaco, che viene visualizzato in frame recintata. Sia il venditore che il publisher non sarà in grado di visualizzare questo valore.
- L'asta viene segnalata al venditore e agli acquirenti vincitori.
Quando si svolge l'asta?
L'API Protected Audience può essere eseguita da sola o con aste di pubblicità programmatica. In un multi-venditore, asta programmatica:
- L'utente visita un sito partecipante.
- Un'asta programmatica viene gestita da un altro venditore per trovare un annuncio contestuale per un'area annuncio disponibile.
- Viene eseguita l'asta dell'API Protected Audience.
scoreAd()
confronta le offerte dell'acquirente con i risultati della prima asta.
Le offerte che non possono battere la variante vincente contestuale vengono rifiutate.
Chi esegue l'asta dell'annuncio dell'API Protected Audience?
Più parti potrebbero eseguire un'asta per vendere spazio pubblicitario.
Ad esempio:
- Publisher di contenuti: agisce per conto proprio per ospitare i contenuti dell'annuncio sul proprio sito web.
- Supply-Side Platform (SSP): collaborazione con il publisher e fornitura di altri servizi.
- Script di terze parti, che agisce per conto di un publisher, per consentire la partecipazione alle aste dell'annuncio.
Con l'API Protected Audience, un venditore ha tre job:
- Applicare le regole per i publisher: quali acquirenti e quali offerte sono idonei.
- Logica di esecuzione dell'asta: esecuzione di JavaScript in worklet per calcolare un punteggio di desiderabilità per ogni offerta.
- Segnala il risultato dell'asta.
Questi lavori vengono eseguiti in modo programmatico, nel codice fornito dal venditore
avvia un'asta dell'annuncio richiamando la funzione JavaScript
navigator.runAdAuction()
.
Funzioni API
runAdAuction()
Il venditore invia una richiesta al browser dell'utente per avviare un'asta dell'annuncio chiamando il numero navigator.runAdAuction()
.
Ad esempio:
const auctionConfig = {
seller: 'https://ssp.example',
decisionLogicUrl: ...,
trustedScoringSignalsUrl: ...,
interestGroupBuyers: ['https://dsp.example', 'https://buyer2.example', ...],
auctionSignals: {...},
sellerSignals: {...},
sellerTimeout: 100,
perBuyerSignals: {
'https://dsp.example': {...},
'https://another-buyer.example': {...},
...
},
perBuyerTimeouts: {
'https://dsp.example': 50,
'https://another-buyer.example': 200,
'*': 150,
...
},
componentAuctions: [
{
'seller': 'https://some-other-ssp.example',
'decisionLogicUrl': ...,
...
},
...
]
};
try {
const auctionResultPromise = navigator.runAdAuction(auctionConfig);
} catch (error) {
// Handle error.
}
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 alle relative
a un'offerta e ai metadati associati, uno alla volta, quindi assegna loro un valore
il punteggio di desiderabilità.
auctionConfig
strutture
seller
- Obbligatorio
- Esempio:
'https://ssp.example'
- Ruolo: origine del venditore.
decisionLogicUrl
- Obbligatorio
- Esempio:
'https://ssp.example/auction-decision-logic.js'
- Ruolo: URL per il codice JavaScript del worklet dell'asta.
trustedScoringSignalsUrl
- Facoltativo
- Esempio:
'https://ssp.example/scoring-signals'
- Ruolo: URL del server attendibile del venditore.
interestGroupBuyers
- Obbligatorio
- Esempio:
['https://dsp.example', 'https://buyer2.example', ...]
- Ruolo: origini di tutti i proprietari di gruppi di interesse che hanno chiesto di fare offerte nell'asta. di Gemini Advanced.
- Note: 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. auctionSignals
- Facoltativo
- Esempio:
{...}
- Ruolo: informazioni sul venditore relative al contesto della pagina, al tipo di asta e così via.
sellerSignals
- Facoltativo
- Esempio:
{...}
- Ruolo: informazioni basate sulle impostazioni del publisher, sull'invio di una richiesta di annuncio contestuale e così via.
sellerTimeout
- Facoltativo
- Esempio:
100
- Ruolo: tempo di esecuzione massimo (ms) dello script
scoreAd()
del venditore. perBuyerSignals
- Facoltativo
- Esempio:
{'https://dsp.example': {...}, 'https://another-buyer.example': {...}, ... }
- Ruolo: indicatori contestuali relativi alla pagina per ogni acquirente specifico, provenienti dal relativo server.
perBuyerTimeouts
- Facoltativo
- Esempio:
50
- Ruolo: tempo di esecuzione massimo (ms) degli script
generateBid()
di un determinato acquirente. componentAuctions
- Facoltativo
- Esempio:
[{'seller': 'https://www.some-other-ssp.com', 'decisionLogicUrl': ..., ...}, ...]
- Ruolo: configurazioni aggiuntive per le aste dei componenti.
decisionLogicUrl
decisionLogicUrl
è una proprietà dell'oggetto di configurazione dell'asta,
passato a runAdAuction()
. Questo URL deve includere uno script per il parametro
scoreAd()
. Questa logica viene eseguita una volta per ogni annuncio
determinarne l'appetibilità.
scoreAd(adMetadata, bid, auctionConfig, trustedScoringSignals, browserSignals) {
...
return desirabilityScoreForThisAd;
}
browserSignals
browserSignals
è un oggetto creato dal browser, che include le informazioni
che il browser conosce e quali script dell'asta del venditore potrebbero voler
verifica:
{
topWindowHostname: 'publisher.example',
interestGroupOwner: 'https://dsp.example',
renderUrl: 'https://cdn.example/render',
adComponents: ['https://cdn.com/ad-component-1', ...],
biddingDurationMsec: 12,
dataVersion: 1 /* DValue from the seller's Key/Value service response. */
}
Prima dell'inizio di un'asta, il venditore trova l'annuncio contestuale migliore per
un'area annuncio disponibile. Parte della logica scoreAd()
rifiuta tutti gli annunci che non possono
battere il vincitore contestuale.
scoreAd()
scoreAd()
accetta i seguenti argomenti:
Argomento | Ruolo |
---|---|
adMetadata |
Metadati arbitrari forniti dall'acquirente. |
auctionConfig |
L'oggetto di configurazione dell'asta passato a navigator.runAdAuction() . |
bid |
Un valore numerico dell'offerta. |
trustedScoringSignals |
Valori recuperati al momento dell'asta dal server attendibile del venditore, che rappresentano l'opinione del venditore sull'annuncio. |
Domande frequenti
Come viene deciso il vincitore dell'asta e chi lo sceglie?
Il venditore fornisce la logica di punteggio per determinare il punteggio di desiderabilità di ciascun annuncio e il browser seleziona il punteggio più alto come annuncio vincente.
Il venditore include la logica nella funzione scoreAd()
e il browser esegue la funzione in un worklet che ha una comunicazione limitata con il codice esterno. Il browser stesso non assegna un punteggio agli annunci. Il browser è l'unico responsabile dell'esecuzione della logica del punteggio e della selezione dell'offerta con il punteggio più alto.
Tutti i riferimenti all'API Protected Audience
Sono disponibili guide di riferimento API:
- Guida per gli sviluppatori relativa all'API Protected Audience.
- Guida per gli acquirenti di annunci ai gruppi di interesse e alla generazione di offerte di Protected Audience.
- Guida per i venditori di annunci alle aste degli annunci di Protected Audience.
- Guida per generare report sui risultati dell'asta
- Best practice per la latenza dell'asta dell'annuncio di Protected Audience
- Risolvere i problemi relativi a Protected Audience
Il messaggio esplicativo dell'API Protected Audience fornisce anche dettagli sul supporto e sui vincoli delle funzionalità.