English
Deutsch
PolskiMatomo-Tracking-API: Serverseitige Hits, Pflichtparameter und die Fehler, die trotzdem 200 liefern
Management Summary
Matomos Messschnittstelle ermöglicht Geschäftsanwendungen, Käufe und andere Vorgänge direkt an die Websiteanalyse zu melden. Das ist für bestätigte Transaktionen nützlich, die im Unternehmenssystem vorliegen, im Browser aber nicht zuverlässig erfasst werden. Die Verbindung kann Auswertungen vervollständigen, sofern Website, Zeitpunkt und Besuchszuordnung stimmen. Eine erfolgreiche Übertragungsantwort bestätigt zunächst nur die Kommunikation; fehlerhafte Angaben können trotzdem zu fehlenden oder irreführenden Berichtswerten führen.
Inhalt
Matomo kann einen Seitenaufruf, ein Ereignis oder ein Ziel über eine HTTP-Anfrage an matomo.php erfassen. Serverseitiges Tracking umfasst auch Vorgänge außerhalb des Browsers, etwa bestätigte Bestellungen oder gekündigte Mitgliedschaften. Ein Hit bezeichnet eine Tracking-Anfrage; ein Besuch kann mehrere Hits enthalten.
HTTP ist das Anfrage-Antwort-Verfahren im Web. Die API ist Matomos Schnittstelle für Daten aus anderen Programmen. Antwortcodes wie 200 oder 204 melden das Ergebnis an dieser Schnittstelle. Die gespeicherte Aktion und deren Website-Zuordnung benötigen trotzdem eine Prüfung. Eine Warteschlange hält Messanfragen zur späteren Verarbeitung bereit.
Eine erfolgreiche HTTP-Antwort beweist noch keine korrekte Erfassung im vorgesehenen Website-Profil. Normale Antworten enthalten häufig ein transparentes GIF; send_image=0 fordert HTTP 204 ohne Bild an. Übertragung, Verarbeitung und Zuordnung benötigen getrennte Prüfungen, besonders bei ausgeschlossenem Verkehr oder einer Tracking-Warteschlange.
Pflichtfelder und aktionsabhängige Parameter
Die allgemeine API verlangt idsite und rec=1: die Website-Kennung und den Schalter zur Aufzeichnung. url und action_name sind empfohlen, aber keine allgemeinen Pflichtfelder. Eine aussagekräftige Seitenadresse und ein Titel erleichtern trotzdem die Auswertung.
Weitere Anforderungen hängen von der Aktion ab: Ereignisse brauchen nicht leere Werte für e_c und e_a; eingerichtete Ziele verwenden idgoal. E-Commerce-Bestellungen benötigen die entsprechenden Bestellfelder einschließlich Bestellkennung und Umsatz. Textwerte müssen für die URL kodiert werden, damit etwa Leerzeichen oder kaufmännische Und-Zeichen nicht als Trennzeichen der Anfrage verstanden werden. Eine gültige Seitenaufruf-Anfrage ist deshalb noch keine gültige Kauf-Anfrage.
Besucherkennung und Besuchsgrenzen
Das dokumentierte Format von _id umfasst genau 16 Hexzeichen: Ziffern von 0 bis 9 und Buchstaben von a bis f. UUIDs und vollständige MD5-Hashes sind ungeeignete Eingabeformate. Die geprüfte Matomo-5.x-Implementierung kann eine längere _id allerdings vor der Dekodierung kürzen, statt den Wert abzulehnen. Der Sender sollte das dokumentierte Format prüfen und nicht auf dieses Verhalten vertrauen.
Ohne nutzbare Besucherkennung kann Matomo eine zeitlich begrenzte Konfigurationskennung aus Merkmalen wie IP-Adresse, Browser und Sprache verwenden. Gleiche Servermerkmale können fremde Aktivitäten zusammenführen. Daraus folgt kein einziger Besuch für den gesamten Tag: Besucherzuordnung und Besuchsgrenzen sind getrennte Fragen; die voreingestellte Inaktivitätsgrenze beträgt 30 Minuten. Eine hohe Ereigniszahl allein unterscheidet keinen Stapelauftrag von Bot-Verkehr.
Dimensionsnummer und Geltungsbereich
Eine Dimension ist ein zusätzliches Auswertungsfeld, etwa der gebuchte Tarif. Der Geltungsbereich legt fest, ob der Wert zum gesamten Besuch oder zu einer einzelnen Aktion gehört.
dimension1 verweist auf die eingerichtete Dimension mit der ID 1 im gewählten Website-Profil. Die Dimension muss existieren und aktiv sein; die Nummer legt kein neues Feld automatisch an.
Eine besuchsbezogene Dimension behält den zuletzt übermittelten Wert dieses Besuchs. Eine aktionsbezogene Dimension speichert einen Wert zur einzelnen Aktion. Der aktuelle Tarif kann einen Besuch beschreiben; der bei einem bestimmten Ereignis gewählte Tarif kann dieses Ereignis beschreiben. Beide Geltungsbereiche erlauben die Filterung von Berichten, beispielsweise auf Besuche oder Aktionen mit einem bestimmten Tarif.
Berechtigung, Zeitpunkte und Aufbewahrung
cip überschreibt die IP-Adresse; geografische Vorgaben und ältere Zeitpunkte benötigen ebenfalls eine Berechtigung. cdt akzeptiert einen UTC-Zeitpunkt (weltweite Zeitreferenz ohne lokale Zeitverschiebung) oder einen Unix-Zeitstempel (Sekunden seit dem 1. Januar 1970 UTC). Zeitpunkte innerhalb der letzten 24 Stunden benötigen normalerweise nicht allein wegen cdt ein Token; ältere Zeitpunkte schon. Fehlende Berechtigungen können Fehler auslösen, aber HTTP 400 ist keine vollständige oder allgemeingültige Diagnoseregel.
Ein Token ist ein geheimer Zugangsnachweis. Ein Tracking-Token ist kein reiner Schreibzugang. Je nach Berechtigung kann token_auth auch Berichte abrufen oder Verwaltungsaktionen ausführen. Ein eigenes Konto sollte nur die benötigten Schreibrechte für das betreffende Website-Profil erhalten. Matomo-5-Tokens erben die Kontorechte; Matomo 6 unterstützt zusätzlich eine Begrenzung der Tokenrechte. Tokens gehören in geschützte Speicher auf dem Server und in den Dateninhalt verschlüsselter HTTPS-POST-Anfragen, nicht in Browsercode oder URL-Protokolle. Auf sichere Anfragen beschränkte Tokens benötigen den unterstützten POST-Übertragungsweg.
Vor dem Import früherer Vorgänge ist zu prüfen, wie lange einzelne Messdatensätze (Rohdaten) aufbewahrt werden. Die geprüfte 5.x-Implementierung lehnt Zeitpunkte jenseits der eingestellten Löschgrenze einschließlich des Löschintervalls ab. Ungültige oder zukünftige Angaben können auf den Anfragezeitpunkt zurückfallen; deshalb muss auch das gespeicherte Datum geprüft werden. Historische Berichte benötigen anschließend eine Neuberechnung. Bereits gelöschte Rohdaten entstehen dadurch nicht erneut.
Fehlende oder falsch zugeordnete Hits prüfen
| Ursache | Was zu sehen ist |
|---|---|
| Fehlendes rec=1 | Die Aufzeichnung ist nicht aktiviert. |
| Falsche idsite | Eine gültige, aber falsche Nummer kann Daten falsch zuordnen; ein unbekanntes Profil kann einen Fehler auslösen. |
| Ungültige oder fehlende _id | Die Besucherzuordnung kann wechseln; vor dem Senden ist eine Prüfung auf 16 Hexzeichen nötig. |
| Altes cdt ohne Berechtigung | Zeitpunkte älter als 24 Stunden brauchen eine Berechtigung; Antwort und gespeichertes Datum benötigen eine Prüfung. |
| Inaktive oder unbekannte Dimension | Website-Profil, Dimensionsnummer und Aktivierung benötigen eine Prüfung. |
| Warteschlange oder Ausschluss | Verzögerungen, Bot-Behandlung und Ausschlussregeln können eine fehlende Aktion erklären. |
Ein Eintrag im Besucherprotokoll bestätigt die Speicherung der angezeigten Aktion. Ein fehlender Eintrag beweist allein keine Ablehnung: Website-Profil, Datum, Zeitzone, Segment, verfügbare Protokollansichten und Tracking-Warteschlange gehören zur Prüfung. Ein kleiner Test in einem eigenen Testprofil erleichtert den Vergleich. Vorübergehende Tracker-Diagnoseprotokolle einer selbst betriebenen Matomo-Installation (On-Premise) oder queuedtracking=0 können die Ursache eingrenzen; Tokens und Besucherdaten dürfen dabei nicht offengelegt werden.
Fragen und Antworten
Woher bekommt ein Server eine gültige _id, wenn derselbe Besucher auch im Browser gezählt wird?
Der JavaScript-Tracker stellt getVisitorId() über eine Funktion in der _paq-Warteschlange nach der Initialisierung bereit. Dadurch entfällt die Abhängigkeit von Cookie-Namen und internem Cookie-Aufbau. Eine im Messkonzept vorgesehene Browser-Server-Übergabe kann diese Kennung mit der auslösenden Aktion übertragen. Gleiche Kennungen unterstützen die Zuordnung, heben aber weder Besuchsgrenzen noch Datenschutzeinstellungen auf.
Für angemeldete Konten empfiehlt Matomo uid statt einer über cid erzwungenen Besucherkennung. Eine stabile interne Kennung vermeidet die unnötige Übertragung einer E-Mail-Adresse. Ein einfacher Hash einer vorhersehbaren Kundennummer anonymisiert nicht und lässt sich möglicherweise durch Durchprobieren rekonstruieren. Kennungen müssen zum Messkonzept und zu erforderlichen Einwilligungen passen; cookielose Messung rechtfertigt nicht automatisch eine dauerhafte Kundenkennung.
Warum zeigen serverseitige Treffer alle denselben Standort?
Eine direkte Backend-Anfrage trägt gewöhnlich die Netzwerkadresse des sendenden Servers. Der ermittelte Standort kann den Server beschreiben oder ungenau bleiben. Ein autorisiertes cip kann eine gesondert festgestellte Besucheradresse übergeben; auch die Konfiguration vertrauenswürdiger Proxys beeinflusst die Adressermittlung. Ein Proxy leitet Anfragen zwischen Systemen weiter. Header sind Kopfdaten einer Anfrage. Weitergereichte Adressfelder sind nur nach Prüfung ihrer Herkunft und der Proxy-Einstellungen vertrauenswürdig. Browsersprache und Geolokalisierungsanbieter können das Ergebnis beeinflussen. Ein Rechenzentrumsstandort ist daher ein Hinweis, keine Gewissheit.
Passend dazu
