Server zu AdServer Anfrage mit JSON Antwort

Owned by Björn Militzer
Last updated: Feb 22, 2021
3 min read

Bei einer direkten Verbindung zwischen einem Fremdserver (zb CMS) und dem AdServer, wird das JSON Format als Kommunikationsstandard verwendet.
Der Fremdserver schickt im Namen eines Benutzers (Client) die Anfrage und fungiert als Schnittstelle zwischen Clienten und AdServer,

Um den Benutzer dennoch eindeutig zu identifzieren und Funktionen wie Frequency Capping zu ermöglichen, muss der Fremdserver für jede Anfrage des selben Clients eine eindeutige ID verwenden (Publisher Provided ID).
Diese ID muss mindestens 14 Tage gespeichert und wieder für den Clienten wieder verwendet werden, erst da nach darf der Fremdserver eine neue ID für den Clienten generieren.
Sollte der Fremdserver diese Funktionalität nicht besitzen, ist eine Server zu AdServer Anfrage leider nicht möglich.

Der AdServer sendet als Antwort grundsätzlich einen ResponseHeader mit dem Status "200/OK" und dem Mime Type "application/json", solange die Anfrage wohlgeformt wurde.

Der Fremdserver muss überprüfen ob die Antwort ein valides JSON ist, und ob die JSON Antwort tatsächlich Daten enthält.
Falls der AdServer keine derzeitig aktiv, gebuchte Kampagne liefern kann, wird ein leeres JSON Object geliefert " { } "


Anfrage

Protokoll: https://

Hostname: pubads.g.doubleclick.net

Service: gampad/adx

