Anmelden

Willkommen in unserem Support Center

Hier erhalten Sie Hilfe zu Integration und Live-Kampagnen.

Willkommen in unserem Support Center. Hier erhalten Sie Hilfe zu Integration und Live-Kampagnen.

Criteo Resellers Program API — Leitfaden V2.0

 

Guide Change Log

Version

Veröffentlichungsdatum

Ändern

V1.0 November 2017 Erste Version veröffentlicht.
V1.1 März 2018 Impressions-Ebene im Reporting zum Guide hinzugefügt.
V1.2 September 2018 Neue Filteroptionen zum Guide hinzugefügt.
V2.0 September 2018

Vorschau auf die V2 des API-Guides, so das unsere Kunden sich entsprechend organisieren können. Dieser Guide umfasst auch Informationen zum neuen Feature " Tagesbudget".

 

 

Über dieses Dokument

Dieses Dokument führt Sie durch die Integration der Criteo REST API. Dank unserer neuen API V2 sind Sie nun in der Lage, Criteo Reseller Programm Kampagnen im Namen Ihrer Verkäufer durchzuführen. Diese Dokumentation erläutert Ihnen die Änderungen, die Sie für die Verwendung der API V2 vornehmen müssen. 
 
Mit den Features, die Ihnen unsere API bietet, können Sie im Namen Ihrer Verkäufer unter anderem folgende Aufgaben übernehmen:
  • Budgets erstellen und aktualisieren
  • Gebote erstellen und aktualisieren (CPC)
  • Verkäufer stoppen
  • Statistiken zu Ihren Verkäufern erhalten

Erste Schritte 

Zur Nutzung unserer REST API müssen Sie im Management Center einen neuen API-Nutzer erstellen. Sie finden diese Plattform hier: https://marketing.criteo.com/

Führen Sie nach der Anmeldung folgende Schritte aus:

  • Klicken Sie auf Einrichten > Nutzer.

 

 

  • Klicken Sie auf API-NUTZER ERSTELLEN

 

  • Anschließend müssen Sie eine Kontakt-E-Mail-Adresse eingeben und eine der folgenden Rollen auswählen: Nur Lesezugriff, Business Manager oder Finanzverantwortlicher. Zur Nutzung der API wählen Sie bitte den Business Manager aus. Die Rollen Nur Lesezugriff und Finanzverantwortlicher verfügen über keine ausreichenden Rechte zum Ein- und Auslesen von Daten über unsere API.
  • Klicken Sie danach auf Nutzer hinzufügen. Sie sehen eine Bestätigung sowie Ihre Client ID und das Client Secret. Speichern Sie diese unbedingt, denn Sie brauchen die Daten zum Senden von Anfragen an unsere API.

currency

Alle in der Criteo REST API dargestellten Beträge werden in Ihrer lokalen Währung dargestellt, einschließlich:

  • Performance-Kennzahlen (etwa COS, Ausgaben, …),
  • Budgets und Gebote

HINWEIS: Sie finden die lokale Währung über die Management Center-Oberfläche. Wählen Sie dazu unter „Einrichten“ den Eintrag „Nutzer“ und navigieren Sie zum gewünschten Nutzer.

Zeitzone

Alle Datumsangaben in der Criteo REST-API erfolgen in Coordinated Universal Time (UTC).

AKTUALITÄT DER DATEN

Das Restbudget und die Statistiken erscheinen nicht in Echtzeit sondern bis zu einige Stunden verzögert. Ein Verkäufer kann also inaktiv sein, während sein Restbudget noch abnimmt. Zwar werden die Ads des Verkäufers nicht mehr angezeigt, doch das verbleibende Budget sinkt, wenn die Daten aktualisiert werden.

Empfehlungen für den API-Einsatz

Wenn Sie eine große Anzahl von Budgets oder Geboten aktualisieren, sollten Sie diese Änderungen in separaten, als Stapel eingerichteten API-Aufrufen implementieren, anstatt einzelne Aufrufe zu nutzen. Letztere könnten zu verzögerter Verarbeitung führen.

