Antwort erstellen

Nachdem Ihre Anwendung die Gebotsanfrage von Google verarbeitet hat, muss sie eine Antwort erstellen und senden. In diesem Leitfaden wird beschrieben, wie Sie Ihre Anwendung so programmieren, dass die Antwort erstellt wird.

Protobuf-BidResponse-Nachricht erstellen

Authorized Buyers sendet die BidRequest als Nachrichtentext einer HTTP-POST. Wenn Ihr Gebotsendepunkt für das Protobuf-Format konfiguriert ist, muss Ihre Anwendung eine Antwort mit dem Content-Type-Header application/octet-stream und einem Nachrichtentext senden, der aus einem serialisierten Protokoll-Zwischenspeicher besteht. Der Protokollpuffer ist eine BidResponse-Nachricht gemäß der Definition in openrtb.proto. Ihre Anwendung muss für jede BidRequest eine analysierbare BidResponse zurückgeben. Zeitüberschreitungen und Antworten, die nicht geparst werden können, gelten als Fehler. Google drosselt Bieter mit hoher Fehlerrate.

Wenn Sie kein Gebot für eine Impression abgeben möchten, müssen Sie eine leere HTTP-204-Antwort zurückgeben. openrtb.proto finden Sie auf der Seite Referenzdaten.

Creative-ID

In Ihrem BidResponse wird ein Creative über das Feld BidResponse.seatbid.bid.crid angegeben (64 Byte). Selbst ähnliche Creatives müssen eindeutige Werte für dieses Feld haben, wenn sie sich in wichtigen Merkmalen unterscheiden, z. B. Größe, deklarierte URL, Creative-Attribute und Anbietertypen. Das bedeutet, dass Sie zwei Anzeigen, die

  • anders aussehen oder sich anders verhalten.
  • Rendern Sie das Bild in verschiedenen Bildern.
  • Sie werden auf unterschiedliche Weise gerendert (z. B. besteht eine Anzeige aus einem Bild, die andere aus einem Video).

Beim Entwerfen Ihrer Anwendung sollten Sie sich für eine systematische Methode zur Generierung von IDs entscheiden, die für die Art der Creatives sinnvoll ist, die Sie einreichen möchten.

Anzeigenattribute

Google empfiehlt, Creative-Attribute zu deklarieren, um die Eigenschaften und das Targeting Ihrer Anzeige zu beschreiben. Verwenden Sie dazu entweder eine Kombination aus BidResponse.seatbid.bid.apis und BidResponse.seatbid.bid.attr oder die Erweiterung BidResponse.seatbid.bid.ext.attribute. Im Folgenden wird beschrieben, wie Sie Attribute deklarieren:

  • VPAID
    Legen Sie BidResponse.seatbid.bid.apis auf VPAID_1 oder VPAID_2 fest. Für das JSON-Format kann dies auf 1 oder 2 festgelegt werden.
  • MRAID
    Legen Sie für BidResponse.seatbid.bid.apis den Wert MRAID_1 oder 3 für das JSON-Format fest.
  • SIZELESS
    Legen Sie für BidResponse.seatbid.bid.attr den Wert RESPONSIVE oder 18 für das JSON-Format fest.
  • PLAYABLE
    Legen Sie dazu für BidResponse.seatbid.bid.attr den Wert USER_INTERACTIVE oder 13 für das JSON-Format fest.

In der Creative-Ressource erfahren Sie, wie Sie Feedback zu den erkannten Eigenschaften Ihrer Creatives erhalten.

Open Bidding-Felder

Gebotsanfragen, die von Anzeigenplattformen und Netzwerken gesendet werden, die Open Bidding nutzen, ähneln denen von Authorized Buyers, die standardmäßige Echtzeitgebote verwenden. Open Bidding-Kunden können eine kleine Anzahl zusätzlicher Felder angeben. Einige vorhandene Felder können auch anders verwendet werden. Dazu gehören:

OpenRTB Authorized Buyers Details
BidResponse.imp[].pmp.deals[].id BidResponse.ad[].adslot[].exchange_deal_id

Die Deal-ID aus dem Namespace der Anzeigenplattform, die mit diesem Gebot verknüpft und an Publisher gesendet wird.

BidResponse.seatbid[].bid[].ext.exchange_deal_type BidResponse.ad[].adslot[].exchange_deal_type

