{"id":10322,"date":"2026-08-30T12:20:00","date_gmt":"2026-08-30T10:20:00","guid":{"rendered":"https:\/\/www.lukaswojcik.com\/blog\/?p=10322"},"modified":"2026-10-24T03:12:38","modified_gmt":"2026-10-24T01:12:38","slug":"matomo-tracking-api-serverseitige-hits-pflichtparameter-und-die-fehler","status":"publish","type":"post","link":"https:\/\/www.lukaswojcik.com\/blog\/de\/digital-analytics-de\/matomo-tracking-api-serverseitige-hits-pflichtparameter-und-die-fehler\/","title":{"rendered":"Matomo-Tracking-API: Serverseitige Hits, Pflichtparameter und die Fehler, die trotzdem 200 liefern"},"content":{"rendered":"

Matomo kann einen Seitenaufruf, ein Ereignis oder ein Ziel \u00fcber eine HTTP-Anfrage an matomo.php<\/code> erfassen. Serverseitiges Tracking umfasst auch Vorg\u00e4nge au\u00dferhalb des Browsers, etwa best\u00e4tigte Bestellungen oder gek\u00fcndigte Mitgliedschaften. Ein Hit<\/strong> bezeichnet eine Tracking-Anfrage; ein Besuch kann mehrere Hits enthalten.<\/p>\n

Eine erfolgreiche HTTP-Antwort beweist noch keine korrekte Erfassung im vorgesehenen Website-Profil. Normale Antworten enthalten h\u00e4ufig ein transparentes GIF; send_image=0<\/code> fordert HTTP 204 ohne Bild an. \u00dcbertragung, Verarbeitung und Zuordnung ben\u00f6tigen getrennte Pr\u00fcfungen, besonders bei ausgeschlossenem Verkehr oder einer Tracking-Warteschlange.<\/p>\n

\n\"Pflichtfelder,
Pflichtfelder, Zuordnungsfelder und privilegierte Vorgaben erf\u00fcllen unterschiedliche Aufgaben. HTTP 200 oder 204 best\u00e4tigt allein keine korrekte Verarbeitung.<\/figcaption><\/figure>\n

Pflichtfelder und aktionsabh\u00e4ngige Parameter<\/h2>\n

Die allgemeine API verlangt idsite<\/code> und rec=1<\/code>: die Website-Kennung und den Schalter zur Aufzeichnung. url<\/code> und action_name<\/code> sind empfohlen, aber keine allgemeinen Pflichtfelder. Eine aussagekr\u00e4ftige Seitenadresse und ein Titel erleichtern trotzdem die Auswertung.<\/p>\n

Weitere Anforderungen h\u00e4ngen von der Aktion ab: Ereignisse brauchen nicht leere Werte f\u00fcr e_c<\/code> und e_a<\/code>; eingerichtete Ziele verwenden idgoal<\/code>. E-Commerce-Bestellungen ben\u00f6tigen die entsprechenden Bestellfelder einschlie\u00dflich Bestellkennung und Umsatz. Zeichenketten m\u00fcssen korrekt URL-kodiert werden. Eine g\u00fcltige Seitenaufruf-Anfrage ist deshalb noch keine g\u00fcltige Kauf-Anfrage.<\/p>\n

Besucherkennung und Besuchsgrenzen<\/h2>\n

Das dokumentierte Format von _id<\/code> umfasst genau 16 Hexzeichen. UUIDs und vollst\u00e4ndige MD5-Hashes sind ungeeignete Eingabeformate. Die gepr\u00fcfte Matomo-5.x-Implementierung kann eine l\u00e4ngere _id<\/code> allerdings vor der Dekodierung k\u00fcrzen, statt den Wert abzulehnen. Der Sender sollte das dokumentierte Format pr\u00fcfen und nicht auf dieses Verhalten vertrauen.<\/p>\n

Ohne nutzbare Besucherkennung kann Matomo eine zeitlich begrenzte Konfigurationskennung aus Merkmalen wie IP-Adresse, Browser und Sprache verwenden. Gleiche Servermerkmale k\u00f6nnen fremde Aktivit\u00e4ten zusammenf\u00fchren. Daraus folgt kein einziger Besuch f\u00fcr den gesamten Tag: Besucherzuordnung und Besuchsgrenzen sind getrennte Fragen; die voreingestellte Inaktivit\u00e4tsgrenze betr\u00e4gt 30 Minuten. Eine hohe Ereigniszahl allein unterscheidet keinen Stapelauftrag von Bot-Verkehr.<\/p>\n

Dimensionsnummer und Geltungsbereich<\/h2>\n

dimension1<\/code> verweist auf die eingerichtete Dimension mit der ID 1 im gew\u00e4hlten Website-Profil. Die Dimension muss existieren und aktiv sein; die Nummer legt kein neues Feld automatisch an.<\/p>\n

Eine besuchsbezogene Dimension beh\u00e4lt den zuletzt \u00fcbermittelten 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\u00e4hlte Tarif kann dieses Ereignis beschreiben. Beide Geltungsbereiche unterst\u00fctzen die Segmentierung.<\/p>\n

Berechtigung, Zeitpunkte und Aufbewahrung<\/h2>\n

cip<\/code> \u00fcberschreibt die IP-Adresse; geografische Vorgaben und \u00e4ltere Zeitpunkte ben\u00f6tigen ebenfalls eine Berechtigung. cdt<\/code> akzeptiert einen UTC-Zeitpunkt oder Unix-Zeitstempel. Zeitpunkte innerhalb der letzten 24 Stunden ben\u00f6tigen normalerweise nicht allein wegen cdt<\/code> ein Token; \u00e4ltere Zeitpunkte schon. Fehlende Berechtigungen k\u00f6nnen Fehler ausl\u00f6sen, aber HTTP 400 ist keine vollst\u00e4ndige oder allgemeing\u00fcltige Diagnoseregel.<\/p>\n

Ein Tracking-Token ist kein reiner Schreibzugang.<\/strong> Je nach Berechtigung kann token_auth<\/code> auch Berichte abrufen oder Verwaltungsaktionen ausf\u00fchren. Ein eigenes Konto sollte nur die ben\u00f6tigten Schreibrechte f\u00fcr das betreffende Website-Profil erhalten. Matomo-5-Tokens erben die Kontorechte; Matomo 6 unterst\u00fctzt zus\u00e4tzlich eine Begrenzung der Tokenrechte. Tokens geh\u00f6ren in serverseitige Geheimnisspeicher und HTTPS-POST-Nutzlasten, nicht in Browsercode oder URL-Protokolle. Auf sichere Anfragen beschr\u00e4nkte Tokens ben\u00f6tigen den unterst\u00fctzten POST-\u00dcbertragungsweg.<\/p>\n

Vor einem Nachimport sind die Aufbewahrungsregeln f\u00fcr Rohdaten zu pr\u00fcfen. Die gepr\u00fcfte 5.x-Implementierung lehnt Zeitpunkte jenseits der eingestellten L\u00f6schgrenze einschlie\u00dflich des L\u00f6schintervalls ab. Ung\u00fcltige oder zuk\u00fcnftige Angaben k\u00f6nnen auf den Anfragezeitpunkt zur\u00fcckfallen; deshalb muss auch das gespeicherte Datum gepr\u00fcft werden. Historische Berichte ben\u00f6tigen anschlie\u00dfend eine Neuberechnung. Bereits gel\u00f6schte Rohdaten entstehen dadurch nicht erneut.<\/p>\n

Fehlende oder falsch zugeordnete Hits pr\u00fcfen<\/h2>\n\n\n\n\n\n\n\n\n\n\n
Ursache<\/th>\nWas zu sehen ist<\/th>\n<\/tr>\n<\/thead>\n
Fehlendes rec=1<\/td>\nDie Aufzeichnung ist nicht aktiviert.<\/td>\n<\/tr>\n
Falsche idsite<\/td>\nEine g\u00fcltige, aber falsche Nummer kann Daten falsch zuordnen; ein unbekanntes Profil kann einen Fehler ausl\u00f6sen.<\/td>\n<\/tr>\n
Ung\u00fcltige oder fehlende _id<\/td>\nDie Besucherzuordnung kann wechseln; vor dem Senden 16 Hexzeichen pr\u00fcfen.<\/td>\n<\/tr>\n
Altes cdt ohne Berechtigung<\/td>\nZeitpunkte \u00e4lter als 24 Stunden brauchen eine Berechtigung; Antwort und gespeichertes Datum pr\u00fcfen.<\/td>\n<\/tr>\n
Inaktive oder unbekannte Dimension<\/td>\nWebsite-Profil, Dimensionsnummer und Aktivierung pr\u00fcfen.<\/td>\n<\/tr>\n
Warteschlange oder Ausschluss<\/td>\nVerz\u00f6gerungen, Bot-Behandlung und Ausschlussregeln k\u00f6nnen eine fehlende Aktion erkl\u00e4ren.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

Ein Eintrag im Besucherprotokoll best\u00e4tigt die Speicherung der angezeigten Aktion. Ein fehlender Eintrag beweist allein keine Ablehnung: Website-Profil, Datum, Zeitzone, Segment, verf\u00fcgbare Protokollansichten und Tracking-Warteschlange geh\u00f6ren zur Pr\u00fcfung. Ein kleiner Test in einem eigenen Testprofil erleichtert den Vergleich. Vor\u00fcbergehende Tracker-Diagnoseprotokolle bei On-Premise oder queuedtracking=0<\/code> k\u00f6nnen die Ursache eingrenzen; Tokens und Besucherdaten d\u00fcrfen dabei nicht offengelegt werden.<\/p>\n

\n

Fragen und Antworten<\/h2>\n

Woher bekommt ein Server eine g\u00fcltige _id, wenn derselbe Besucher auch im Browser gez\u00e4hlt wird?<\/h3>\n

Der JavaScript-Tracker stellt getVisitorId()<\/code> \u00fcber eine Funktion in der _paq<\/code>-Warteschlange nach der Initialisierung bereit. Dadurch entf\u00e4llt die Abh\u00e4ngigkeit von Cookie-Namen und internem Cookie-Aufbau. Eine im Messkonzept vorgesehene Browser-Server-\u00dcbergabe kann diese Kennung mit der ausl\u00f6senden Aktion \u00fcbertragen. Gleiche Kennungen unterst\u00fctzen die Zuordnung, heben aber weder Besuchsgrenzen noch Datenschutzeinstellungen auf.<\/p>\n

F\u00fcr angemeldete Konten empfiehlt Matomo uid<\/code> statt einer \u00fcber cid<\/code> erzwungenen Besucherkennung. Eine stabile interne Kennung vermeidet die unn\u00f6tige \u00dcbertragung einer E-Mail-Adresse. Ein einfacher Hash einer vorhersehbaren Kundennummer anonymisiert nicht und l\u00e4sst sich m\u00f6glicherweise durch Durchprobieren rekonstruieren. Kennungen m\u00fcssen zum Messkonzept und zu erforderlichen Einwilligungen passen; cookielose Messung rechtfertigt nicht automatisch eine dauerhafte Kundenkennung.<\/p>\n

Warum zeigen serverseitige Treffer alle denselben Standort?<\/h3>\n

Eine direkte Backend-Anfrage tr\u00e4gt gew\u00f6hnlich die Netzwerkadresse des sendenden Servers. Der ermittelte Standort kann den Server beschreiben oder ungenau bleiben. Ein autorisiertes cip<\/code> kann eine gesondert festgestellte Besucheradresse \u00fcbergeben; auch die Konfiguration vertrauensw\u00fcrdiger Proxys beeinflusst die Adressermittlung. Beliebige weitergeleitete Header sind nicht vertrauensw\u00fcrdig. Browsersprache und Geolokalisierungsanbieter k\u00f6nnen das Ergebnis beeinflussen. Ein Rechenzentrumsstandort ist daher ein Hinweis, keine Gewissheit.<\/p>\n<\/div>\n

\n

Quellen<\/h2>\n