Dabei sollte ein Aufruf für die Gebote erfolgen und ein weiterer Aufruf für die Budgets. Beide Aufrufe sollten die korrekten Gebote und Budgets für die jeweilige Kampagne(n) enthalten.

BEISPIEL: Sie müssen Gebote und Budgets für 10 unterschiedliche Verkäufer festlegen. Wir empfehlen, dass Sie 1 API-Aufruf für den seller-campaign Endpunkt und 1 Aufruf für den budgets Endpunkt tätigen. Dabei sollten die Aufrufe die gewünschten Gebote und Budgets der jeweiligen Verkäufer enthalten.

Technische Elemente

Alle technischen Komponenten und Endpunkte in dieser V2 Dokumentation sind neu. Zum Vergleich finden Sie unseren V1 Swagger hier:

https://api.criteo.com/marketing/swagger 

In diesem Swagger finden Sie folgende Endpunkte:

  • Authentication: Erhalt eines Tokens. Aus Sicherheitsgründen ist das Token 5 (fünf) Minuten lang gültig.
  • Portfolio: Abruf grundlegender Informationen, etwa Ihre AdvertiserID und Ihren Advertiser-Namen.
  • Seller
    • GET /v2/crp/sellers: Abruf grundlegender Informationen zum Verkäufer
    • POST /v2/crp/statistics: Abruf grundlegender Kampagnenstatistiken
  • Budget
    • GET /v2/crp/budgets: Status und Restbetrag pro Budget abrufen
    • POST /v2/crp/budgets: Budget pro Verkäufer erstellen
    • PUT /v2/crp/budgets: Budget pro Verkäufer aktualisieren
  • Sellers-campaign
    • GET/v2/crp/seller-campaign: Abruf von Verkäufer Informationen in Hinblick auf das Verkäufer-Gebot für die Kampagne
    • PUT /v2/crp/seller-campaigns: Bereitstellung eines Gebots (CPC) für den Verkäufer für die Kampagne

Bitte beachten Sie: Sellers und Sellers-campaign werden basierend auf dem Katalog-Importautomatisch erstellt. Entsprechend bieten wir keine POST Calls für diese Endpunkte an.

BEISPIEL: Dieser Swagger verweist auf die Criteo Produktionsumgebung. Hier durchgeführte Tests wirken sich also auf echte Kampagnen aus.

API Übersicht

Unten finden Sie die wichtigsten Features der Criteo Reseller Program REST API, die es Ihnen erlauben, Budgets und Gebote von Kampagnen auf Verkäufer-Level zu verwalten.

Erste Schritte

Wie authentifiziere ich die API?

Criteo verwendet JWT zur Bereitstellung eines Token-basierten Authentifizierungssystems für unsere REST API. Um Aufrufe an unsere API zu tätigen, müssen Sie bei jedem Aufruf ein Token übergeben.

Sie erhalten Ihr Token, indem Sie einen POST-Aufruf an den Endpunkt /oauth2/token tätigen und dabei die Parameter client_id und client_secret angeben (siehe Abschnitt „Erste Schritte“).

HINWEIS: Jedes Token ist 5 Minuten lang gültig. Wenn Ihr Token abgelaufen ist, erhalten Sie den HTTP-Statuscode 401 zurück.

Wie rufe ich meine AdvertiserID ab?

Rufen Sie Ihre AdvertiserID ab, indem Sie einen GET-Aufruf an den Endpunkt /portfolio/ senden.

Wie rufe ich meine Catalog ID ab?

Rufen Sie Ihre Catalog ID ab, indem Sie einen GET-Aufruf an den Endpunkt /v2/crp/sellers senden.

Wie rufe ich meine CampaignID ab?

Rufen Sie Ihre CampaignID ab, indem Sie einen GET-Aufruf an den Endpunkt /v2/crp/seller-campaigns senden.

Verkäufer verwalten

Wie kann ich im Criteo Reseller-Programm einen Verkäufer onboarden?

Schritt 1: Zum Onboarding eines neuen Verkäufers sollten Sie sichergehen, dass dieser im Produkt Feed, den Sie zuvor mit Criteo geteilt haben, korrekt markiert ist. 