Parameter:

  • iu - Identifizierung der AdUnit/Platzierung im AdServer. Wird durch Ströer vorgegeben.
    Beispiel: iu=/4444/website.de_sd/jsonad

  • sz - Anzufragende Pixelgröße des Werbemittels. Wird durch Ströer vorgegeben.
    Beispiel: sz=728x90 für eine Größe oder sz=728x90|120x600 für mehrere Größen

  • c - Cachebuster um die Antwort des AdServers nicht im Browser Cache zu speichern. Max 10-stellige Zufallszahl. Muss durch Fremdserver generiert werden
    Sollte der Fremdserver mehre Anfragen zeitgleich für den selben Clienten absenden (zb.: für mehrere zu füllende Positionen), so muss bei allen Anfragen der gleiche Cachebuster Wert verwendet werden.
    Beispiel: c=5496134897

  • tile - Definiert die Position des Werbemittels auf dem Clienten. Ganzzahl die für jede zusätzliche Position hochgezählt wird. Muss durch Fremdserver errechnet werden.
    Beispiel: tile=1 für die erste Position, tile=2 für die zweite Position

  • d_imp - Definiert wann eine Impression gezählt und (vor dem Werbekunden) abgerechnet werden soll. Wert ist immer 1
    Beispiel: d_imp=1

  • m - Mime Type. In der Regel application/json
    Beispiel: m=application/json

  • gdpr - Definiert ob für den Nutzer die DSGVO gilt und Datenverarbeitung entsprechend der DSGVO zustimmungspflichtig ist. 1 bedeutet Ja, 0 bedeutet Nein. Wir raten dringend zu einer fachgerechten Rechtsberatung, um zu klären für welche Nutzer Sie als Publisher die DSGVO anzuwenden haben.
    Beispiel: gdpr=1

  • gdpr_consent- Übergibt die Zustimmung / Ablehnungen des Nutzers zur Datenverarbeitung unter der DSGVO als base64-encodierte Zeichenkette. Die Zeichenkette wird durch Ihre Consent Management Plattform (CMP) auf Basis des IAB Transparency & Consent Frameworks generiert. Bitte wenden Sie sich an den Betreiber Ihrer CMP, um zu erfahren wie dieser sog. "tcString" aus der CMP abrufbar ist.

    Beispiel: gdpr_consent=CPA8PaWPA8PaWAfabBDEBLCgAPHAAHHAAAigF5wBwAWQCIAIkATABigDWAJBAXmBecAcAFkAiACJAEwAYoA1gCQQF5g
    Hinweis: Der "tcString" kann je nach Einstellungen auf Ihrer Webseite sehr lang werden (bis zu 1.400 Zeichen). Stellen Sie bitte sicher das Ihr Server solch komplexe Requests zulässt und bearbeiten kann.

  • ppid - Anonymisierte Id für den Clienten, welche durch den Fremdserver generiert wird. Muss 14 Tage für denselben Clienten bei allen Anfragen gleich sein. Für einen neuen / unbekannten Client muss eine neue ppid geniert wird.
    Die ID muss desweiteren: 

    1. alphanumerisch sein, also nur die Zeichen 0–9, a–z und A–Z enthalten

    2. mindestens 32 Zeichen umfassen

    3. höchstens 150 Zeichen lang sein

    4. auf allen Geräten gleich sein

    5. gehasht sein. Senden Sie uns auf keinen Fall eindeutig, zuweisbare Daten, die auf die Identität des Users schließen lassen (z.B.: eine Emailadresse)

  • t - Zusätzliche Targetings, die Informationen oder Daten zu dem Clienten oder dem Fremdserver vermitteln.
    Es kann ein sogenanntes Key / Value Paar übergeben werden. Weitere Key / Value Paare sind möglich und werden mit einem ASCI codierten & (%26) verknüpft.
    Der Key wird von dem Value per ASCI codierten = (%3D) getrennt. Mehrere Values für einen Key werden mit dem ASCI codierten , (%2C) verknüpft.
    Folgende Zeichen sind in Schlüssel/Wert-Paaren nicht zulässig: " ' ! + # * ~ ; ^ ( ) < > [ ] = . Leerzeichen sind zwar in Werten erlaubt (als %20 oder + maskiert), in Schlüsseln sind sie jedoch nicht zulässig.

    Beispiel:  t=interesse%3Dsport%2Cnews%26age%3D25-34 (Der Key "interesse" enthält die Values "sport" und "news", der weitere Key "age" enthält ein Value "25-34")
    • age - Alter des Clienten
      55-up, 45-54, 35-44, 25-34, 18-24, 13-17 (soweit vorhanden)
    • gender - Geschlecht des Clienten
      m, f, u
    • deviceclass - Device Klasse des Clienten
      s, m, l, xl (Smartphone, Tablet, Desktop, 4K Display)
    • deviceos - OS des Clienten
      win,mac,ios,lin,and (Windows, MacOS, iOS, Linux, Android)
    • deviceid - IDFID oder AdId des mobilen Devices (falls vorhanden)
    • deviceclient - Zugangsart des Clienten
      browser, app (Browser, App)
    • PLZ - 5 stellige Postleitzahl des Clienten
    • country- Englische Abkürzung für den Namen des Staates aus dem der Client zugreift
      ger, fr, usa
    • tagm - Benutzer TagManager, immer no
      no

Beispielanfrage:

https://pubads.g.doubleclick.net/gampad/adx?iu=4444/website.de_sd/jsonad&sz=225x40&c=1234567890&m=application/json&tile=1&d_imp=1&gdpr=1&gdpr_consent=CPA8PaWPA8PaWAfabBDEBLCgAPHAAHHAAAigF5wBwAWQCIAIkATABigDWAJBAXmBecAcAFkAiACJAEwAYoA1gCQQF5g&ppid=12JD92JD8078S8J29SDOAKC0EF230337&t=age%3D35-44%26gender%3Dw%26devicetype%3Ds%26tagm%3Dno%26plz%3D12345%26country%3Dger%26deviceclient%3Dapp%26deviceid%3D201F2EB1-8041-9E39-CD07-FCBBA5A29B41


Antwort

Der AdServer sendet immer eine Antwort von "200/OK" solange die Anfrage wohlgeformt wurde.
Falls keine derzeit gebuchte Kampagne verfügbar ist wird immer ein leeres JSON Object geliefert " { } ".


Datenschutz
Impressum