Empfehlung Workflow Anbindung einer externen Anzeigenproduktion über die Ad API an den PEIQ Werbemarkt

Die hier referenzierte PEIQ Ad API befindet sich noch im Modus Beta und ist teilweise noch “work in progress”

Abfrage der Nummern der zuletzt geänderten Anzeigen und Aufträge

Über den Endpunkt /ads/events (Feed-orientiert) kann sich eine externe, technische Anzeigenproduktion die Auftrags- und Anzeigennummern der seit dem letzten offset (beim ersten mal ohne offset) neuen/geänderten Anzeigen und Aufträgen abrufen.

Wenn beim Parameter “eventName” der Wert “production” übergeben wird, dann werden nur als produktionsrelevant definierte Änderungen an Auftrag und Anzeige berücksichtigt.

Mit dem Ergebnis wird ein Offset zurückgegeben, der beim nächsten Aufruf wieder mitgegeben werden kann, um dann wieder nur die seit dem letzten Abruf geänderten zu erhalten.

Abfrage der benötigten Daten von Anzeigen und Aufträgen

Mit den bei /ads/events erhaltenen Nummern können die Daten der zugehörigen Elemente abgefragt werden:

Anzeigen: GET /ads/{number}

Aufträge: GET /orders/{number}

Informationen vom zugehörigen Geschäftspartner können über GET /businesspartners/number abgefragt werden. Die Nummer des zugehörigen Geschäftspartners ist unter GET /orders/number im Element “business_partner” enthalten.

Unmittelbar nach dem Abholen der Anzeigendaten über die API liefert die technische Anzeigenproduktion mit "PUT ads/{number}" den beim Abrufen zuletzt erhaltenen Timestamp (production_timestamp) im Feld production_status_timestamp als Quittierung, sowie optional den Produktionsstatus (production_status) und eine optionale textuelle Info (production_note) zurück.

Rückmeldung Anzeigendaten im Verlauf der Anzeigenproduktion

Zwischenzeitlich können weitere Parameter über PUT /ads/{number} gesetzt werden. So kann der “production_status” mit “production_status_timestamp” (entspricht immer dem Wert in production_timestamp bei der letzten Abholung) entsprechend auf “Produktion” gesetzt werden, wenn das Anzeigenmotiv produziert wird. Und “Fertig”, wenn die Anzeige fertig produziert und das Motiv hochgeladen ist. Weitere typische Parameter sind Update anderer Produktionsdaten zu einer Anzeige: height_booked_mm (bei variabler gebuchter Höhe), production_note (textuelle Info). Diese Felder können einzeln selektiv aktualisiert werden.

Der “production_status” muss dabei spätestens auf “Fertig” gesetzt werden, wenn Anzeige fertig produziert ist. Dabei muss der zurückgemeldete production_status_timestamp mit dem zuletzt abgeholten Zeitstempel übereinstimmen, ansonsten kann die Anzeige im PEIQ Werbemarkt (NGen) nicht in den Anzeigen-Status “Fertig” gehen und die Seiten, auf denen die Anzeige platziert ist, nicht produziert werden.

Bei Übergabe des production_status “Fertig” erfolgt eine Validierung des production_status_timestamp.

Der übergebene “production_status_timestemp” (PUT) muss dem production_timestamp (GET) entsprechen.

Es wird generell empfohlen, den aktuellen Stand der Anzeige vor jeder Rückmeldung noch einmal abzufragen und und zu prüfen, ob anhand des Timestamp die Stände noch zusammenpassen.

Übermitteln des Anzeigenmotive (PDF)

Der Upload eines Motivs der Anzeige erfolgt binär (octet-stream) über

PUT /ads/images/{number}

Die PDFe sind im CMYK-Farbmodell zu übermitteln.

NGen prüft die formale Validität des PDF und liest die tatsächliche Größe aus. Passende Bildschirmauflösungen werden automatisch erzeugt.

Es wird empfohlen, die letzte gültige Version des Anzeigenmotivs (PDF) vor dem Setzen des “production_status” auf Fertig, die endgültige Version des Anzeigenmotivs zu übermitteln.