Um die korrekte Markierung des neuen Verkäufers sicherzustellen, müssen Sie in der Spalte seller name für jedes im Feed bereitgestellte Produkt des jeweiligen Verkäufers die eindeutige ID dieses Verkäufers (der Name des Verkäufers) eintragen. 

Tipp: Ein Verkäufer wird aktiv, sobald sie uns über den Feed die verfügbaren Produkte schicken.

Jetzt werden die Verkäufer registriert und für alle Ihre CRP-Kampagnen werden seller-campaigns eingerichtet.

Schritt 2: Sie können die seller ID and seller-campaign ID über den folgenden Aufruf abfragen: GET /v2/crp/seller-campaigns

Schritt 3: Jetzt können Sie uns das Budget und die Gebote Ihres Verkäufers senden. Dies erfolgt über die zuvor beschriebenen Endpunkte für Verkäufer, insbesondere:

  • POST /v2/crp/budgets:    Mit diesem Aufruf senden Sie uns das Budget des Verkäufers. Nun kann dieses Budget über mehrere Kampagnen verteilt werden.
  • PUT /v2/crp/seller-campaigns: Über diesen Aufruf stellen Sie die CPC des Verkäufers pro seller-campaign bereit.

TIPP: Sie können eine vollständige Liste der Verkäufer mit ihrem jeweiligen Status (aktiv/inaktiv) abrufen, indem Sie einen GET-Aufruf an den sellers-Endpunkt senden und dabei Ihre Katalog-ID im Criteo Reseller-Programm (catalogID) als Parameter angeben.  

Wie kann ich die Daten eines Verkäufers aus dem Criteo Reseller-Programm entfernen?

Wenn Sie einen Verkäufer aus dem Criteo Reseller Program entfernen wollen, müssen Sie lediglich das Budget dieses Verkäufers stoppen. Dies geschieht über einen PUT-Aufruf an /v2/crp/budgets mit status = STOPPED.

Alternativ können Sie auch die Produkte des Verkäufers aus Ihrem Produkt-Feed entfernen. Dies wirkt sich jedoch erst aus, nachdem Criteo die Verarbeitung von Feed und Verkäufern abgeschlossen hat. Darüber hinaus verlangt das erneute Hinzufügen einen erhöhten Zeitaufwand, da Feed und Verkäufer erneut verarbeitet werden müssen. Daher raten wir von dieser Alternative ab.

Die Entfernung eines Verkäufers aus dem Feed hat keinen Einfluss auf die Statistiken zu diesem Verkäufer.

Verwaltung von Kampagnen

Wie starte ich eine Kampagne?

Stellen Sie zum Start einer Kampagne im Criteo Reseller-Programm zuerst einen Produkt-Feed bereit. Dieser sollte Produkte von allen Händlern/Partnern enthalten, die beim Programm angemeldet sind. Hinweis: Bei jedem Produkt sollte der eindeutige Bezeichner des Händlers/Partners im Feld „Seller“ angegeben sein. Die Kampagne wird automatisch erstellt, sobald Ihr Feed verarbeitet ist.

Damit die Kampagne online gehen kann, benötigt sie mindestens einen Verkäufer mit einem bereits festgelegten Budget und Gebot. Wir empfehlen jedoch nicht, mit einer so niedrigen Zahl von Verkäufern zu starten. CRP-Kampagnen wurden dafür entwickelt, Hunderte oder gar Tausende Verkäufer zu umfassen.

TIPP: Wenn Sie bereits mit Criteo zusammenarbeiten, stehen Ihnen die folgenden Optionen zur Verfügung:

  • Empfehlung: Sie können Ihren aktuellen Feed aktualisieren, indem Sie die Verkäufer-Informationen in das Feld Seller eintragen (vorausgesetzt, sie nutzen aktuell keine drei Kategorien).
  • Alternativ können Sie auch einfach den uns bereits zur Verfügung stehenden Feed kopieren. Stellen Sie dabei sicher, dass die eindeutige ID des Verkäufers im Feld Seller angegeben ist.
    • In diesem Fall besprechen Sie bitte die Rechnungsstellung für Ihre Kampagne. Im Idealfall ist es am besten, wenn wir die neue CRP-Kampagne in Ihre aktuelle Rechnungsstellung integrieren können.

