Guida per i venditori: pubblicare aste degli annunci

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
Questo diagramma illustra ogni fase di un'asta dell'annuncio dell'API Protected Audience.
  1. Un utente visita un sito che visualizza annunci.
  2. 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().
  3. 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.
  4. 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.
  5. 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.
  6. 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:

  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 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:

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