Pinterest Tag & Conversions API (CAPI)

Installation instructions, documentation and FAQs for the Shopware plugin

Pinterest Tag & Conversions API (CAPI)

Mit dieser Erweiterung bindest du das Pinterest Tag sauber in deinen Shopware-Shop ein und überträgst alle relevanten Shop-Ereignisse zusätzlich serverseitig über die Pinterest Conversions API (CAPI v5). So misst du deine Pinterest-Kampagnen präzise – datenschutzkonform und erst nach Cookie-Einwilligung.

  1. Clientseitiges Pinterest Tag und serverseitige Conversions API (CAPI v5)
  2. Deduplizierung von Browser- und Server-Events über eine gemeinsame Event-ID
  3. Erfasste Ereignisse: page_visit, view_category, search, add_to_cart, checkout, optional lead
  4. Enhanced Match mit serverseitig per SHA-256 gehashter E-Mail
  5. Eigene Ereignisse je Route sowie gezielter Ausschluss einzelner Kundengruppen

Prerequisites

  • Ein Pinterest Business-Konto mit eingerichtetem Ad Account und Zugriff auf den Ads Manager
  • Für die serverseitige Conversions API zusätzlich ein Conversions-API-Access-Token aus dem Pinterest Ads Manager
  • Shopware 6.7
  • Ein aktiver Cookie-Consent-Manager (Shopware-Standard oder ein unterstütztes externes Tool), damit das Tag rechtskonform geladen wird

Compatibility

Die Erweiterung ist mit Shopware 6.7 kompatibel. Das clientseitige Tag wird über den offiziellen Pinterest-Tag-Code geladen, die serverseitige Übermittlung erfolgt direkt von deinem Shop an die Pinterest Conversions API. Zusätzliche Drittanbieter-Plugins sind nicht erforderlich.

Installation

  1. Erweiterung im Shopware Store erwerben und in deinem Shop installieren.
  2. Erweiterung unter Extensions activate.
  3. Konfiguration öffnen und die Pinterest Tag-ID (sowie optional Ad Account ID und Conversions-API-Token) hinterlegen (siehe „Einrichtung“).
  4. Clear the Storefront cache or reload the page so that the tag is displayed.

Furnishings

Bevor du die Erweiterung konfigurierst, brauchst du ein paar Zugangsdaten aus dem Pinterest Ads Manager (ads.pinterest.com):

  • Tag-ID: Navigiere zu Ads › Conversions bzw. „Pinterest-Tag“ und erstelle bzw. öffne deinen Pinterest Tag. Die Tag-ID ist rein numerisch.
  • Ad Account ID: Steht in der URL des Ads Managers (ads.pinterest.com/advertiser/<AD_ACCOUNT_ID>/...) oder unter den Kontoeinstellungen.
  • Conversions-API-Access-Token: Under Ads › Conversions › Conversions API generieren. Pinterest zeigt den Token nur einmal an – sofort vollständig sichern und wie ein Passwort behandeln.

Öffne anschließend die Plugin-Konfiguration unter Erweiterungen › Meine Erweiterungen beim Eintrag „Pinterest Tag & Conversions API (CAPI)“ über das Drei-Punkte-Menü › Configuration. Wähle oben den gewünschten Verkaufskanal aus und nimm die folgenden Einstellungen vor:

  • Active: Schaltet das Tracking für den gewählten Verkaufskanal ein.
  • Pinterest Tag-ID: Deine Tag-ID aus dem Ads Manager.
  • Serverseitiges Tracking über die Conversions API: Aktiviert die zusätzliche Server-zu-Server-Übermittlung.
  • Ad Account ID and Conversions-API-Access-Token: Die oben beschafften Werte aus dem Ads Manager.
  • Enhanced Match: Optional. Sendet eine gehashte E-Mail zusätzlich mit.
  • Consent-Manager: Wähle den in deinem Shop eingesetzten Cookie-Consent-Manager aus.
Plugin-Konfiguration des Pinterest Tag & Conversions API in der Shopware-Administration
Plugin-Konfiguration: Tag-ID, Ad Account ID, Conversions-API-Token, Enhanced Match und Consent-Manager

1 · Erfasste Ereignisse