Die Kampagne wird automatisch erstellt, sobald Ihr Feed verarbeitet ist. Damit die Kampagne online gehen kann, benötigt sie mindestens einen Verkäufer mit einem bereits festgelegten Budget und Gebot. Wir empfehlen jedoch nicht, mit einer so niedrigen Zahl von Verkäufern zu starten. CRP-Kampagnen wurden dafür entwickelt, Hunderte oder gar Tausende Verkäufer zu umfassen.

Sie können diese Daten über die Endpunkte POST /v2/crp/budgets und  PUT /v2/crp/seller-campaigns übermitteln. 

Wie stoppe ich eine Kampagne?

Zum Stoppen Ihrer gesamten Kampagne im Criteo Reseller-Programm (für alle Verkäufer) wenden Sie sich an Ihren Account Manager.

Wie stoppe ich einen Verkäufer?

Um einen oder mehrere Verkäufer in Ihrer Kampagne zu stoppen, setzen Sie deren Budgets einfach auf "STOPPED".

Danach zeigt das System keine Ads für die Produkte dieses Verkäufers mehr an.

Um ein Budget auf "STOPPED" zu setzen, machen Sie bitte einen PUT-Aufruf an den Endpunkt /v2/crp/budgets wie folgt: PUT /v2/crp/budgets mit status = STOPPED.

HINWEIS: Verkäuferbudgets mit dem Status STOPPED können nicht reaktiviert werden. Wenn Sie einen Verkäufer mit dem Status STOPPED wieder aktivieren wollen, müssen sie für ihn ein neues Budget erstellen. Näheres dazu finden Sie im Abschnitt "Ein neues Budget erstellen".

Wenn Sie ein Budget stoppen, sehen Sie möglicherweise auch nach dem Stopp einen Rückgang des Budgets. Die Aktualisierung der Statistiken nimmt möglicherweise ein paar Stunden in Anspruch. Beispiel: Wenn Sie Ihr Budget bei zehn Euro stoppen, werden Ihre Ads nicht mehr geschaltet, aber es gibt möglicherweise noch nicht erfasste Ausgaben. Daher könnte das Rstbudget letztlich 9,50 € betragen.

Was muss ich bei einem Verkäufer machen, dessen Budget fast vollständig aufgebraucht ist?

Sie müssen nichts unternehmen. Wir erkennen, wenn das Budget von Verkäufern verbraucht ist, und stoppen ihre Kampagnen, sobald dies der Fall ist.

Wie lege ich Budgets und CPCs fest?

Mithilfe folgender Endpunkte können Sie das Budget und den CPC eines bestimmten Verkäufers festlegen:

  • Budgets:
    • Zur Initialisierung senden Sie einen POST-Aufruf an den Endpunkt /v2/crp/budget   .
    • Zur Aktualisierung senden Sie einen PUT-Aufruf an den Endpunkt /v2/crp/budget.
  • CPCs: Zur Initialisierung und Aktualisierung senden Sie einen PUT-Aufruf an den Endpunkt /v2/crp/seller-campaign.

Wie erhöhe ich ein Budget oder einen CPC?

Zur Erhöhung eines Budgets und des CPCs für einen bestimmten Verkäufers tätigen Sie einen PUT-Aufruf an die Endpunkte /v2/crp/budget und v2/crp/seller-campaign.

Wie verringere ich einen CPC?

Möchte Ihr Verkäufer seinen CPC senken, richten Sie einen POST-Aufruf an den Endpunkt v2/crp/seller-campaign.

Wie verringere ich ein Budget?

Will der Verkäufer sein Budget verringern, müssen Sie den aktuellen Status auf "STOPPED" setzen. Dadurch werden die Ads unter dem aktuellen Budget ab dem Tag der Ausführung unsichtbar gemacht. Danach müssen Sie ein neues Budget mit dem niedrigeren Wert einrichten. Näheres finden Sie im Abschnitt "Ein neues Budget erstellen". Dieses Budget tritt einen Tag später (Zeitzone UTC) in Kraft.

