Guida per i venditori: pubblicare aste degli annunci

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

In questo articolo troverai un riferimento tecnico per l'asta dell'annuncio, come utilizzato nell'iterazione attuale dell'API Protected Audience sperimentale.

Leggi la guida per gli sviluppatori per 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'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 del venditore e degli acquirenti viene eseguito in worklet JavaScript isolati che non possono comunicare con il mondo esterno.

1. Un utente visita un sito che mostra annunci.
2. Il codice del venditore viene eseguito navigator.runAdAuction(). Specifica quale spazio pubblicitario è in vendita e chi può fare offerte. I venditori devono includere anche uno script che assegna un punteggio a ogni offerta, scoreAd().
3. Il codice dell'acquirente invitato viene eseguito per generare un'offerta, l'URL di una creatività dell'annuncio pertinente e altri dati. Lo script di offerta può eseguire query per i dati in tempo reale, come 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 per restituire l'utilità di un'offerta. Gli annunci che non possono battere il vincitore contestuale vengono rifiutati. Il venditore può utilizzare il proprio servizio Key/Value per i dati in tempo reale.
5. L'annuncio vincente viene restituito come valore opaco, che viene visualizzato in un frame recintato. Né il venditore né l'editore potranno 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'asta programmatica con più venditori:

1. L'utente visita un sito partecipante.
2. Un'asta di pubblicità programmatica viene gestita da un altro venditore per trovare un annuncio contestuale per uno spazio pubblicitario 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 superare il vincitore contestuale vengono rifiutate.

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

Esistono più parti che potrebbero organizzare un'asta per vendere spazio pubblicitario.

Ad esempio:

• Editore di contenuti: che agisce in prima persona per ospitare contenuti pubblicitari sul proprio sito web.
• Supply-Side Platform (SSP): collabora con il publisher e fornisce altri servizi.
• Script di terze parti: agisce per conto di un publisher per consentire la partecipazione alle aste degli annunci.

Con l'API Protected Audience, un venditore ha tre compiti:

• Applica le regole del publisher: quali acquirenti e quali offerte sono idonei.
• Esegui la logica dell'asta: JavaScript eseguito nei worklet per calcolare un punteggio di desiderabilità per ogni offerta.
• Segnala il risultato dell'asta.

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

Funzioni API

runAdAuction()

Il venditore invia una richiesta al browser dell'utente per avviare un'asta di annunci 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. Può essere decodificato dal browser solo quando viene passato a un frame recintato per il rendering: la pagina del publisher non può ispezionare l'annuncio vincente.

Lo script decisionLogicUrl considera ogni singolo annuncio, insieme alla relativa offerta e ai metadati, uno alla volta, quindi gli assegna un punteggio di idoneità numerico.

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 dei gruppi di interesse a cui è stato chiesto di fare offerte all'asta.

Note: 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 basato sugli interessi. Ad esempio, il venditore potrebbe esaminare le creatività pubblicitarie per verificare la conformità alle proprie norme.

auctionSignals

(Facoltativo)

Esempio: {...}

Ruolo: informazioni del venditore su contesto della pagina, tipo di asta e così via.

sellerSignals

(Facoltativo)

Esempio: {...}

Ruolo: informazioni basate sulle impostazioni del publisher, sulla creazione 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 sulla pagina per ogni acquirente specifico, dal suo server.

perBuyerTimeouts

Facoltativo

Esempio: 50

Ruolo: tempo di esecuzione massimo (ms) degli script di un determinato acquirente generateBid().

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, trasmessa a runAdAuction(). Questo URL deve includere uno script per la funzione scoreAd(). Questa logica viene eseguita una volta per ogni annuncio per determinarne l'attrattività.

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

browserSignals

browserSignals è un oggetto creato dal browser, che include informazioni che il browser conosce e che lo script dell'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 dell'inizio di un'asta, il venditore trova l'annuncio contestuale migliore per l'area annuncio disponibile. Parte della logica di scoreAd() rifiuta qualsiasi annuncio che non possa superare il vincitore contestuale.

scoreAd()

scoreAd() accetta i seguenti argomenti:

Domande frequenti

Come viene scelto il vincitore dell'asta e chi lo seleziona?

Il venditore fornisce la logica di punteggio per determinare il punteggio di desiderabilità di ogni 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 di assegnazione 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à.