Una volta elaborata la richiesta di offerta da Google, l'applicazione deve creare e inviare una risposta. Questa guida spiega come codificare l'applicazione per creare la risposta.
Crea messaggio BidResponse
Authorized Buyers invia BidRequest
come corpo del messaggio di
un POST
HTTP. La risposta inviata dall'applicazione deve avere l'intestazione Content-Type
impostata su application/octet-stream
e un corpo del messaggio costituito da un buffer di protocollo serializzato. Il buffer di protocollo è un messaggio BidResponse
come definito in realtime-bidding.proto
. L'applicazione deve restituire un BidResponse
analizzabile in risposta a ogni BidRequest
. I timeout e le risposte che non possono essere analizzati sono considerati errori e Google limita gli offerenti con percentuali di errore elevate.
Se non vuoi fare offerte per un'impressione, puoi impostare solo il campo processing_time_ms
e lasciare vuoti tutti gli altri campi. Puoi recuperare realtime-bidding.proto
dalla pagina dei dati di riferimento.
ID creatività
BidResponse
specifica una creatività tramite il campo buyer_creative_id
(limite di 64 byte). Anche creatività simili
devono avere valori univoci per buyer_creative_id
se differiscono in
caratteristiche degne di nota tra cui, a titolo esemplificativo, dimensioni, URL dichiarato, attributi delle creatività e tipi di fornitore. In altre parole, devi assegnare ID creatività diversi a due annunci che:
- Avere un aspetto o un comportamento diverso.
- Esegui il rendering su immagini diverse.
- Esegui il rendering in modi diversi (ad esempio, un annuncio è costituito da un'immagine e l'altro contiene Flash).
Durante la progettazione dell'applicazione, devi decidere un modo sistematico di generare identificatori significativi per i tipi di creatività che intendi inviare.
Attributi annuncio
Devi dichiarare gli attributi della creatività che descrivono in modo completo le caratteristiche
dell'annuncio e il relativo targeting in BidResponse.Ad.attribute
. Gli attributi che devono essere dichiarati sono (consulta anche l'elenco completo degli attributi supportati all'indirizzo buyer-declarable-creative-attributes.txt):
7 Tagging: IsTagged
L'annuncio contiene un pixel o un beacon web allo scopo di creare un elenco di ID cookie per il successivo remarketing.8 Remarketing: IsRemarketing
L'annuncio ha come target i consumatori in base al loro ID cookie o ID dispositivo, dove l'elenco di ID cookie o ID dispositivo rappresenta un insieme di consumatori che in precedenza hanno interagito con un sito di proprietà o rappresentato dall'acquirente.9 UserInterestTargeting: IsUserInterestTargeted
L'annuncio è indirizzato ai consumatori in base al loro ID cookie o ID dispositivo, dove l'elenco di ID cookie o ID dispositivo rappresenta un insieme di consumatori definiti dall'acquirente come gruppo di interesse comune.30 InstreamVastVideoType: Vpaid
Per il rendering dell'annuncio è necessario il supporto VPAID.32 MraidType: MRAID
Per il rendering dell'annuncio è necessaria l'API MRAID.
Inoltre, i seguenti attributi sono supportati, ma la relativa dichiarazione non è obbligatoria, perché Authorized Buyers li rileva automaticamente e blocca (o consente) le tue creatività in base ai valori rilevati, anziché alla tua dichiarazione. Consulta API Creatives per scoprire come ricevere feedback relativi alle proprietà rilevate delle tue creatività.
34 RichMediaCapabilityType: RichMediaCapabilityFlash
Per il rendering dell'annuncio è necessario il supporto Flash.50 RichMediaCapabilityType: RichMediaCapabilityNonFlash
L'annuncio non richiede Flash per il rendering.47 RichMediaCapabilityType: RichMediaCapabilitySSL
L'annuncio può essere visualizzato su una pagina SSL. Tieni presente che Authorized Buyers considera le creatività con valori dichiarati diversi di questo attributo come distinte (verranno esaminate separatamente e avranno stati di approvazione distinti). Di conseguenza, se fai offerte con entrambe le versioni SSL e non SSL della stessa creatività, devi dichiarare questo attributo di conseguenza, in modo che questa distinzione si rifletta correttamente in AdX.
Campi di Open Bidding
Le risposte all'offerta inviate dagli offerenti di rete e della piattaforma di scambio che partecipano a Open Bidding sono simili a quelle di Authorized Buyers che partecipano alle offerte in tempo reale standard. I clienti di Open Bidding possono specificare un numero limitato di campi aggiuntivi e alcuni campi esistenti potrebbero avere utilizzi alternativi. tra cui:
OpenRTB | Authorized Buyers | Dettagli |
---|---|---|
BidResponse.imp[].pmp.deals[].id |
BidResponse.ad[].adslot[].exchange_deal_id |
L'ID deal dello spazio dei nomi della piattaforma di scambio pubblicitario associato a questa offerta e riportato ai publisher. |
BidResponse.seatbid[].bid[].ext.exchange_deal_type |
BidResponse.ad[].adslot[].exchange_deal_type |
Il tipo di deal segnalato ai publisher, che influisce sul modo in cui il deal viene trattato nell'asta. |
BidResponse.seatbid[].bid[].ext.third_party_buyer_token |
BidResponse.ad[].adslot[].third_party_buyer_token |
Token utilizzato per identificare le informazioni sull'acquirente di terze parti finale se la piattaforma di scambio pubblicitario come Open Bidding è un intermediario. Questo dato viene ottenuto dall'acquirente di terze parti e deve essere trasmesso a Google inalterato nella risposta all'offerta. |
Suggerimenti
- Abilita le connessioni HTTPS permanenti (note anche come "keep-alive" o "riutilizzo della connessione") sui tuoi server. Imposta il timeout su un valore minimo di 10 secondi: in molti casi valori più elevati sono vantaggiosi. Google verifica ciò durante i test di latenza iniziali della tua applicazione, poiché Authorized Buyers invia richieste con una frequenza elevata e deve evitare l'overhead di latenza necessario per stabilire una connessione TCP separata per ogni richiesta.
Includi l'URL di monitoraggio delle impressioni facoltativo per monitorare quando viene visualizzata l'impressione anziché quando vince l'offerente. A causa dell'abbandono tra vincite e rendering, questo produce statistiche di monitoraggio più accurate.
- Mantieni il codice dello strumento di offerta privo di dipendenze da campi obsoleti, che possono causare errori nelle offerte.
- Includi
BidResponse.Ad.width
eBidResponse.Ad.height
inBidResponse
. Un valoreBidResponse
per una richiesta che include più dimensioni di annunci deve includere i valoriwidth
eheight
altrimenti verrà eliminato dall'asta. - Limita le dimensioni della risposta a meno di 8 K. Risposte molto grandi possono aumentare la latenza di rete e causare timeout.
- Segui le linee guida per le offerte per l'inventario iOS che richiedono l'attribuzione SKAdNetwork.
Esempio di risposta all'offerta
Gli esempi riportati di seguito rappresentano esempi leggibili dalle richieste Protobuf e JSON.
JSON OpenRTB
Protobuf OpenRTB
Importante: i messaggi Protobuf illustrati negli esempi sono rappresentati qui come testo leggibile. Tuttavia, non è così che i messaggi vengono inviati via cavo. Quando utilizzi il formato Google o OpenRTB Protobuf, sono accettati solo i messaggi BidResponse serializzati.
Puoi creare e serializzare un messaggio BidResponse
utilizzando il seguente codice C++:
BidResponse bid_response; // fill in bid response with bid information string post_response; if (bid_response.SerializeToString(&post_response)) { // respond to the POST with post_response as the content } else { // return an error to the POST }
Specifica creatività
La risposta all'offerta specifica la creatività da pubblicare se l'offerta vince. La tua offerta
deve includere uno dei formati di annunci supportati (AMP, video, nativi). In questo esempio, specifichiamo la creatività utilizzando il campo html_snippet
.
In alternativa, puoi specificare la creatività utilizzando uno dei seguenti campi, in base al formato dell'annuncio:
- Annuncio sottoposto a rendering con SDK
BidResponse.Ad.sdk_rendered_ad
- AMP
BidResponse.Ad.amp_ad_url
- Video
BidResponse.Ad.video_url
oBidResponse.Ad.video_vast_xml
- Nativo
BidResponse.Ad.native_ad
Specifica un annuncio ospitato sui tuoi server utilizzando uno snippet HTML nel
campo html_snippet
di BidResponse
. Lo snippet viene racchiuso in un iframe inserito nella pagina web, in modo che l'annuncio venga recuperato e visualizzato al caricamento della pagina. Devi creare lo snippet HTML in modo che l'annuncio (banner o interstitial) venga visualizzato correttamente all'interno di un iframe e abbia dimensioni appropriate per l'area annuncio per cui fai un'offerta.
Inoltre, le dimensioni dell'annuncio dichiarate nella risposta all'offerta devono corrispondere esattamente a una delle combinazioni di dimensioni nella richiesta di offerta quando:
- Un annuncio è un banner standard (non un video, nativo o interstitial).
- L'offerente ha dichiarato la dimensione nella risposta all'offerta. La dichiarazione delle dimensioni è obbligatoria ogni volta che nella richiesta è presente più di una dimensione.
- Viene fatta un'eccezione per gli annunci interstitial. Per gli interstitial, la larghezza deve essere almeno il 50% della larghezza dello schermo e l'altezza deve essere almeno il 40% dell'altezza dello schermo.
Il campo html_snippet
supporta qualsiasi codice HTML valido visualizzato correttamente, ma tieni presenti le limitazioni relative alla specifica del campo buyer_creative_id
nella sezione Crea messaggio BidResponse. Ciò può essere utile per inserire informazioni aggiuntive negli argomenti degli URL recuperati dai server nell'ambito del rendering dell'annuncio. Ciò ti consente di ritrasmettere i dati arbitrari sull'impressione ai tuoi server.
La maggior parte delle norme relative agli snippet HTML restituiti nelle risposte all'offerta è uguale a quella per gli annunci di terze parti. Per ulteriori informazioni, consulta le linee guida del programma Authorized Buyers, i Requisiti per la pubblicazione di annunci di terze parti e la Dichiarazione di URL di clickthrough negli annunci.
Specifica le macro
Lo snippet HTML che definisce una creatività può includere uno o più elementi speciali denominati macro. Al momento della pubblicazione degli annunci, i valori vengono sostituiti
per le macro. Ad esempio, l'applicazione di offerta client potrebbe utilizzare la macro WINNING_PRICE
per determinare quanto ha pagato l'annuncio se vince l'asta. Per analizzare questa macro, devi implementare un'applicazione che decripta le conferme dei prezzi. Per ulteriori informazioni, consulta la pagina Decriptazione delle conferme dei prezzi.
Specifica una macro come parte di uno snippet HTML nel formato %%MACRO%%
, dove MACRO
è una delle macro supportate elencate nella tabella seguente.
Google richiede l'utilizzo della macro CLICK_URL_UNESC
o CLICK_URL_ESC
nella creatività dell'annuncio pubblicato da terze parti. Google utilizza le macro CLICK_URL
per il monitoraggio dei clic.
Per utilizzare una macro, includila nell'annuncio in modo che l'URL venga recuperato quando un utente fa clic sull'annuncio. Il valore restituito del recupero è un reindirizzamento a un altro URL che aggiungi a CLICK_URL
.
Macro | Descrizione |
---|---|
ADVERTISING_IDENTIFIER |
Consente agli acquirenti di ricevere l'IDFA di iOS o l'ID pubblicità di Android al rendering delle impressioni. Per ulteriori dettagli, consulta Decriptazione degli identificatori degli inserzionisti. |
CACHEBUSTER |
Una rappresentazione stringa di un numero intero a quattro byte casuale, senza segno. |
CLICK_URL_UNESC |
L'URL di clic senza caratteri di escape dell'annuncio. Nello snippet, una versione con caratteri di escape dell'URL di clic di terze parti deve seguire direttamente la macro. Ad esempio, se l'URL di clic di terze parti è <a href="%%CLICK_URL_UNESC%%http%3A%2F%2Fmy.adserver.com%2Fsome%2Fpath%2Fhandleclick%3Fclick%3Dclk"></a> Al momento della pubblicazione degli annunci, questo valore viene esteso a: <a href="http://google-click-url?...&ad_url=http%3A%2F%2Fmy.adserver.com%2Fsome%2Fpath%2Fhandleclick%3Fclick%3Dclk"></a> L'URL registra innanzitutto il clic su Google, quindi reindirizza all'URL di clic di terze parti. |
CLICK_URL_ESC |
L'URL di clic con caratteri di escape dell'annuncio. Utilizza questo metodo invece di
Ad esempio, in uno snippet HTML potrebbe essere utilizzato il seguente codice: <a href="http://my.adserver.com/click?google_click_url=%%CLICK_URL_ESC%%"></a> Al momento della pubblicazione degli annunci, questo valore viene esteso a: <a href="http://my.adserver.com/click?google_click_url=http://google-click- url%3F...%26ad_url%3D"></a> In questo modo il clic viene registrato con Puoi aggiungere un URL con doppio escape dopo |
CLICK_URL_ESC_ESC |
L'URL con doppio escape dell'annuncio. Utilizza questo metodo invece di
Ad esempio, in uno snippet HTML potrebbe essere utilizzato il seguente codice: <a href="http://my.adserver.com/click?google_click_url=%%CLICK_URL_ESC_ESC%%"></a> Al momento della pubblicazione degli annunci, questo valore viene esteso a: <a href="http://my.otheradserver.com/click?google_click_url=http%3A%2F%2Fmy.adserver.com%2Fclick%3Fgoogle_click_url%3Dhttp%3A%2F%2Fgoogle-click-%20url%253F...%2526ad_url%253D"></a> |
SCHEME |
Espanso a http: se la richiesta di offerta non richiede SSL o a
https: se la richiesta di offerta richiede SSL. |
SITE |
Il dominio URL con escape dell'URL di contenuti o l'ID anonimo per l'inventario anonimo. |
SITE_URL |
Deprecato. Sostituita dalla macro SITE, che fornisce le stesse funzionalità. |
TZ_OFFSET |
La differenza di fuso orario. |
VERIFICATION |
I diversi valori per la produzione e il momento in cui la creatività viene analizzata nella pipeline di verifica. Il formato è %%?VERIFICATION:true-val:false-val%% , dove tutti i valori tranne le macro possono essere utilizzati per true-val e false-val , comprese le stringhe vuote. Per Open Bidding, consigliamo alle piattaforme di scambio di utilizzare questa macro; una volta effettuata questa operazione, le Demand-Side Platform non devono apportare modifiche.Ad esempio, se una creatività dovesse includere %%?VERIFICATION:-1:5000%% , la sostituzione del testo sarebbe 5000 alla pubblicazione e -1 nella pipeline di verifica. Questo serve a distinguere questi due insiemi di ping. |
WINNING_PRICE |
Costo delle impressioni codificato (ovvero CPI anziché CPM) in micro della valuta dell'account. Ad esempio, un CPM vincente di 5 $corrisponde a un CPM di 5.000.000 di micro, o CPI di 5000 micro. Il valore decodificato di WINNING_PRICE in questo caso sarebbe 5000.
Il prezzo vincente è specificato nel CPI.
|
WINNING_PRICE_ESC |
WINNING_PRICE con URL in formato escape. |
L'escape degli URL nelle macro utilizza il seguente schema:
- Lo spazio è sostituito dal segno più (
+
). - I caratteri alfanumerici (0-9, a-z, A-Z) e i caratteri della serie !()*,-./:_~ rimangono invariati.
- Tutti gli altri caratteri sono sostituiti da
%XX
, doveXX
è il numero esadecimale che rappresenta il carattere.
Limitazioni per i publisher
I publisher utilizzano l'BidRequest
per trasmettere limitazioni agli annunci consentiti. Devi applicare le limitazioni in questi campi:
allowed_vendor_type
excluded_attribute
excluded_sensitive_category
Un campo specifica le funzionalità consentite dell'annuncio, l'altro quelle non consentite. Non restituire mai un annuncio con una funzionalità non consentita. Per le funzionalità consentite come il tipo di fornitore, restituisci un annuncio solo se il tipo di fornitore è presente nell'elenco allowed_vendor_type
in BidRequest
. Per ulteriori dettagli, consulta i commenti per questi campi nella definizione del buffer di protocollo BidRequest
.
Se uno snippet HTML viene restituito in BidResponse
, devi
impostare con precisione i campi attribute
, category
e click_through_url
in BidResponse
.
Se un annuncio ha più valori applicabili per questi campi, devi includere ogni valore. Per ulteriori dettagli, leggi i commenti su questi campi nella definizione del buffer di protocollo BidResponse
.
Le risposte che non hanno questi campi impostati vengono ignorate.
I valori possibili di BidRequest.excluded_attribute
sono
(vedi publisher-excludable-creative-attributes.txt):
7 Tagging: IsTagged
Gli annunci non sono consentiti se contengono un pixel o un beacon web allo scopo di creare un elenco di ID cookie per il successivo remarketing.8 CookieTargeting: IsCookieTargeted
Gli annunci non sono consentiti se scelgono come target i consumatori in base al loro ID cookie, dove l'elenco degli ID cookie rappresenta un insieme di consumatori che in precedenza hanno interagito con un sito di proprietà o rappresentato dall'acquirente.9 UserInterestTargeting: IsUserInterestTargeted
Gli annunci non sono consentiti se scelgono come target i consumatori in base al loro ID cookie, dove l'elenco degli ID cookie rappresenta un insieme di consumatori che l'acquirente ha definito come gruppo di interesse comune.21 CreativeType: Html
Gli annunci non possono utilizzare il campohtml_snippet
osnippet_template
inBidResponse.Ad
.22 CreativeType: VastVideo
Gli annunci non possono utilizzare il campovideo_url
inBidResponse.Ad
.30 InstreamVastVideoType: Vpaid
Gli annunci non possono richiedere il supporto VPAID per il rendering.32 MraidType: MRAID
Gli annunci non possono richiedere il rendering dall'API MRAID.34 RichMediaCapabilityType: RichMediaCapabilityFlash
Gli annunci non possono richiedere il supporto Flash per il rendering.39 RichMediaCapabilityType: RichMediaCapabilityHTML5
Gli annunci non possono richiedere funzionalità HTML5 per il rendering.48 RichMediaCapabilityType: RichMediaCapabilityNonSSL
Gli annunci non sono autorizzati a effettuare richieste non SSL.
Di conseguenza, se il campo excluded_attribute
contiene il valore 7, non devi restituire un annuncio che utilizza un pixel o un beacon web per la creazione di un elenco. Tieni presente che se un annuncio esegue questa operazione, deve impostare il valore 7 nel
campo dell'attributo di BidResponse
.
Allo stesso modo, se il campo excluded_attribute
contiene il valore 48, devi restituire solo gli annunci in grado di eseguire il rendering su una pagina SSL (e di conseguenza dichiarare l'attributo 47 RichMediaCapabilityType: RichMediaCapabilitySSL).
Inoltre, il campo excluded_sensitive_category
in BidRequest
utilizza i codici del file ad-sensitive-categories.txt
disponibili nella pagina Dati di riferimento. Ecco le descrizioni estese di alcuni di questi codici:
3 Politics
Include politiche o questioni sociali controverse; non include gli annunci che promuovono agenzie di stampa generalmente non considerate di parte.4 Dating
Include servizi di incontri e community di incontri online.5 Religion
Include annunci religiosi e annunci che promuovono o condannano orientamenti religiosi; non include l'astrologia o spiritualità non confessionali.7 Video Games (Casual & Online)
Include videogiochi, giochi online e giochi scaricabili; non include console per videogiochi.8 Ringtones & Downloadables
Componenti aggiuntivi per dispositivi mobili, tra cui suonerie e altri articoli scaricabili, come salvaschermo e sfondi per computer, nonché immagini e layout di profili per social network.10 Get Rich Quick
Schemi che promettono rapidi utili.18 Weight Loss
Include regimi dimagranti, diete ipocaloriche, programmi e prodotti correlati; non include annunci per la sana alimentazione e il benessere generale.19 Cosmetic Procedures & Body Modification
Include lifting, suzioni, interventi con il laser, depilazione e interventi per la ricrescita dei capelli, tatuaggi e interventi di chirurgia plastica.23 Drugs & Supplements:
Include prodotti farmaceutici, vitamine, integratori e rivenditori correlati; non include risorse che forniscono informazioni sui farmaci.24 Sexual & Reproductive Health
Include annunci sulle funzioni sessuali e sulla fertilità; non include le normali risorse per la gravidanza.35 Social Casino Games
Sono inclusi giochi e scommesse simulati (inclusi, senza alcuna limitazione, poker, slot machine, bingo, lotterie, scommesse sportive, scommesse sulle corse, nonché altri giochi di carte e giochi da casinò) in cui non è possibile vincere beni di valore (come denaro o premi).36 Significant Skin Exposure
Immagini di annunci in cui qualsiasi parte del corpo umano non è vestita, dallo sterno fino a metà coscia; oppure il corpo è vestito con biancheria intima, costumi da bagno, lingerie o altri indumenti trasparenti oppure con un asciugamano o un lenzuolo.37 Sensationalism
Annunci che hanno lo scopo di indurre gli utenti a fare clic su di essi attirando la loro curiosità, spesso con messaggi teaser che utilizzano immagini o linguaggio iperbolici. Include gli annunci incentrati su argomenti sensazionalistici (ad esempio l'arresto, la morte o il divorzio delle celebrità) o con contenuti potenzialmente scioccanti.
Apri Measurement
Open Measurement consente di specificare fornitori di terze parti che forniscono servizi indipendenti di misurazione e verifica per gli annunci pubblicati in ambienti di app mobile.Al momento, i formati di annunci supportati includono annunci video, banner e interstitial. Per ulteriori informazioni su come utilizzare Open Measurement in una risposta all'offerta contenente questi formati, consulta l'articolo del Centro assistenza SDK Open Measurement.
Risposte all'offerta di esempio
Le seguenti sezioni mostrano esempi di risposte all'offerta per diversi tipi di annunci.