Pinterest Conversions API für Shopify: eine Einrichtungsanleitung

Die Pinterest Conversions API ist Pinterests Server-zu-Server-Weg, um Conversion-Events zu senden. Dein Shop oder ein Tool wie ROASaurus sendet Events wie Käufe direkt an dein Pinterest-Werbekonto, statt sich nur auf den Pinterest Tag im Browser des Käufers zu verlassen. Pinterest nutzt die Daten für das Conversion-Reporting, die Kampagnenoptimierung und das Targeting.

Dieser Leitfaden behandelt die v5-API und die Events, die sie akzeptiert, die Click-ID epik, wie Kundendaten gehasht werden, wie die Deduplizierung mit dem Pinterest Tag funktioniert, wie du testest und wie du alles in Shopify einrichtest.

Was ist die Pinterest Conversions API?

Der Pinterest Tag ist ein Skript im Browser des Käufers. Die Conversions API erledigt dieselbe Aufgabe von einem Server aus. In der API-Version 5 sendest du Events an den Events-Endpunkt deines Werbekontos, autorisiert mit einem Conversion-Zugriffstoken, das du im Pinterest Ads Manager erstellst. Jedes Event gibt an, wo es stattgefunden hat: Bei einem Webshop ist die Action Source web.

Pinterest bittet Werbetreibende, die auch den Tag nutzen, eine Conversion nicht doppelt zu zählen, indem sie mit jedem Event eine event_id mitgeben. Außerdem verlangt Pinterest Events in Echtzeit oder höchstens eine Stunde, nachdem sie stattgefunden haben.

In Shopify hat eine Server-Verbindung einen klaren Vorteil: Käufe stammen aus der Bestellung selbst. Shopify meldet jede bezahlte Bestellung per Webhook an ROASaurus, und ROASaurus sendet sie kurz nach der Zahlung an Pinterest, unabhängig davon, ob der Tag im Browser ausgelöst wurde. Der Leitfaden zu Server-Side-Tracking in Shopify erklärt die Idee ausführlicher.

Welche Events akzeptiert die Pinterest Conversions API?

Pinterest hat eine feste Liste von Standard-Eventnamen, kleingeschrieben und mit Unterstrichen, zum Beispiel page_visit, add_to_cart und checkout. Außerdem kannst du pro Werbetreibenden bis zu 15 benutzerdefinierte Event-Typen definieren. ROASaurus ordnet die fünf Shopping-Events von Shopify so zu:

Der Name kann verwirrend sein. Pinterests checkout ist der abgeschlossene Kauf, nicht der Beginn des Checkouts. Der Beginn des Checkouts ist ein eigenes Event, initiate_checkout.

Für das Checkout-Event empfiehlt Pinterest, den Wert, die Währung, die Bestell-ID, die Content-IDs und die Artikelanzahl zu senden. ROASaurus sendet alle fünf, dazu Menge und Preis jedes Artikels. Pinterest verlangt den Wert vor Steuern und Versand. In Shopify sendet ROASaurus genau das: die Bestellsumme abzüglich Steuern und Versand, vom Server und vom Browser-Tag. Wenn eine Webshop-Plattform Steuern und Versand nicht getrennt meldet, sendet ROASaurus die Bestellsumme.

Wie ordnet Pinterest ein Event einer Person zu?

Jedes Event enthält Nutzerdaten. Pinterest verlangt mindestens eines von drei Dingen: eine gehashte E-Mail-Adresse, eine gehashte mobile Werbe-ID oder die IP-Adresse zusammen mit dem User Agent. Ein Webshop hat keine Werbe-ID, daher braucht er die E-Mail-Adresse oder die IP-Adresse und den User Agent. ROASaurus überspringt ein Event, das keines von beiden hat, statt eines zu senden, das Pinterest nicht verwenden kann.

Die Click-ID epik

Die Pinterest-Click-ID kann aus zwei Quellen stammen: aus einem Parameter epik in der URL der Landingpage oder aus dem Cookie _epik auf deiner Domain. Der API-Leitfaden von Pinterest empfiehlt, den Wert des Cookies _epik zu übergeben, weil er auch dann funktioniert, wenn der URL-Parameter fehlt oder entfernt wurde, was zu einer besseren Abdeckung führt.

ROASaurus liest beides in deinem Storefront aus, nutzt den URL-Parameter, wenn ein neuer Klick einen mitbringt, und sonst das Cookie. Es speichert die Click-ID beim Besucher und sendet sie im Feld click_id jedes Server-Events, auch beim Kauf. Besuche mit einer epik zählen in den Attributionsberichten von ROASaurus als Pinterest-Besuche.

POST https://api.pinterest.com/v5/ad_accounts/549755885175/events

{
  "data": [{
    "event_name": "checkout",
    "action_source": "web",
    "event_time": 1793016000,
    "event_id": "order-5512345678901",
    "event_source_url": "https://example-store.com/checkouts/…/thank-you",
    "user_data": {
      "em": ["a3f1…9c2e"],
      "ph": ["7b40…11d8"],
      "external_id": ["e05c…4a7f"],
      "client_ip_address": "203.0.113.24",
      "client_user_agent": "Mozilla/5.0 (iPhone; …)",
      "click_id": "dj0yJnU9…"
    },
    "custom_data": {
      "currency": "USD",
      "value": "84",
      "order_id": "5512345678901",
      "content_ids": ["44123456789"],
      "contents": [{ "id": "44123456789", "quantity": 2, "item_price": "42" }],
      "num_items": 2
    }
  }]
}

Wie funktioniert die Deduplizierung mit dem Pinterest Tag?

Melden der Tag und die API beide einen Kauf, erhält Pinterest zwei Events für eine Bestellung. Um sie als eines zu behandeln, braucht es auf beiden Seiten dieselbe ID: Die Event-ID im Tag muss mit der event_id im Server-Event übereinstimmen. Pinterest behält das erste Event, das es erhält, und entfernt Duplikate, die innerhalb von 48 Stunden eintreffen.

ROASaurus bildet die Kauf-ID aus der Shopify-Bestell-ID. Der Kauf aus der Bestellung 5512345678901 hat die Event-ID order-5512345678901, sowohl im Tag, der im Checkout ausgelöst wird, als auch im Server-Event.

Alle fünf Events werden dedupliziert

Jedes Shopping-Event in ROASaurus hat eine Event-ID, die der Tag im Browser und das Server-Event verwenden. Der Tag nutzt Pinterests eigene Namen für dieselben Events: pagevisit, viewcontent, addtocart, initiatecheckout und checkout, die zu page_visit, view_content, add_to_cart, initiate_checkout und checkout in der API passen. Wenn beide laufen, behält Pinterest also eine Kopie jedes Seitenaufrufs, jeder Produktansicht, jedes Warenkorb-Hinzufügens, jedes Checkout-Starts und jedes Kaufs.

Du kannst es auf zwei Arten betreiben:

• Tag und Conversions API zusammen. Der Tag liefert Browsersignale, der Server ergänzt, was der Tag verpasst, und Pinterest führt die Kopien zusammen.
• Betreibe die API ohne den Tag. Lass die Tag-ID leer oder schalte Also load the browser tag aus. Jedes Event wird dann nur einmal gesendet, ausschließlich vom Server.

Der Hilfeartikel zur Doppelzählung behandelt dieselben Prüfungen für die anderen Werbeplattformen.

Wie testest du die Pinterest Conversions API?

Die API hat ein Test-Flag. Anfragen, die mit test=true gesendet werden, gehen an eine Sandbox: Pinterest behandelt sie als Testdaten und verwendet sie nicht für Reporting oder Optimierung.

1. Den Testmodus einschalten

   Bearbeite in ROASaurus unter Tracking & platforms das Pinterest-Pixel und setze den Haken bei Test mode (events show under Test events, max 20). Jedes Server-Event wird dann mit test=true gesendet. Pinterest verarbeitet höchstens 20 Test-Events pro Batch.

2. Eine Testbestellung aufgeben

   Besuche deinen Shop, sieh dir ein Produkt an, lege es in den Warenkorb und schließe eine Bestellung ab.