Der Dealtyp, der Publishern gemeldet wird und sich darauf auswirkt, wie der Deal in der Auktion behandelt wird.

BidResponse.seatbid[].bid[].ext.third_party_buyer_token BidResponse.ad[].adslot[].third_party_buyer_token Token, das verwendet wird, um Informationen zu Endkäufern von Drittanbietern zu identifizieren, wenn die Anzeigenplattform als Open Bidding-Nutzer ein Vermittler ist. Dieser Wert wird vom Drittanbieter-Käufer abgerufen und muss in der Gebotsantwort unverändert an Google übergeben werden.

Empfehlungen

  • Aktivieren Sie persistente HTTPS-Verbindungen (auch als „Keep-Alive“ oder „Verbindungswiederverwendung“ bezeichnet) auf Ihren Servern. Legen Sie das Zeitlimit auf mindestens 10 Sekunden fest. Höhere Werte sind in vielen Fällen von Vorteil. Google prüft dies bei den ersten Latenztests Ihrer Anwendung, da Authorized Buyers Anfragen mit hoher Geschwindigkeit sendet und den Latenzoverhead beim Herstellen einer separaten TCP-Verbindung für jede Anfrage vermeiden muss.
  • Fügen Sie die optionale Impressions-Tracking-URL hinzu, um zu erfassen, wann die Impression gerendert wird, anstatt wann der Bieter den Zuschlag erhält. Aufgrund des Rückgangs zwischen Impressionen und Conversions ergeben sich so genauere Tracking-Statistiken.

  • Der Gebotscode darf keine Abhängigkeiten von veralteten Feldern haben, da dies zu Fehlern bei Geboten führen kann.
  • Fügen Sie BidResponse.seatbid.bid.w und BidResponse.seatbid.bid.h in Ihre BidResponse ein. Ein BidResponse für eine Anfrage mit mehreren Anzeigengrößen muss diese Felder enthalten, da es sonst aus der Auktion ausgeschlossen wird.
  • Begrenzen Sie die Antwortgröße auf unter 8 KB. Sehr große Antworten können die Netzwerklatenz erhöhen und zu Zeitüberschreitungen führen.
  • Beachten Sie die Richtlinien für Gebote für iOS-Inventar, für das eine SKAdNetwork-Attribution erforderlich ist.

Beispiel für eine Gebotsantwort

Die folgenden Beispiele sind lesbare Beispiele für Protobuf- und JSON-Anfragen.

OpenRTB Protobuf

OpenRTB JSON

Google

Wichtig:Die in den Beispielen dargestellten Protobuf-Nachrichten sind hier als visuell lesbarer Text dargestellt. So werden die Nachrichten jedoch nicht über das Netzwerk gesendet. Wenn Sie das Google- oder OpenRTB-Protobuf-Format verwenden, werden nur serialisierte BidResponse-Nachrichten akzeptiert.

Mit dem folgenden C++-Code können Sie eine BidResponse-Nachricht erstellen und serialisieren:

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
}

Creative angeben

In Ihrer Gebotsantwort wird das Creative angegeben, das ausgeliefert werden soll, wenn Ihr Gebot den Zuschlag erhält. Ihr Gebot muss eines der unterstützten Anzeigenformate (AMP, Video, nativ) enthalten. In diesem Beispiel geben wir das Creative über das Feld html_snippet an.

Alternativ können Sie Ihr Creative mit einem der folgenden Felder angeben, je nach Anzeigenformat:

  • SDK-gerenderte Anzeige
    • BidResponse.seatbid.bid.ext.sdk_rendered_ad
  • AMP
    • BidResponse.seatbid.bid.amp_ad_url
  • Video
    • BidResponse.seatbid.bid.adm
  • Native App
    • BidResponse.seatbid.bid.adm_native

Geben Sie im Feld BidResponse.seatbid.bid.adm eine Anzeige an, die auf Ihren eigenen Servern gehostet wird. Verwenden Sie dazu ein HTML-Snippet. Das Snippet ist in einem iFrame enthalten, der in die Webseite eingefügt wird. Dadurch wird die Anzeige beim Laden der Seite abgerufen und gerendert. Das HTML-Snippet muss so erstellt werden, dass die Anzeige (Banner oder Interstitial) in einem iFrame korrekt gerendert wird und die richtige Größe für den Anzeigenblock hat, auf den Sie bieten.

