Conversions API

Überblick

Conversions API sendet die Conversions, die Matomo ohnehin erfasst (Ziele und E-Commerce-Bestellungen), serverseitig an Google Ads, Meta, LinkedIn, X und Microsoft Advertising. Sie brauchen dafür keine Werbe-Pixel auf Ihrer Website, und Werbeblocker oder Browser-Einschränkungen verfälschen Ihre Kampagnenzahlen nicht mehr.

So funktioniert es

Sie richten pro Website eine oder mehrere Ziel-Plattformen ein und legen fest, welche Matomo-Ziele als welche Conversion gesendet werden. Matomo erfasst die Conversion wie gewohnt. Ein Hintergrundjob sendet sie mit dem empfohlenen Cronjob innerhalb einer Minute, bei Google mit einer einstellbaren Verzögerung.

• Google Ads: Data Manager API, Anmeldung per Service-Account, Klicks über gclid, gbraid und wbraid, Verarbeitungsstatus im Versandprotokoll.
• Meta: Conversions API mit Event-Namen wie Purchase oder Lead, fbclid und die Meta-Cookies _fbp/_fbc.
• LinkedIn: Conversions API mit Conversion-Regeln, Klicks über li_fat_id.
• X (Twitter): Web-Conversions der X Ads API, Anmeldung per Pixel-Token oder OAuth, Klicks über twclid.
• Microsoft Advertising (Bing): UET Conversions API mit dem Token des UET-Tags, Klicks über msclkid. Den Microsoft UET Consent Mode liest das Plugin ebenfalls.

Einwilligung zuerst

Gesendet wird nur, wofür der Besucher eingewilligt hat, je Plattform. Ihr Consent-Banner übergibt die Entscheidung über Matomo Tag Manager, über Google Consent Mode oder über die JavaScript-API. Antwortet der Besucher erst nach der Conversion, etwa bei einem Ziel beim Seitenaufruf, wartet die Conversion bis zu 24 Stunden auf seine Entscheidung. Ein Widerruf stoppt alles, was noch nicht gesendet ist. Optional übermittelt Ihre Website Kundendaten wie die E-Mail-Adresse. Matomo normalisiert und hasht sie je Plattform, Klartext wird nie gespeichert.

Volle Kontrolle

Das Versandprotokoll zeigt jede Sendung mit Status, Fehlertexten der Plattformen und „Erneut senden“. Anmeldefehler pausieren eine Ziel-Plattform automatisch, und Hauptadministratoren werden informiert. Matomos Rohdaten-Löschung und DSGVO-Werkzeuge umfassen die Daten des Plugins. Sie finden das Plugin unter Administration → Webseiten → Conversions API und im Reporting unter Ziele → Conversions API, auch im Dark Mode von Matomo.

Einsatzszenarien

• Kein Pixel, keine Lücken: Matomo erfasst die Conversion ohnehin. Conversions API sendet sie direkt an die Werbeplattformen. Werbeblocker und Browser-Einschränkungen schlucken nichts mehr, und Sie brauchen keine zusätzlichen Tags auf der Website.
• Klicks automatisch zugeordnet: Das Plugin erkennt Anzeigenklicks von Google (gclid, gbraid, wbraid), Meta (fbclid), LinkedIn (li_fat_id), X (twclid) und Microsoft (msclkid) und ordnet spätere Conversions zu, auch nach einem Login und über mehrere Besuche innerhalb Ihres Lookback-Fensters.
• Einwilligung je Plattform: Gesendet wird nur, wofür der Besucher eingewilligt hat. Das Signal kommt aus Ihrem Consent-Banner über Matomo Tag Manager, Google Consent Mode oder die JavaScript-API. Pro Website wählen Sie den Modus „Streng“ oder „Extern“. Antwortet der Besucher erst nach der Conversion, wartet sie bis zu 24 Stunden auf seine Entscheidung.
• Sparsam mit Daten: Kundendaten werden in Matomo normalisiert und gehasht, Klartext wird nie gespeichert. IP, Browserkennung und Hashes werden nach dem Versand gelöscht, spätestens nach 7 Tagen, Klick-IDs nach 90 Tagen.
• Jede Sendung nachvollziehbar: Das Versandprotokoll zeigt, was wann an welche Plattform ging, mit den Fehlertexten der Plattformen, „Erneut senden“ und bei Google dem Verarbeitungsstatus. Abgelaufene Zugänge erkennt das Plugin und meldet sie.