Ist das Tracking aktiv und die Einwilligung erteilt, erfasst die Erweiterung automatisch die wichtigsten Ereignisse im Kaufprozess und meldet sie an Pinterest:

  • page_visit: jeder Seitenaufruf im Storefront (clientseitig)
  • view_category: Kategorie- und Listing-Seiten (clientseitig)
  • search: Suchergebnisseiten (clientseitig)
  • add_to_cart: Artikel in den Warenkorb gelegt (ausschließlich serverseitig)
  • checkout: abgeschlossene Bestellung mit Umsatz, Währung und Artikeln (client- und serverseitig, dedupliziert)
  • lead: erfolgreiche Kontaktformular-Übermittlung (optional, clientseitig zuschaltbar)

Kategorie- und Suchseiten sind produktiv oft HTTP-gecacht: Ein gecachter Seitenaufruf durchläuft kein PHP und würde ohne Sonderbehandlung eine einzige, wiederverwendete Event-ID an alle Besucher ausspielen. Deshalb feuern diese beiden Ereignisse ausschließlich clientseitig mit einer laufzeitgenerierten Event-ID.

2 · Conversions API & Enhanced Match

Zusätzlich zum clientseitigen Tag überträgt die Erweiterung dieselben Ereignisse serverseitig über die Pinterest Conversions API (CAPI v5) direkt von deinem Shop an Pinterest. Browser- und Server-Ereignis teilen sich eine gemeinsame Event-ID, sodass Pinterest sie zuverlässig dedupliziert und jedes Ereignis nur einmal zählt.

Das serverseitige Tracking arbeitet unabhängig von Ad-Blockern und Browser-Einschränkungen und sorgt so für eine deutlich stabilere Conversion-Messung. Bekannte Crawler-User-Agents werden dabei automatisch von den serverseitigen Ereignissen ausgeschlossen.

Mit aktiviertem Enhanced Match übergibt die Erweiterung zusätzlich eine gehashte E-Mail-Adresse an die Conversions API. Das Hashing erfolgt serverseitig per SHA-256 – Klartextdaten verlassen deinen Shop nicht. So ordnet Pinterest Conversions zuverlässiger den richtigen Nutzern zu.

  • Serverseitiges Tracking über die Conversions API: aktiviert die Server-zu-Server-Übermittlung.
  • Enhanced Match: sendet eine gehashte E-Mail zusätzlich mit.
  • Conversions API asynchron versenden: verarbeitet die Aufrufe über die Shopware Message Queue, ohne die Storefront zu verlangsamen. Erfordert einen laufenden Message-Queue-Worker.
  • Minutes: schreibt die Conversions-API-Aufrufe in die Shopware-Logs zur Diagnose.

3 · Cookie-Einwilligung & Datenschutz

Das Pinterest Tag wird erst geladen, wenn der Besucher der Kategorie „Marketing“ zugestimmt hat. Wird die Einwilligung widerrufen, stoppt das Tracking aktiv – die Warteschlange wird geleert, das Tag neutralisiert und erreichbare Pinterest-Cookies werden entfernt.

Unterstützt werden der Shopware Cookie-Consent-Manager sowie sieben externe Consent-Tools:

  • Cookiebot
  • CookieFirst
  • Usercentrics
  • ACRIS EU Cookie Policy Pro
  • CCM19
  • CMP
  • CookieYes

Bei Shopware Cookie-Consent-Manager, Cookiebot, CookieFirst, CookieYes und ACRIS EU Cookie Richtlinie Pro kann die Erweiterung die Einwilligung auch serverseitig auslesen – die Conversions API sendet nur dann ein Ereignis, wenn Marketing-Consent tatsächlich erteilt wurde. Bei Usercentrics, CCM19 und CMP liegt die Einwilligung ausschließlich im Browser vor und ist serverseitig nicht zuverlässig auslesbar: Hier unterbleibt aus Sicherheitsgründen das serverseitige Ereignis, das clientseitige Tag feuert aber weiterhin normal nach erteilter Einwilligung.

Data protection notice: Enhanced Match überträgt eine SHA-256-gehashte E-Mail-Adresse; diese wird vor dem Verlassen deines Shops gehasht. Die Conversions API sendet zusätzlich die IP-Adresse und den User-Agent des Besuchers im Klartext an Pinterest – das ist für den Abgleich erforderlich und bei serverseitigen Conversion-APIs üblich. Pinterest Inc. verarbeitet diese Daten in den USA. Weise diese Datenübertragung in deiner Datenschutzerklärung aus.