Beispiel:

Tag 0: Verkäufer A hat anfangs einen Budget von 1.000 US-Dollar festgelegt.

Tag 2: Verkäufer A hat noch ein Restbudget von 800 US-Dollar, will sein verfügbares Budget aber auf 500 US-Dollar senken.

Führen Sie also folgende API-Aufrufe aus:

  • PUT-Aufruf an den Endpunkt v2/crp/budgets
    • Setzen des Status auf STOPPED
    • (Der genaue Budgetbetrag muss nicht angegeben werden, denn Status hat Priorität)
  • POST-Aufruf an den Endpunkt /v2/crp/budgets
    • Setzen des Amount auf 500
    • (Der Status muss nicht explizit angegeben werden; bleibt er leer, wird er als Active angenommen.)

WICHTIGER HINWEIS Senkungen des Budgets werden sofort umgesetzt und wirken sich wie folgt aus:

  • Alle Kampagnen dieses Verkäufers werden sofort gestoppt und für den Rest des Tages pausiert.
  • Der Verkäufer wird am Folgetag um 00:00 Uhr UTC-Zeit mit dem neu festgelegten Budget für seine Kampagnen wieder aktiv.

Wie erstelle ich ein neues Budget?

In einem der beiden folgenden Fälle können Sie ein neues Budget erstellen:

  • Am aktuellen Tag ist kein Budget für diesen Käufer aktiv. große Budgets können sich nicht überschneiden.
  • Sie haben das Budget für diesen Verkäufer AUFGEBRAUCHT.

Um ein neues Budget für einen Verkäufer zu erstellen, müssen Sie folgende Schritte unternehmen:

  • POST-Aufruf an den Endpunkt /v2/crp/budgets

Wann tritt das neue Budget in Kraft?

  • Heute, wenn für die Verkäufer noch kein Budget definiert ist.
  • Morgen, wenn bereits ein Budget existiert.

Einer meiner Verkäufer hat irrtümlich ein falsches Budget eingerichtet. Wie kann ich diesen Fehler korrigieren?

Als Erstes sollte der Verkäufer Ihnen das aktualisierte Budget mitteilen. Nun gibt es drei verschiedene Szenarien mit jeweils unterschiedlichen Aktionen:

  • Sie kennen das neue Budget bereits und es ist niedriger als das anfänglich festgelegte Budget:
    • Führen Sie die Aktionen aus dem Abschnitt „Wie verringere ich ein Budget/einen CPC?“ aus.
  • Sie kennen das neue Budget bereits und es ist höher als das anfänglich festgelegte Budget:
    • Führen Sie die Aktionen aus dem Abschnitt „Wie erhöhe ich ein Budget/einen CPC?“ aus.
  • Sie kennen das neue/richtige Budget nicht:
    • Führen Sie die Aktionen aus dem Abschnitt „Einen Verkäufer entfernen“ aus.

Einer meiner Verkäufer hat versehentlich ein Gebot festgelegt. Wie kann ich dies korrigieren?

Als Erstes sollte der Verkäufer Ihnen den aktualisierten CPC angeben. Senden Sie dann einen PUT-Aufruf an den Endpunkt /v2/crp/seller-campaigns, um das aktualisierte Gebot festzulegen.

Was geschieht, wenn ein Verkäufer den Namen auf meiner Plattform ändert?

Unsere API stützt sich bei der Verwaltung der Gebote und Budgets auf den sellerName. Daher wird bei jeder Änderung des Verkäufernamens automatisch ein neuer Eintrag in unserem System angelegt. Dieser ist nicht mit dem vorherigen Verkäufernamen verknüpft.
Hier eine Zusammenfassung der Schritte, die Sie unternehmen müssen, wenn ein Verkäufer auf Ihrer Plattform seinen Namen ändert:

  • Aktualisieren Sie den Product Feed mit dem neuen sellerName.
  • Initialisieren Sie das Gebot und Budget Ihres Verkäufers, indem Sie uns folgende Aufrufe senden: PUT /v2/crp/seller-campaigns & POST /v2/crp/budgets