Einrichtung Schritt für Schritt

Wie Sie das Plugin installieren, steht unter Plugins installieren. Für die Conversions API brauchen Sie eine selbst betriebene Matomo-Installation ab Version 5 mit PHP 8.1 oder neuer, auch für die Kommandozeile. Eingerichtet wird je Website unter Administration → Webseiten → Conversions API oder im Reporting unter Ziele → Conversions API. Beides sehen Administratoren der Website.

1. Cronjob anlegen

Ein Hintergrundjob sendet die Conversions. Lassen Sie ihn jede Minute laufen, sonst sendet Matomo nur einmal pro Stunde. Die genaue Zeile zeigt die Plugin-Seite unter Setup:

* * * * * php /pfad/zu/matomo/console feinwerkconversionsapi:dispatch > /dev/null 2>&1

Haben Sie mehrere PHP-Versionen, tragen Sie den vollen Pfad des PHP-8-Programms ein. Läuft der Job seit mehr als 15 Minuten nicht, zeigt die Plugin-Seite einen Hinweis.

2. Ziel-Plattform hinzufügen

Wählen Sie Google Ads, Meta (Facebook/Instagram), LinkedIn, X (Twitter) oder Microsoft Advertising (Bing) und tragen Sie den Zugang ein. Zugangsdaten werden verschlüsselt gespeichert.

• Meta: Events Manager → Datenquelle → Einstellungen → Conversions API → Zugriffsschlüssel generieren. Dazu die Dataset-(Pixel-)ID. Ziel ist ein Event-Name wie Purchase oder Lead.
• Google Ads: In einem Google-Cloud-Projekt die Data Manager API aktivieren, ein Dienstkonto mit JSON-Schlüssel anlegen und dessen E-Mail-Adresse in Google Ads als Nutzer hinzufügen. Dazu die Kundennummer des Kontos mit der Conversion-Aktion. Ziel ist die ID einer Conversion-Aktion vom Typ Import aus Klicks.
• LinkedIn: Campaign Manager → Signals Manager → Direct API → Zugriffsschlüssel erzeugen. Dazu die Werbekonto-ID. Ziel ist die ID einer Conversion-Regel vom Typ Conversions API.
• X (Twitter): Im X Events Manager die Pixel-ID ablesen. Anmelden können Sie sich mit dem Pixel-Token aus dem Events Manager oder mit den vier OAuth-Schlüsseln einer App aus dem X Developer Portal. Sind beide ausgefüllt, gilt der Pixel-Token. Ziel ist die Event-ID des Conversion-Events, etwa tw-abc12-def34.
• Microsoft Advertising: Beim UET-Tag Conversions API verwenden wählen und den Token erzeugen. Dazu die UET-Tag-ID. Ziel ist der Event-Name, der zum Conversion-Ziel in Microsoft Advertising passt, etwa purchase oder lead.

Unter Zu sendende Ziele ordnen Sie Matomo-Ziele und die E-Commerce-Bestellung einem Ziel der Plattform zu und wählen den Wert: Umsatz der Conversion, ein fester Wert oder keiner. Verbindung testen prüft den Zugang.

3. Website anbinden

Die Conversion selbst erfasst Matomo wie gewohnt. Die Website übergibt zusätzlich die Einwilligung des Besuchers und auf der Bestellbestätigung die Kundendaten, am einfachsten über den Matomo Tag Manager:

var _mtm = window._mtm = window._mtm || [];
_mtm.push({event: 'fwcapi_consent',
  fwcapi_consent: {google: consent.google, meta: consent.meta, linkedin: consent.linkedin,
    x: consent.x, microsoft: consent.microsoft}});

consent steht für die tatsächliche Entscheidung des Besuchers aus Ihrem Consent-Banner, nie pauschal true. Auf der Bestellbestätigung, bevor Matomo die Bestellung trackt:

_mtm.push({event: 'purchase', ecommerce: {transaction_id: 'A-4711'},
  user_data: {email: 'jane@example.org', phone_number: '+4915112345678'}});

Nutzt Ihre Website Google Tag Manager oder Google Consent Mode, liest das Plugin diese Einträge ebenfalls, ebenso den Microsoft UET Consent Mode (uetq.push('consent', …)) als Entscheidung für Microsoft. Ohne Tag Manager gibt es die JavaScript-API (_paq.push(['FeinwerkConversionsApi::setConsent', consent])), für serverseitiges Tracking die Parameter fwcapi_consent, fwcapi_ud und fwcapi_eid. Den passenden Code zeigt die Plugin-Seite unter Setup.

4. Erste Daten prüfen

Das Versandprotokoll zeigt je Zeitraum, was erfasst, eingeplant, gesendet oder übersprungen wurde, darunter jede Conversion mit Status, Versuchen und Fehlertext der Plattform. Erneut senden stößt eine fehlgeschlagene Sendung neu an. Bei Google zeigt die Tabelle der Anfragen zusätzlich den Verarbeitungsstatus bei Google.

Praxisbeispiele

Conversions trotz Werbeblocker an Meta melden

Legen Sie eine Meta-Ziel-Plattform an und ordnen Sie die E-Commerce-Bestellung Purchase mit dem Umsatz zu. Läuft das Meta-Pixel weiter, wählen Sie bei Deduplizierung mit vorhandenem Pixel die Bestellnummer: Meta zählt dann jede Bestellung nur einmal, auch wenn Pixel und Plugin sie melden.

Leads an LinkedIn melden

Ordnen Sie das Ziel Kontaktanfrage einer LinkedIn-Conversion-Regel zu und geben Sie einen festen Wert an, etwa den durchschnittlichen Wert eines Leads. LinkedIn ordnet die Conversion über die Klick-ID li_fat_id der Kampagne zu, auch wenn die Anfrage erst bei einem späteren Besuch kommt.

Google Ads mit Bestellungen und Newsletter-Anmeldungen

Legen Sie eine Google-Ziel-Plattform mit zwei Conversion-Aktionen an. Google empfiehlt rund sechs Stunden Sendeverzögerung, damit frische Klicks bei Google bekannt sind. Das Plugin stellt sie für Google voreingestellt ein. Bis zum Versand stehen die Conversions im Versandprotokoll als Eingeplant.

Gut zu wissen