Cookie-Voreinstellungen in der Storefront mit dem Pinterest Tag in der Marketing-Kategorie
Cookie-Dialog: Das Pinterest Tag erscheint in der Kategorie „Marketing“.

4 · Selbst testen

Bevor du das Tracking live schaltest, empfehlen wir einen kurzen Funktionstest:

  • Test-Modus aktivieren: In der Plugin-Konfiguration den Test-Modus einschalten. Serverseitige Ereignisse werden dann mit ?test=true gesendet – Pinterest validiert die Nutzlast, zählt die Ereignisse aber nicht als echte Conversions.
  • Client-Events prüfen: Installiere die kostenlose Browser-Erweiterung „Pinterest Tag Helper“ (Chrome Web Store) und rufe deinen Shop auf. Die Erweiterung zeigt page_visit, view_category, search und checkout live an, sobald Marketing-Consent erteilt wurde.
  • Server-Events prüfen: add_to_cart ist bewusst ausschließlich serverseitig und erscheint deshalb not im Pinterest Tag Helper. Prüfe add_to_cart sowie die serverseitigen checkout-Events stattdessen im Pinterest Ads Manager unter Conversions › Ereignisverlauf bzw. den Test-Events.
  • Deduplizierung prüfen: Client- und Server-checkout-Event teilen sich dieselbe Event-ID – im Ereignisverlauf sollte die Bestellung nur einmal als Conversion gezählt werden, obwohl beide Wege ein Ereignis senden.
  • Test-Modus deaktivieren: Nach erfolgreichem Test den Test-Modus wieder ausschalten, damit die Ereignisse produktiv gezählt werden.

5 · Mehrere Verkaufskanäle & weitere Optionen

  • Mehrere Verkaufskanäle: Wähle oben in der Konfiguration den jeweiligen Verkaufskanal und hinterlege pro Kanal eine eigene Tag-ID, Ad Account ID und ein eigenes Conversions-API-Token.
  • Own events: Definiere zusätzliche clientseitige Ereignisse je Seite/Route über die Konfiguration, ganz ohne Code-Anpassung.
  • Gross/Net: Lege fest, ob Umsätze brutto oder netto übergeben werden.
  • Order value: Übermittle den Bestellwert inklusive oder exklusive Versandkosten.
  • Kundengruppen ausschließen: Nimm einzelne Kundengruppen (z. B. Händler oder interne Gruppen) vom Tracking aus.
  • Währung überschreiben: Optional eine feste Währung statt der Verkaufskanal-Währung vorgeben.
  • 24 languages: Administration und Storefront-Texte stehen in 24 Sprachen zur Verfügung.

FAQs

Alle drei findest du im Pinterest Ads Manager (ads.pinterest.com). Die Ad Account ID steht in der URL bzw. unter den Kontoeinstellungen, die Tag-ID unter „Ads › Conversions“, und das Conversions-API-Token generierst du dort unter „Conversions API“ – der Token wird nur einmal angezeigt, also sofort sichern.

Das Pinterest Tag wird erst nach Zustimmung zur Marketing-Kategorie im Cookie-Dialog geladen. Prüfe außerdem, ob die Erweiterung für den richtigen Verkaufskanal aktiv ist und eine gültige Tag-ID hinterlegt wurde.

add_to_cart wird bewusst ausschließlich serverseitig über die Conversions API gesendet, nicht über das clientseitige Tag. Der Tag Helper zeigt nur clientseitige Ereignisse an. Prüfe add_to_cart stattdessen im Pinterest Ads Manager unter „Conversions › Ereignisverlauf“.

Nein. Das clientseitige Tag funktioniert eigenständig. Die Conversions API ist optional, verbessert aber die Datenqualität deutlich, da sie unabhängig von Ad-Blockern arbeitet. Für sie brauchst du eine Ad Account ID und ein Conversions-API-Access-Token.

Mit aktiviertem Test-Modus sendet die Erweiterung serverseitige Ereignisse mit dem Parameter ?test=true. Pinterest validiert die Nutzlast, zählt die Ereignisse aber nicht als echte Conversions. So kannst du das Setup gefahrlos prüfen, bevor du live gehst.

Wähle die betroffenen Kundengruppen in der Plugin-Konfiguration aus. Für diese werden weder Tag- noch Conversions-API-Ereignisse ausgespielt.

Support

If you have any questions or problems, please do not hesitate to contact us: