AdSpirit RTB API

AdSpirit RTB API (Stand 02.08.2011)
1.
Dieses Dokument
Dieses Dokument beschreibt die Nutzung der AdSpirit RTB API aus Sicht des AdSpirit Nutzers. Sofern Sie nicht selbst
AdSpirit-Kunde sind lesen Sie dieses Dokument bitte aus Sicht des Publishers bzw. des Werbekunden.
2.
RTB-Usermatching (Bidder)
Beim Usermatching für Bieter werden alle Nutzerinformationen die AdSpirit über den Nutzer besitzt an den Partner
übermittelt. Sobald dieser Partner dann ein Gebot von AdSpirit einfordert muss der Partner mit der Gebotsanforderung
die Nutzerdaten mit übermitteln, sodass AdSpirit auch ohne direkten Kontakt zum Nutzer dennoch alle Informationen
besitzt.
2.1.
Wie funktioniert das Usermatching für Bieter?
Für alle Anfragen die der Publisher an AdSpirit sendet sollte zuvor beim Publisher ein Nutzerprofil angelegt werden. Nutzer die über noch kein Nutzerprofil verfügen sollte der Publisher bei AdSpirit um ein Nutzerprofil anfragen. Hierzu wird
das Usermatching verwendet um die Nutzerdaten von AdSpirit an den Publisher zu übergeben. Der Publisher bindet dazu bei allen neuen Nutzern einen Pixel-Code mit einer AdSpirit-URL ein. Mittels des Pixel-Codes wird an AdSpirit die Anfrage geschickt Nutzerdaten zu erhalten. Als Resultat zu dieser Anfrage wird AdSpirit an den Publisher die Nutzerdaten
zu diesem Nutzer senden.
2.2.
Request Ablauf
Generieren Sie im Menüpunkt "RTB-Usermatching" einen Usermatching-Code. Dieser besteht aus folgenden Parametern:
umid=
ID des Usermatching-Codes
dataid=
ID die AdSpirit beim Publisher besitzt
userid=
ID des Nutzers beim Publisher
redirecturl=
Callback-URL
call_type=
Callback-Typ
Generieren Sie diese URL und schicken Sie diese an den Publisher bei dem Sie den Traffic einkaufen.
Der Publisher bindet diese URL in einen 1x1 Pixel ein und zeigt ihn jedem neuen Nutzer.
Bei jeder Einblendung der URL/des Pixels ersetzt der Publisher die Platzhalter durch die jeweiligen Informationen.
2.3.
Response
Wird die Anfrage vom Nutzer an den AdSpirit AdServer geschickt antwortet dieser mit einer Weiterleitung an die als
Callback-URL übergebene Zielseite. Hierbei hängt AdSpirit folgende URL-Parameter an die Callback-URL an:
dataid=
ID die AdSpirit beim Publisher besitzt
user_id=
ID des Nutzers beim Publisher
external_user_id=
ID des Nutzers bei AdSpirit
Fehler! Verweisquelle konnte nicht gefunden werden.
Seite 1 / 5
Darüber hinaus übermittelt AdSpirit eine Reihe von Nutzerrelevanten Daten. Diese werden mit weiteren Parametern
übergeben und beginnen jeweils mit "custom_".
Die Daten die AdSpirit so an den Publisher übermittelt (external_user_id sowie custom_*-Parameter) muss
muss der Publisher
nun bei jeder Gebotsanfrage an AdSpirit mit übermitteln: external_user_id als HTTP-Parameter X-RTB-UserID und custom_*-Parameter als HTTP-Cookies. Die Namen der Cookies werden dabei ohne "custom_" ausgeführt (d.h. aus Parameter "custom_abc=123" wird Cookie "abc=123").
3.
RTB-Usermatching (Seller)
Das Usermatching für Seller ermöglicht es dem Werbekunden der bei Ihnen via RTB Einblendungen einkaufen möchte
seine Nutzerdaten an Sie (AdSpirit) zu übermitteln. Hierdurch ist AdSpirit in der Lage bei einer Gebotsanfrage an den
Werbekunden diesem die Nutzerdaten zurück zu geben, sodass der Werbekunde auf Basis dieser Daten genauere Gebote abgeben kann.
3.1.
Ablauf
Der Ablauf entspricht dem Usermatching für Bieter: Zunächst wird vom Werbekunden eine URL an Sie übermittelt. In
diese URL werden durch entsprechende Platzhalter Daten eingefügt. Trifft ein neuer Nutzer auf AdSpirit wird AdSpirit
diesem Nutzer einen 1x1 Pixel zeigen in dem die URL des Werbekudnen enthalten ist. Damit wird an diesen die Anfrage
gesendet den Nutzer zu identifizieren. Der Werbekunde wiederum antwortet damit dass er die Daten in Form eines
HTTP-Redirects an AdSpirit zurück sendet.
3.2.
Request Ablauf
Als erstes benötigen Sie vom Werbekunden eine Usermatching-URL, diese Hinterlegen Sie beim RTB-Werbemittel.
Außerdem weisen Sie dem Werbemittel einer Usermatching-Datenbank zu.
Innerhalb der Usermatching-URL können Sie folgende Platzhalter verwenden um die jeweiligen Daten an den Werbekunden zu senden:
%dataid%
(notwendig) ID der Usermatching-Datenbank
%redirect%
(notwendig) Callback-URL an die der Werbekunde die Daten senden soll
%userid%
(notwendig) ID des Nutzers bei AdSpirit
%calltype%
(optional) Typ wie der Werbekunde die Daten senden soll (js, iframe, redirect)
AdSpirit wird nun alle nicht abgeglichenen Nutzer an diese Usermatching-URL senden und damit um Datenabgleich bitten.
3.3.
Response Ablauf
Erhält der AdServer des Werbekundens die Anfrage zum Datenabgleich von AdSpirit antwortet dieser damit, die folgenden Parameter an die als %redirect% übergebene Callback-URL anzuhängen:
dataid=
(notwendig) ID der Usermatching-Datenbank (%dataid%)
user_id=
(notwendig) ID des Nutzers bei AdSpirit (%userid%)
external_user_id=
(notwendig) ID des Nutzers beim Werbekunden
custom_*=
(optional) weitere Nutzerinformationen. AdSpirit wird die Nutzerdaten mit jeder Gebotsanfrage als
HTTP-Cookies mitsenden. Der Name des Cookies wird dabei ohne "custom_" geschrieben (d.h. aus Parameter "&custom_abc=123" wird Cookie "abc=123").
Der AdServer des Werbekunden muss diese Callback-URL je nach Wert des Parameters %calltype% wie folgt ausgeben:
js
document.write('<div style="position:absolute; left:0px; top:0px;"><img border="0" width="1" height="1"
alt="" src="[CALLBACK-URL]" /></div>');
Fehler! Verweisquelle konnte nicht gefunden werden.
Seite 2 / 5
iframe
<html><body><div style="position:absolute; left:0px; top:0px;"><img border="0" width="1" height="1"
alt="" src="[CALLBACK-URL]" /></div></body></html>
redirect
PHP-Code: header('Location: [CALLBACK-URL]');
4.
AdSpirit Bidder Request API
AdSpirit erwartet bzw. sendet einen Request in Form eines HTTP-GET Befehls. Als Parameter können alle üblichen Parameter gesetzt werden die auch von normalen Scrip-/IFrame-Codes für Werbeflächen unterstützt werden (z.B. rdclick,
exttrack, ...). Außerdem kann der Parameter &rtbprovider=... gesetzt werden - er beschreibt den Ausgabetyp des AdSpirit Bidder Response. Mögliche Werte für diesen Parameter finden Sie unten.
Hinweis: Der Parameter notdm wird von der Bidder-API automatisch gesetzt. Dies bedeutet, dass über RTBWerbemittel verknüpfte Werbemittel ausgeliefert werden können.
Um dem AdSpirit Server die nötigen Informationen über den Nutzer der die Werbeeinblendung erhalten soll mitzuteilen,
müssen vom verkaufenden/Gebots-einholenden RTB-Server alle nötigen Informationen via HTTP-Header übertragen werden (sofern &rtbprovider=adspirit). Folgende Header-Informationen werden u.a. benötigt bzw. von AdSpirit bei der Gebotsanfrage versandt:
X-Forwarded-For
IP-Adresse des Nutzers
User-Agent
Browser-String des Nutzers
Accept-Language
Sprache des Nutzers
Referer
URL/Referer auf dem die Werbung erscheinen soll
UA-Pixels
Größe des Nutzerschirms (Schreibweise: 123x456)
UA-OS
Betriebssystem des Nutzers
Geo-Position
Geo-Koordinaten des Nutzers in Lat/Lon (Schreibweise: 123.23, -62.14)
Geo-Country
Ländercode in dem der Nutzer sich aufhält (ISO 3166-1)
X-RTB-Floorprice
Mindestpreis den der Publisher für diese Einblendung erhalten möchte. Ist der Parameter gesetzt und
größer als 0 werden nur Gebote abgegeben wenn der Gebotspreis über diesem Preis liegt.
X-RTB-Pid
Eindeutige ID für die Werbefläche des Publishers. Anhand dieser ID werden verschiedene Werbeflächen
unterschieden. Die ID wird in AdSpirit als SubID übernommen. Sofern die ID nicht gesetzt ist wird stattdessen der Referer gespeichert und aus diesem eine automatische SubID errechnet (sofern bei der Werbefläche "Referrer prüfen" aktiviert ist). Es ist daher wichtig dass ein (fremder) Publisher entweder immer Referer
oder immer X-RTB-Pid übermittelt (oder beides) aber nie dazwischen hin und her wechselt.
X-RTB-RequestID
Eindeutige ID des Requests.
X-RTB-UserID
Eindeutige ID des Nutzers aus Publishersicht (vgl. Parameter &external_user_id=... aus Usermatching-API
(Bidder) )
X-RTB-PriceEnc
sofern gesetzt muss der Bieter zur Preisübermittlung eine separate URL verwenden
Darüber hinaus erwartet AdSpirit alle als custom_* übermittelten Nutzerdaten zu diesem Nutzer in Form von HTTPCookieinformationen.
Fehler! Verweisquelle konnte nicht gefunden werden.
Seite 3 / 5
5.
AdSpirit Bidder Response API
Sofern der Parameter rtbprovider=adspirit gesetzt ist oder der Parameter weggelassen wird, antwortet AdSpirit bzw der
bietende AdServer mit einem Response im AdSpirit Bidder Response Format. Hierbei wird ein Text übermittelt der je eine
Information pro Zeile enthält. Eine Zeile muss jeweils durch \r\n (Zeichencodes #13#10) beendet werden. Jede Zeile besteht aus einem Name=Wert Paar. Folgende Name=Wert-Paare werden u.a. übermittelt:
cpm
Float. Gebotswert in der im AdServer eingestellten Währung aber ohne Währungsangabe z.B. 0.67
requestid
Zahl. ID des Requests
wmid
Zahl. ID des gelieferten Werbemittels
url
String. Ziel-URL auf die das Werbemittel verweist.
default
String urlcodiert. Zusätzlicher Trackingcode der vom Publisher angezeigt werden soll wenn AdSpirit nicht den
Zuschlag für diese Einblendung erhalten hat.
priceurl
String urlcodiert. Sofern beim Request der HTTP Header X-RTB-PriceEnc gesetzt war muss hier eine URL zur
Preisübermittlung übergeben werden. Der AdServer verwendet diese URL in einem 1x1 Pixel. Als Platzhalter für
die Stelle an der der Preis eingetragen werden soll sollte %RTB_PriceEnc_A% verwendet werden. (siehe unten)
code
String urlcodiert. Werbemittel-Code der angezeigt werden soll, wenn AdSpirit vom Publisher den Zuschlag erhält.
Je nach Typ der Anfrage, gebuchten Werbemittel usw. können weitere Name=Wert-Paare hinzukommen um weiterführende Informationen zu ermöglichen.
6.
Klicktracking / Klickmacros
Ebenso wie bei normalen IFrames / Script-Codes kann auch beim RealTime Bidding Klicktracking erfolgen. Hierzu wird an
die RTB-Request-URL der entsprechende Parameter &rdclick= / &rdclick_0= / &rdclick_1= / ... (vgl. externes Klicktracking bei IFrames/Scripts) angehangen.
Da es sich beim RTB um die Weiterleitung des Werbemittels handelt und nicht um eine direkte Auslieferung an den Nutzer kann hier anstelle der Klick-URL auch der Klick-Macro des jeweiligen AdServers angehangen werden (z.B.
&rdclick_0=%%CLICK_URL_ESC%% bei DoubleClick).
7.
Preisbenachrichtigung
AdSpirit unterstützt die Möglichkeit den Gewinner der RTB-Auktion den Gewinnpreis mitzuteilen. Ebenso ist es möglich
dass AdSpirit Preisbenachrichtigungen für gewonnene Auktionen entgegen nimmt bei denen mitgeboten wurde.
7.1.
Preisübermittlung
Der Gewinnpreis wird innerhalb von AdSpirit mit dem Parameter &prenca= und &prencm= innerhalb der ViewtrackingURL übermittelt. Darüber hinaus kann in einigen Fällen der Platzhalter %RTB_PriceEnc_A% verwendet werden um an einer anderen Stelle als der Viewtracking-URL den Preis zu übermitteln. Um hierbei vor Manipulation zu schützen wird der
Preis verschlüsselt und besitzt eine eingeschränkte Gültigkeitsdauer (in der Regel +/- 10 Minuten).
7.2.
Preisübermittlung aktivieren
Um die Preisübermittlung zu aktivieren muss dazu innerhalb der Werbefläche bzw. des Werbemittels, für das die Preisübermittlung aktiviert werden soll, die Einstellung RTB-Preisübermittlung aktiviert werden sowie ein Encryption-Key und
ein Integrity-Key hinterlegt werden. Der Encryption-Key und der Integrity-Key müssen dem Publisher/Advertiser mitgeteilt
und bei diesem ebenfalls hinterlegt werden.
Bitte beachten Sie: Sobald die Preisübermittlung aktiviert ist, wird dadurch die normale Abrechnung/Vergütung des
Werbemittels bzw. der Werbefläche überschrieben. Die in der Kampagne eingetragenen Werte gelten dann lediglich als
Maximalgebot für die RTB-Gebotsabgabe.
Fehler! Verweisquelle konnte nicht gefunden werden.
Seite 4 / 5
7.3.
Preisverschlüsselung
Die Verschlüsselung der Preise erfolgt anhand des vom Google AdExchange verwendeten Algorithmus. Hierbei wird der
Preis, ein aktueller Zeitstempel sowie die zwei hinterlegten Schlüssel via SHA1 Verfahren verschlüsselt bzw. wieder entschlüsselt. Der Pseudocode zur Verschlüsselung der Werte sieht wie folgt aus:
iv = InitializatioVector (16 Byte)
e_key = encryption Key (32 Byte)
i_key = integrity Key (32 Byte)
price = Preis in Millionstel (8 Byte)
pad = sha1(e_key, iv) // first 8 bytes
enc_price = pad <xor> price
signature = sha1(i_key, price || iv) // first 4 bytes
final_message = WebSafeBase64Encode( iv || enc_price || signature )
Der Pseudocode zur Entschlüsselung sieht wie folgt aus:
enc_price = WebSafeBase64Decode(final_message)
(iv, p, sig) = dec_price -- split up according to fixed lengths
price_pad = sha1(e_key, iv)
price = p <xor> price_pad
conf_sig = sha1(i_key, price || iv)
success = (conf_sig == sig)
Die Datumsinformationen sind dabei innerhalb der ersten 8 Byte der verschlüsselten Nachricht enthalten.
Fehler! Verweisquelle konnte nicht gefunden werden.
Seite 5 / 5