HINWEIS: Sie können die Statistiken des früheren sellerName vom Endpunkt statistics abrufen.

Wie kann ich das verbrauchte Budget meines Verkäufers einsehen?

Sie können eine Übersicht über das ausgegebene Budget eines bestimmten Verkäufers für eine Kampagne im Criteo Reseller-Programm erhalten, indem Sie einen GET-Aufruf an den Endpunkt /v2/crp/budgets senden. Diese Information wird dann als spentAmount zurückgegeben.

Wie kann ich das verbleibende Budget für meine Verkäufer einsehen?

Sie können eine Übersicht über das ausgegebene Budget eines bestimmten Verkäufers für eine Kampagne im Criteo Reseller-Programm erhalten, indem Sie einen GET-Aufruf an den Endpunkt /v2/crp/budgets. senden.

Diese Information wird dann als remainingAmount zurückgegeben.

Welche Status-Formen kann man Budget einnehmen?

  • Laufend
  • Aufgebraucht: Ihr Budget ist verbraucht und wir haben die Ads Ihres Verkäufers gestoppt.
  • Stopped: Sie haben den Verkäufer manuell gestoppt.
  • Beendet: Sie haben für dieses Budget ein Enddatum bereitgestellt. Dieses Enddatum liegt jetzt in der Vergangenheit.
  • Geplant: Sie haben für dieses Budget ein Startdatum festgelegt, dass noch in der Zukunft liegt.

Kann ich ein Budget so planen, dass es zu einem späteren Zeitpunkt startet?

Ja. Wenn Sie ein Budget erstellen wollen, dass erst in der Zukunft startet, legen Sie einfach ein Startdatum fest. Das Budget startet dann am Startdatum um Mitternacht (MEZ).

Kann ich ein Enddatum für mein Budget vorgeben?

Ja. Sie können für ihr Budget ein Enddatum definieren. Das Budget endet dann am angegebenen Tag um 23:59 Uhr mitteleuropäischer Zeit. Der Status des Budgets am Tag darauf lautet dann automatisch VERBRAUCHT.

Kann ich ein Tagesbudget einrichten?

Noch nicht. Dieses Feature ist jedoch geplant. D. h. in Zukunft können Sie dann den Budgettyp als "DAILY" festlegen und einen entsprechenden Betrag angeben. Dieses Feature wird voraussichtlich im ersten Quartal 2019 verfügbar sein. Dieses Datum ist jedoch weder verbindlich noch bestätigt.

Kann ich meine Aufrufe hinsichtlich der Verkäufer-Budgets filtern?

ja. Dies sind die zur Verfügung stehenden Filter:

  • /v2/crp/sellers
    • Für den Seller-Endpunkt: Sie können nach Status (Available/NotAvailable) und Verkäufer-ID filtern.
  • /v2/crp/seller-campaigns
    • Für den Endpunkt seller-campaigns: Sie können nach Kampagnen-ID und Verkäufer-ID filtern.
  • /v2/crp/budgets
    • Endpunkt Budgets: nach Status

Berichtswesen

Sie können einen POST-Aufruf an den Endpunkt /v2/crp/statistics senden. Auf Impressions, Klicks und Kosten kann nur auf Verkäuferebene zugegriffen werden – und maximal tagesgenau.

Neben den Dimensionen für die Verkäufer-ID und die Kampagnen-ID kann eine weitere Dimension angegeben werden.

Dimensionen:

  • AdvertiserID
  • CampaignID – Pflichtangabe
  • Seller ID – Pflichtangabe
  • Woche
  • Tag

Verfügbare Metriken:

  • Anzeigen
  • Clicks
  • AdvertiserCost

Display: Da in einem Banner mehrere Verkäufer angegeben werden können, verwenden wir den Verkäufer, der die letzte Produktansicht in unserem System registriert hat.

War dieser Beitrag hilfreich?
0 von 0 fanden dies hilfreich
Powered by Zendesk