Außerdem muss die in der Gebotsantwort angegebene Anzeigengröße genau mit einer der Größenkombinationen in der Gebotsanfrage übereinstimmen, wenn Folgendes zutrifft:

  • Eine Anzeige ist ein normales Banner (kein Video-, natives oder Interstitial-Anzeigenformat).
  • Der Bieter hat die Größe in der Gebotsantwort angegeben. Eine Größendeklaration ist immer dann erforderlich, wenn die Anfrage mehr als eine Größe enthält.
  • Eine Ausnahme gilt für Interstitial-Anzeigen. Bei Interstitials muss die Breite mindestens 50% der Bildschirmbreite und die Höhe mindestens 40% der Bildschirmhöhe betragen.

Sie können ein HTML-Snippet-Creative mit beliebigem gültigen HTML-Code angeben, der richtig gerendert wird. Beachten Sie jedoch die Einschränkungen bei der Angabe des Felds crid im Abschnitt Create BidResponse-Nachricht. So können Sie beispielsweise zusätzliche Informationen in Argumente der URLs einfügen, die beim Rendern der Anzeige von Ihren Servern abgerufen werden. So können Sie beliebige Daten zur Impression an Ihre eigenen Server zurückgeben.

Die meisten Richtlinien für HTML-Snippets, die in Gebotsantworten zurückgegeben werden, gelten auch für Drittanbieteranzeigen. Weitere Informationen finden Sie in den Richtlinien für das Authorized Buyers-Programm, den Anforderungen für die Anzeigenbereitstellung durch Drittanbieter und unter Anzeigen mit Klick-URLs deklarieren.

Makros angeben

Makros sind formatierter Text, der in einige Felder für Gebotsanfragen eingebettet ist und URLs enthält, die bei der Anzeigenauslieferung durch einen relevanten Wert ersetzt werden. Wenn Ihr erfolgreiches Gebot beispielsweise das Makro AUCTION_PRICE im HTML-Snippet-Creative enthielt, das mit Ihrem Gebot gesendet wurde, wird das Makro durch einen Wert ersetzt, den Sie entschlüsseln können, um den Betrag zu ermitteln, den Sie für die Impression in der Auktion bezahlt haben.

Sie können Makros in die folgenden Felder einfügen:

  • BidResponse.seatbid.bid.adm

    Makros werden für HTML-Snippets, native Formate, Video-URLs und VAST-XML-Videoformate unterstützt.

  • BidResponse.seatbid.bid.adm_native.eventtrackers.url

  • BidResponse.seatbid.bid.adm_native.imptrackers

  • BidResponse.seatbid.bid.ext.amp_ad_url

    Für AMP-Creatives werden nur die Google-spezifischen Makros WINNING_PRICE und WINNING_PRICE_ESC unterstützt.

  • BidResponse.seatbid.bid.burl

  • BidResponse.seatbid.bid.ext.impression_tracking_url

    Verwenden Sie diese URL anstelle von BidResponse.seatbid.bid.burl, wenn Sie mehr als eine Abrechnungs-URL benötigen.

Sie können beispielsweise ein Makro als Teil eines HTML-Snippets einfügen, indem Sie ${MACRO} in die URL einbetten, über die das Creative abgerufen wird. MACRO ist eines der in der OpenRTB-Spezifikation beschriebenen unterstützten Makros.

Google RTB-Makros

Google unterstützt neben den in der OpenRTB-Spezifikation aufgeführten Makros auch zusätzliche Makros. Diese sind anders formatiert und werden in eine URL eingebettet als %%MACRO%% angezeigt. In der folgenden Tabelle werden diese Makros beschrieben:

Makro Beschreibung
ADVERTISING_IDENTIFIER Käufer können beim Rendern von Impressionen die iOS-IDFA oder die Android-Werbe-ID erhalten. Weitere Informationen finden Sie unter Werbetreibenden-IDs entschlüsseln.
CACHEBUSTER Eine Stringdarstellung einer zufälligen, vorzeichenlosen, vier Byte großen Ganzzahl.
CLICK_URL_UNESC

Die nicht maskierte Klick-URL für die Anzeige. Im Snippet sollte direkt nach dem Makro eine entschlüsselte Version der Drittanbieter-Klick-URL folgen.

Wenn die Klick-URL des Drittanbieters beispielsweise http://my.adserver.com/some/path/handleclick?click=clk lautet, könnte der folgende Code mit der einmal ent escapeten Version der Klick-URL des Drittanbieters nach der Makroaufruf verwendet werden:

<a href="%%CLICK_URL_UNESC%%http%3A%2F%2Fmy.adserver.com%2Fsome%2Fpath%2Fhandleclick%3Fclick%3Dclk"></a>

Bei der Anzeigenbereitstellung wird der Creative-Code folgendermaßen erweitert:

<a href="http://google-click-url?...&ad_url=http%3A%2F%2Fmy.adserver.com%2Fsome%2Fpath%2Fhandleclick%3Fclick%3Dclk"></a>

Über die URL wird der Klick zuerst bei Google registriert und dann an die Klick-URL des Drittanbieters weitergeleitet.

CLICK_URL_ESC

Die URL für Klicks auf die Anzeige, die mit einem Escape-Zeichen versehen ist. Verwenden Sie dieses Makro anstelle von CLICK_URL_UNESC, wenn der Wert zuerst an einen anderen Server übergeben werden muss, der dann eine Weiterleitung zurückgibt.

Der folgende Code könnte beispielsweise in einem HTML-Snippet verwendet werden:

<a href="http://my.adserver.com/click?google_click_url=%%CLICK_URL_ESC%%"></a>

Bei der Anzeigenbereitstellung wird der Creative-Code folgendermaßen erweitert:

<a href="http://my.adserver.com/click?google_click_url=http://google-click- url%3F...%26ad_url%3D"></a>

Dadurch wird der Klick bei my.adserver.com registriert, das dann für die Weiterleitung an die im Parameter google_click_url übergebene URL verantwortlich ist. Dabei wird davon ausgegangen, dass my.adserver.com den Parameter google_click_url entwirft.

Sie können nach %%CLICK_URL_ESC%% eine doppelt doppelte URL-Escaping-Zeichenfolge anhängen. Nachdem die Entfernung der Escape-Sequenzen durch my.adserver.com abgeschlossen ist, bleibt eine einzelne Escape-Version der URL übrig, die an google_click_url angehängt wird. Wenn die google_click_url abgerufen wird, wird sie noch einmal entescaped und dann weitergeleitet.

CLICK_URL_ESC_ESC

Die doppelt maskierte URL für die Anzeige. Verwenden Sie dieses Makro anstelle von CLICK_URL_UNESC, wenn der Wert zuerst an einen anderen Server übergeben werden muss, der dann eine Weiterleitung zurückgibt.

Der folgende Code könnte beispielsweise in einem HTML-Snippet verwendet werden:

<a href="http://my.adserver.com/click?google_click_url=%%CLICK_URL_ESC_ESC%%"></a>

Bei der Anzeigenbereitstellung wird der Creative-Code folgendermaßen erweitert:

<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 Wird auf http: erweitert, wenn für die Gebotsanfrage kein SSL erforderlich ist, oder auf https:, wenn für die Gebotsanfrage SSL erforderlich ist.
SITE Die Domain mit maskierter URL der Content-URL oder bei anonymem Inventar die anonyme ID.
SITE_URL Verworfen. Wurde durch das SITE-Makro ersetzt, das dieselbe Funktionalität bietet.
TZ_OFFSET Die Zeitzonenverschiebung.
VERIFICATION

Die verschiedenen Werte für die Produktion und für das Scannen des Creatives in der Bestätigungspipeline. Das Format lautet: %%?VERIFICATION:true-val:false-val%%. Dabei können für true-val und false-val beliebige Werte verwendet werden, mit Ausnahme von Makros, einschließlich leerer Strings. Für Open Bidding empfehlen wir Anzeigenplattformen, dieses Makro zu verwenden. In diesem Fall müssen auf Nachfrageseite keine Änderungen vorgenommen werden.

Wenn ein Creative beispielsweise %%?VERIFICATION:-1:5000%% enthält, ist der Textersatz beim Ausliefern 5000 und in der Überprüfungspipeline -1. So können Sie diese beiden Pings unterscheiden.

WINNING_PRICE

Die codierten Kosten für die Impression (das heißt CPI statt CPM) in millionstel Einheiten der Kontowährung. Ein erfolgreiches CPM-Gebot von 5 US-Dollar entspricht 5.000.000 Millionstel CPM oder 5.000 Millionstel CPI. Der decodierte Wert von WINNING_PRICE wäre in diesem Fall 5.000. Der Gewinnerpreis wird in CPI angegeben.

Um dieses Makro zu parsen, müssen Sie eine Anwendung implementieren, die Preisbestätigungen entschlüsselt. Weitere Informationen finden Sie auf der Seite Preisbestätigungen entschlüsseln.

WINNING_PRICE_ESC WINNING_PRICE mit URL-Escaping

Google verlangt, dass Sie im Creative der vom Drittanbieter ausgelieferten Anzeige entweder das CLICK_URL_UNESC- oder das CLICK_URL_ESC-Makro verwenden. Google verwendet die CLICK_URL-Makros für das Klick-Tracking.

Für die URL-Escaping-Funktion in Makros wird das folgende Schema verwendet:

  • Das Leerzeichen wird durch ein Pluszeichen (+) ersetzt.
  • Alphanumerische Zeichen (0–9, a–z, A–Z) und Zeichen aus dem Satz !()*,-./:_~ bleiben unverändert.
  • Alle anderen Zeichen werden durch %XX ersetzt, wobei XX die Hexadezimalzahl ist, die für das Zeichen steht.

Einschränkungen und Anforderungen für Publisher

Die Gebotsanfrage enthält Informationen zu den Einschränkungen und Anforderungen, die Publisher an Creatives in der Auktion stellen.

  • BidRequest.bcat
    • Sie können die in diesem Feld angegebenen blockierten Kategorien mit denjenigen vergleichen, die für Ihre eingereichten Creatives im Feld detectedCategories der Real-time Bidding API erkannt wurden.
  • BidRequest.imp.ext.allowed_vendor_type
  • BidRequest.imp.secure
    • In der Praxis wird diese Einstellung immer auf true festgelegt, da Google SSL-Unterstützung für alle Creatives erfordert.
  • BidRequest.imp.{audio/banner/native/video}
  • BidRequest.imp.{audio/banner/native/video}.api
  • BidRequest.imp.{audio/banner/native/video}.battr
  • BidRequest.imp.{audio/banner/video}.mimes

Geben Sie niemals Gebote für Anzeigen ab, die eine eingeschränkte Funktion enthalten. Bei zulässigen Funktionen wie dem Anbietertyp darf eine Anzeige nur zurückgegeben werden, wenn der Anbietertyp in der Liste allowed_vendor_type in BidRequest enthalten ist. Nur Anzeigenformate, die in der Gebotsanfrage durch Ausfüllen von Feldern wie BidRequest.imp.banner angegeben sind, sollten in Ihr Gebot aufgenommen werden. Weitere Informationen finden Sie in den Kommentaren zu diesen Feldern in der BidRequest-Protokoll-Bufferdefinition.

Wenn eine Anzeige in BidResponse zurückgegeben wird, müssen Sie die Felder BidResponse.seatbid.bid.attr, BidResponse.seatbid.bid.cat und entweder BidResponse.seatbid.bid.adomain oder BidResponse.seatbid.bid.adm_native.link.url in BidResponse korrekt festlegen. Wenn für eine Anzeige mehrere Werte für diese Felder gelten, müssen Sie alle angeben. Weitere Informationen finden Sie in den Kommentaren zu diesen Feldern in der BidResponse-Protokollpufferdefinition. Antworten, für die diese Felder nicht festgelegt sind, werden verworfen.

Open Measurement

Mit Open Measurement können Sie Drittanbieter angeben, die unabhängige Analyse- und Überprüfungsdienste für Anzeigen in mobilen App-Umgebungen anbieten.

Zu den unterstützten Anzeigenformaten gehören Video-, Banner- und Interstitial-Anzeigen. Weitere Informationen zur Verwendung von Open Measurement in einer Gebotsantwort, die diese Formate enthält, finden Sie im Hilfeartikel Open Measurement SDK.

Beispiel für Gebotsantworten

In den folgenden Abschnitten finden Sie Beispielgebotsantworten für verschiedene Anzeigentypen.

App-Banner

OpenRTB Protobuf

OpenRTB JSON

Google

App-Interstitial

OpenRTB Protobuf

OpenRTB JSON

Google

Video-Interstitial in Apps

OpenRTB Protobuf

OpenRTB JSON

Google

Native App

OpenRTB Protobuf

OpenRTB JSON

Google

Webvideo

OpenRTB Protobuf

OpenRTB JSON

Google

Mobiles Webbanner für Bieter auf Anzeigenplattform

OpenRTB Protobuf

OpenRTB JSON