• Einwilligung: Im Standardmodus Streng wird nur gesendet, wofür der Besucher eingewilligt hat, je Plattform. Den Modus Extern wählen Sie je Website, wenn Ihre Website die Einwilligung selbst sicherstellt (Administration → Webseiten → Verwalten).
• Späte Einwilligung: Antwortet der Besucher erst nach der Conversion auf das Banner, etwa bei einem Ziel beim Seitenaufruf, wartet die Conversion bis zu 24 Stunden auf seine Entscheidung. Das Plugin meldet eine spätere Entscheidung selbst an Matomo, sie gilt auch für Conversions aus früheren Besuchen und für serverseitig erfasste Ziele. Ein Widerruf stoppt alles, was noch nicht gesendet ist. Eine Ablehnung, die nur aus den Standardwerten von Google Consent Mode stammt, gilt dabei noch nicht als Entscheidung. Abschaltbar je Website über Auf späte Einwilligung warten.
• Datenschutz: Kundendaten werden in Matomo normalisiert und gehasht, Klartext wird nie gespeichert. Vollständige IP, Browserkennung und Hashes werden nach dem Versand gelöscht, spätestens nach 7 Tagen, Klick-IDs nach 90 Tagen. Wartet eine Conversion auf die Einwilligung, liegen IP und Browserkennung bis zu 24 Stunden verschlüsselt vor, nur für Plattformen, für die die Website eine Ziel-Plattform hat. Matomos Rohdaten-Löschung und DSGVO-Werkzeuge umfassen die Daten des Plugins.
• User-ID und cookieloses Tracking: Ein Anzeigenklick aus einem anonymen Besuch zählt auch für eine Conversion nach dem Login, solange derselbe Browser mit demselben Matomo-Cookie genutzt wird. Ohne Besucher-Cookie erkennt Matomo einen Besucher nur innerhalb eines Tages wieder.
• Fehlersuche: Nach einem Anmeldefehler pausiert eine Ziel-Plattform mindestens eine Stunde, nach fünf in Folge wird sie deaktiviert. Ändert sich Matomos Salt, tragen Sie die Zugangsdaten neu ein. Den Lizenzstatus zeigt die Plugin-Seite, geprüft über den Feinwerk Marketplace Connector. Das Plugin arbeitet auch ohne gültige Lizenz weiter. Weitere Hilfe: support@feinwerk.io.

Technische Referenz

Eigenschaft	Wert
Technischer Name	FeinwerkConversionsApi
Aktuelle Version	0.4.0
Matomo	≥ 5.0.0, < 6.0.0
PHP	≥ 8.1.0
Lizenz	kostenpflichtig
Datenbankänderungen	keine in der aktuellen Version

FAQ

Welche Plattformen werden unterstützt?

Google Ads über die Data Manager API, Meta (Facebook und Instagram) über die Conversions API, LinkedIn über die Conversions API, X (Twitter) über die Web-Conversions der X Ads API und Microsoft Advertising (Bing) über die UET Conversions API. Pro Website können Sie beliebig viele Ziel-Plattformen einrichten.

Brauche ich dafür Google Tag Manager?

Nein. Einwilligung, Kundendaten und Bestellnummer übergeben Sie über Matomo Tag Manager (_mtm) oder die JavaScript-API von Matomo. Nutzt Ihre Website Google Tag Manager oder Google Consent Mode, liest das Plugin diese Einträge ebenfalls.

Kann ich das Pixel parallel weiter betreiben?

Ja. Für den Parallelbetrieb deduplizieren die Plattformen über eine gemeinsame Event-ID, wahlweise die Bestellnummer oder eine ID, die Ihre Website an Pixel und Matomo übergibt.

Wie schnell kommen die Conversions an?

Mit dem empfohlenen Cronjob prüft das Plugin jede Minute, was zu senden ist. Für Google ist standardmäßig eine Verzögerung von rund 6 Stunden eingestellt, damit frische Klicks bei Google schon bekannt sind.

Was passiert ohne Einwilligung?

Im Standardmodus „Streng“ wird ohne Einwilligung nichts an die Plattform gesendet. Antwortet der Besucher erst nach der Conversion auf das Consent-Banner, wartet die Conversion bis zu 24 Stunden auf seine Entscheidung. Ohne Zustimmung wird sie verworfen und ihre Daten werden gelöscht. Stellt der Website-Betreiber die Einwilligung anderweitig sicher, kann er pro Website den Modus „Extern“ wählen.

Welche Matomo-Version brauche ich?

Matomo 5 mit PHP 8.1 oder neuer, auch für die Kommandozeile, mit der der Cronjob läuft. Das Plugin unterstützt den Dark Mode von Matomo.

Wo finde ich die Conversions API in Matomo?

Administratoren einer Website finden sie unter Administration → Webseiten → Conversions API und im Reporting unter Ziele → Conversions API. Dort richten Sie Ziel-Plattformen ein, prüfen das Versandprotokoll und finden den Code für Ihre Website.