3. Das Ergebnis auslesen

   Öffne das Event log. Pinterest kann mit HTTP 200 antworten, obwohl ein Event in einer Anfrage fehlgeschlagen ist, deshalb prüft ROASaurus den Status jedes Events und zeigt Fehler dort an.

4. Den Testmodus ausschalten

   Entferne den Haken beim Testmodus, damit Events im Reporting und in der Optimierung zählen.

5. Die Events Overview prüfen

   Öffne im Pinterest Ads Manager die Seite Events Overview. Sie zeigt die eingehenden Events und die deduplizierten Conversions. Pinterest empfiehlt, einen Good Event Quality Score anzustreben.

So richtest du die Pinterest Conversions API in Shopify mit ROASaurus ein

Du brauchst einen Shopify-Shop mit der ROASaurus-App und Zugriff auf den Pinterest Ads Manager. Die Seite zur Pinterest-Integration listet jedes Feld auf, das ROASaurus sendet.

1. Shopify-Shop verbinden

   Gehe zu Add a store › Shopify, klicke auf Install app und aktiviere im Theme-Editor die ROASaurus-App-Einbettung. Sie erfasst epik und das Cookie _epik auf jeder Seite. Die Shopify-Einrichtungsanleitung zeigt jeden Schritt.

2. Ein Conversion-Zugriffstoken erstellen

   Gehe im Pinterest Ads Manager zu Conversions und erstelle ein Conversion-Zugriffstoken. Notiere dir deine Werbekonto-ID.

3. Das Pinterest-Pixel in ROASaurus hinzufügen

   Gehe zu Tracking & platforms, klicke bei der Pinterest-Karte auf Add pixel und fülle Ad account ID und Conversion access token aus.

4. Tag-ID eintragen

   Für die Deduplizierung mit dem Tag trage die Pinterest Tag ID ein und lass Also load the browser tag angehakt. Ohne Tag-ID sendet ROASaurus nur Server-Events und lädt den Tag nicht.

5. Das Checkout-Pixel hinzufügen

   Füge im Shopify admin › Settings › Customer events ein Custom Pixel namens ROASaurus hinzu und füge das Snippet von deiner Seite Tracking & platforms ein. Es löst das checkout-Event des Tags im Checkout von Shopify aus, mit der Bestell-ID als event_id.

6. Server-Events auswählen und dann testen

   Wähle die gewünschten Server-Events aus und teste im Testmodus, bevor du live gehst.

Ist Respect visitor consent aktiviert, was die Standardeinstellung ist, richtet sich ROASaurus nach der Entscheidung des Käufers im Cookie-Banner von Shopify. Lehnt ein Käufer Marketing-Cookies ab, lädt ROASaurus den Pinterest Tag für ihn nicht, setzt keine Besucher-ID, sodass seine Klicks ihm nicht zugeordnet werden, und sendet seine Browsing-Events nicht an Pinterest. Seine bezahlte Bestellung wird weiterhin vom Server an die Conversions API gesendet, mit gehashten Bestelldaten sowie der IP-Adresse und dem User Agent der Bestellung, aber ohne Click-ID. Der Leitfaden zu Einwilligung und Datenschutz erklärt, was gespeichert und gesendet wird.

Verbinde dein Pinterest-Werbekonto unter Setup › Ad spend, und ROASaurus ruft jede Stunde die Kampagnenausgaben ab, sodass du den Pinterest-ROAS und den Gewinn nach Werbekosten in der Gewinnanalyse siehst. Der Leitfaden zur TikTok Events API behandelt dieselbe Einrichtung für TikTok, wo jedes Event, das auf beiden Wegen gesendet wird, dedupliziert wird.

Quellen

1. Pinterest Developers: Track conversion events in the API
2. Pinterest Business help: The Pinterest Conversions API
3. Pinterest Developers: Track conversions with Pinterest Tag

In ROASaurus

• Pinterest-Integration
• Server-Side-Tracking in ROASaurus
• Hilfe: Doppelzählung verhindern

Weiterlesen