Guida per i venditori: pubblicare aste degli annunci

Guida all'API Seller e riferimenti per l'asta dell'annuncio dell'API Protected Audience.

In questo articolo troverai 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 conoscere l'intero ciclo di vita dell'API Protected Audience e consulta la spiegazione dell'API Protected Audience per una discussione approfondita su come i venditori eseguono 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 dell'API Protected Audience è una raccolta di piccoli programmi JavaScript che il browser esegue sul dispositivo dell'utente per scegliere un annuncio. Per tutelare la privacy, tutto il codice dell'asta dell'annuncio fornito dal venditore e dagli acquirenti viene eseguito in worklet JavaScript isolati che non possono comunicare con il mondo esterno.

Sei fasi di un'asta dell'annuncio dell'API Protected Audience
Questo diagramma illustra ogni fase dell'asta dell'annuncio dell'API Protected Audience.
  1. Un utente visita un sito che pubblica annunci.
  2. Il codice del venditore esegue il giorno navigator.runAdAuction(). che specifica quale spazio pubblicitario è in vendita e chi può fare offerte. I venditori devono anche includere uno script che attribuisca un punteggio a ogni offerta, scoreAd().
  3. Il codice dell'acquirente invitato viene eseguito per generare un'offerta, l'URL per una creatività dell'annuncio pertinente e altri dati. Lo script di offerta può eseguire query su dati in tempo reale, ad esempio il budget rimanente della campagna pubblicitaria, dal servizio chiave/valore dell'acquirente.
  4. Il codice del venditore assegna un punteggio a ogni offerta e seleziona un vincitore. Questa logica utilizza il valore dell'offerta e altri dati restituiscono l'opportunità di un'offerta. Gli annunci che non possono battere il vincitore contestuale vengono rifiutati. Il venditore può utilizzare il proprio servizio chiave/valore per ottenere dati in tempo reale.
  5. L'annuncio vincente viene restituito sotto forma di valore opaco, che viene mostrato in un frame recintato. Sia il venditore sia l'editore non saranno in grado di visualizzare questo valore.
  6. L'asta viene segnalata al venditore e agli acquirenti vincenti.

Quando si svolge l'asta?

L'API Protected Audience può essere eseguita da sola o con aste programmatiche. In un'asta programmatica multi-venditore:

  1. L'utente visita un sito partecipante.
  2. Un'asta programmatica viene gestita da un altro venditore per trovare un annuncio contestuale per un'area annuncio disponibile.
  3. Viene eseguita l'asta dell'API Protected Audience.
  4. scoreAd()confronta le offerte dell'acquirente con i risultati della prima asta.

Le offerte che non possono battere il vincitore contestuale vengono rifiutate.

Chi esegue l'asta dell'annuncio dell'API Protected Audience?

Più parti possono eseguire un'asta per vendere uno spazio pubblicitario.

Ad esempio:

  • Publisher di contenuti: che agisce per sé stesso per ospitare i contenuti degli annunci sul proprio sito web.
  • Supply-Side Platform (SSP): collaborazione con il publisher e fornitura di altri servizi.
  • Script di terze parti: che agisce per un publisher, per consentire la partecipazione alle aste dell'annuncio.

Con l'API Protected Audience, un venditore svolge tre job:

  • Forza l'applicazione delle regole per i publisher, ovvero quali acquirenti e offerte sono idonei.
  • Esegui la logica dell'asta: JavaScript viene eseguito nei worklet per calcolare un punteggio di desiderabilità per ogni offerta.
  • Segnalare il risultato dell'asta.

Questi job vengono eseguiti in modo programmatico, nel codice fornito dal venditore quando avvia un'asta dell'annuncio richiamando la funzione JavaScript navigator.runAdAuction().

Funzioni API

runAdAuction()

Il venditore 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': ...,
      ...
    },
    ...
  ]
};

try {
  const auctionResultPromise = navigator.runAdAuction(auctionConfig);
} catch (error) {
  // Handle error.
}

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, insieme all'offerta associata e ai metadati, quindi assegna un punteggio numerico 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 a cui è stato chiesto di fare offerte nell'asta.
Nota: 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.
auctionSignals
Facoltativo
Esempio: {...}
Ruolo: informazioni del venditore sul contesto della pagina, sul tipo di asta e così via.
sellerSignals
Facoltativo
Esempio: {...}
Ruolo: informazioni basate sulle impostazioni del publisher, creazione di una richiesta di annuncio contestuale e così via.
sellerTimeout
Facoltativo
Esempio: 100
Ruolo: runtime massimo (ms) dello script scoreAd() del venditore.
perBuyerSignals
Facoltativo
Esempio: 
{'https://dsp.example': {...}, 'https://another-buyer.example': {...}, ... }
Ruolo: indicatori contestuali sulla pagina per ogni acquirente specifico, dal relativo server.
perBuyerTimeouts
Facoltativo
Esempio: 50
Ruolo: runtime massimo (ms) degli script generateBid() di un acquirente specifico.
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, passata a runAdAuction(). Questo URL deve includere uno script per la funzione scoreAd(). Questa logica viene eseguita una volta per ogni annuncio per determinarne l'appetibilità.

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

browserSignals

browserSignals è un oggetto creato dal browser, incluse informazioni che il browser conosce e che lo script di 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 /* DValue 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 logica scoreAd() rifiuta qualsiasi annuncio che non può battere l'elemento vincente 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 una logica nella funzione scoreAd() e il browser la esegue in un worklet che ha una comunicazione limitata con codice al di fuori di questo. Il browser stesso non assegna un punteggio agli annunci. Il browser è l'unico responsabile dell'esecuzione della logica di punteggio e della selezione dell'offerta con il punteggio più alto.

Tutti i riferimenti dell'API Protected Audience

Sono disponibili guide di riferimento API:

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