{"id":10324,"date":"2026-08-30T18:00:00","date_gmt":"2026-08-30T16:00:00","guid":{"rendered":"https:\/\/www.lukaswojcik.com\/blog\/?p=10324"},"modified":"2026-10-24T03:12:38","modified_gmt":"2026-10-24T01:12:38","slug":"matomo-tracking-api-hity-po-stronie-serwera-parametry-obowiazkowe-i-bledy","status":"publish","type":"post","link":"https:\/\/www.lukaswojcik.com\/blog\/pl\/digital-analytics-pl\/matomo-tracking-api-hity-po-stronie-serwera-parametry-obowiazkowe-i-bledy\/","title":{"rendered":"Matomo Tracking API: hity po stronie serwera, parametry obowi\u0105zkowe i b\u0142\u0119dy, kt\u00f3re mimo to zwracaj\u0105 200"},"content":{"rendered":"

Matomo mo\u017ce zapisa\u0107 ods\u0142on\u0119, zdarzenie albo cel przez \u017c\u0105danie HTTP do matomo.php<\/code>. Pomiar po stronie serwera obejmuje tak\u017ce dzia\u0142ania poza przegl\u0105dark\u0105, na przyk\u0142ad potwierdzone zam\u00f3wienie lub anulowan\u0105 subskrypcj\u0119. Hit<\/strong> oznacza jedno \u017c\u0105danie pomiarowe; wizyta mo\u017ce obejmowa\u0107 wiele hit\u00f3w.<\/p>\n

Udana odpowied\u017a HTTP nie dowodzi poprawnego zapisu w odpowiedniej witrynie. Zwyk\u0142a odpowied\u017a cz\u0119sto zawiera przezroczysty GIF; send_image=0<\/code> \u017c\u0105da HTTP 204 bez obrazka. Przes\u0142anie, przetworzenie i przypisanie danych wymagaj\u0105 osobnych kontroli, zw\u0142aszcza przy wykluczonym ruchu lub kolejce pomiarowej.<\/p>\n

\n\"Pola
Pola obowi\u0105zkowe, pola przypisania i uprzywilejowane nadpisania pe\u0142ni\u0105 r\u00f3\u017cne funkcje. HTTP 200 lub 204 nie potwierdza poprawnego przetworzenia.<\/figcaption><\/figure>\n

Parametry obowi\u0105zkowe i wymagania akcji<\/h2>\n

Og\u00f3lne wymagania API obejmuj\u0105 idsite<\/code> oraz rec=1<\/code>: identyfikator witryny i prze\u0142\u0105cznik zapisu. url<\/code> i action_name<\/code> s\u0105 zalecane, lecz nie nale\u017c\u0105 do og\u00f3lnych parametr\u00f3w obowi\u0105zkowych. Zrozumia\u0142y adres strony i tytu\u0142 nadal u\u0142atwiaj\u0105 interpretacj\u0119 raport\u00f3w.<\/p>\n

Dalsze wymagania zale\u017c\u0105 od akcji: zdarzenia potrzebuj\u0105 niepustych warto\u015bci e_c<\/code> i e_a<\/code>, a skonfigurowane cele korzystaj\u0105 z idgoal<\/code>. Zam\u00f3wienia e-commerce wymagaj\u0105 odpowiednich p\u00f3l, w tym identyfikatora zam\u00f3wienia i przychodu. Ci\u0105gi znak\u00f3w wymagaj\u0105 poprawnego kodowania URL. Prawid\u0142owe \u017c\u0105danie ods\u0142ony nie staje si\u0119 automatycznie prawid\u0142owym \u017c\u0105daniem zakupu.<\/p>\n

Identyfikator odwiedzaj\u0105cego a granice wizyty<\/h2>\n

Udokumentowany format _id<\/code> obejmuje dok\u0142adnie 16 znak\u00f3w szesnastkowych. UUID i pe\u0142ny skr\u00f3t MD5 s\u0105 nieodpowiednimi formatami wej\u015bciowymi. Sprawdzona implementacja Matomo 5.x mo\u017ce jednak skr\u00f3ci\u0107 d\u0142u\u017csze _id<\/code> przed dekodowaniem zamiast odrzuci\u0107 warto\u015b\u0107. Nadawca powinien sprawdza\u0107 udokumentowany format, zamiast polega\u0107 na tym zachowaniu.<\/p>\n

Bez u\u017cytecznego identyfikatora odwiedzaj\u0105cego Matomo mo\u017ce wykorzysta\u0107 czasowy identyfikator konfiguracji oparty na takich cechach jak adres IP, przegl\u0105darka i j\u0119zyk. Jednakowe cechy serwera mog\u0105 po\u0142\u0105czy\u0107 niezwi\u0105zane dzia\u0142ania. Nie oznacza to jednej wizyty przez ca\u0142y dzie\u0144: identyfikacja odwiedzaj\u0105cego i granice wizyty to osobne kwestie, a domy\u015blny limit bezczynno\u015bci wynosi 30 minut. Sama du\u017ca liczba zdarze\u0144 nie odr\u00f3\u017cnia zadania wsadowego od ruchu bot\u00f3w.<\/p>\n

Numer i zakres wymiaru<\/h2>\n

dimension1<\/code> wskazuje skonfigurowany wymiar o ID 1 w wybranej witrynie. Wymiar musi istnie\u0107 i by\u0107 aktywny; numer nie tworzy automatycznie nowego pola.<\/p>\n

Wymiar na poziomie wizyty przechowuje ostatni\u0105 przekazan\u0105 warto\u015b\u0107 dla tej wizyty. Wymiar na poziomie akcji przechowuje warto\u015b\u0107 dla konkretnej akcji. Aktualny plan abonamentowy mo\u017ce opisywa\u0107 wizyt\u0119; plan wybrany podczas konkretnego zdarzenia mo\u017ce opisywa\u0107 to zdarzenie. Oba zakresy obs\u0142uguj\u0105 segmentacj\u0119.<\/p>\n

Uprawnienia, czas i przechowywanie danych<\/h2>\n

cip<\/code> nadpisuje adres IP; nadpisywanie lokalizacji i starsze znaczniki czasu r\u00f3wnie\u017c wymagaj\u0105 uprawnie\u0144. cdt<\/code> przyjmuje dat\u0119 i czas UTC albo znacznik Unix. Czas z ostatnich 24 godzin zwykle nie wymaga tokenu wy\u0142\u0105cznie z powodu cdt<\/code>; starszy czas wymaga tokenu. Brak uprawnie\u0144 mo\u017ce wywo\u0142a\u0107 b\u0142\u0105d, ale HTTP 400 nie stanowi pe\u0142nej ani uniwersalnej regu\u0142y diagnostycznej.<\/p>\n

Token pomiarowy nie zapewnia wy\u0142\u0105cznie prawa zapisu.<\/strong> Zale\u017cnie od uprawnie\u0144 token_auth<\/code> umo\u017cliwia tak\u017ce pobieranie raport\u00f3w lub operacje administracyjne. Osobne konto powinno otrzyma\u0107 tylko niezb\u0119dne prawo zapisu do w\u0142a\u015bciwej witryny. Tokeny Matomo 5 dziedzicz\u0105 uprawnienia konta; Matomo 6 dodatkowo obs\u0142uguje limit uprawnie\u0144 tokenu. Tokeny powinny pozostawa\u0107 w serwerowym magazynie sekret\u00f3w i tre\u015bci \u017c\u0105da\u0144 HTTPS POST, poza kodem przegl\u0105darki i logami adres\u00f3w URL. Tokeny ograniczone do bezpiecznych \u017c\u0105da\u0144 wymagaj\u0105 obs\u0142ugiwanego sposobu przesy\u0142ania przez POST.<\/p>\n

Przed importem historii potrzebna jest kontrola zasad przechowywania danych surowych. Sprawdzona implementacja 5.x odrzuca daty przekraczaj\u0105ce skonfigurowan\u0105 granic\u0119 usuwania, uwzgl\u0119dniaj\u0105c\u0105 odst\u0119p mi\u0119dzy cyklami usuwania. Nieprawid\u0142owa lub przysz\u0142a data mo\u017ce zosta\u0107 zast\u0105piona czasem \u017c\u0105dania, dlatego kontrola powinna obejmowa\u0107 zapisany czas. Raporty historyczne wymagaj\u0105 nast\u0119pnie ponownego przeliczenia. Przeliczenie nie odtwarza ju\u017c usuni\u0119tych rekord\u00f3w surowych.<\/p>\n

Kontrola brakuj\u0105cych lub b\u0142\u0119dnie przypisanych hit\u00f3w<\/h2>\n\n\n\n\n\n\n\n\n\n\n
Przyczyna<\/th>\nCo wida\u0107<\/th>\n<\/tr>\n<\/thead>\n
Brak rec=1<\/td>\nZapis nie jest w\u0142\u0105czony.<\/td>\n<\/tr>\n
B\u0142\u0119dne idsite<\/td>\nPoprawny, lecz niew\u0142a\u015bciwy numer mo\u017ce b\u0142\u0119dnie przypisa\u0107 dane; nieznana witryna mo\u017ce wywo\u0142a\u0107 b\u0142\u0105d.<\/td>\n<\/tr>\n
B\u0142\u0119dne lub brakuj\u0105ce _id<\/td>\nPrzypisanie odwiedzaj\u0105cego mo\u017ce si\u0119 zmieni\u0107; potrzebna jest walidacja 16 znak\u00f3w szesnastkowych.<\/td>\n<\/tr>\n
Stare cdt bez uprawnie\u0144<\/td>\nCzas sprzed ponad 24 godzin wymaga uprawnie\u0144; kontroli wymagaj\u0105 odpowied\u017a i zapisany czas.<\/td>\n<\/tr>\n
Nieaktywny lub nieznany wymiar<\/td>\nKontroli wymagaj\u0105 witryna, numer wymiaru i aktywacja.<\/td>\n<\/tr>\n
Kolejka lub wykluczenie<\/td>\nOp\u00f3\u017anienia, obs\u0142uga bot\u00f3w i regu\u0142y wykluczania mog\u0105 wyja\u015bnia\u0107 brak akcji.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

Wpis w dzienniku odwiedzin potwierdza zapis wy\u015bwietlanej akcji. Brak wpisu nie dowodzi odrzucenia: kontroli wymagaj\u0105 witryna, data, strefa czasowa, segment, dost\u0119pno\u015b\u0107 widok\u00f3w dziennika oraz kolejka pomiarowa. Ma\u0142y test w osobnej witrynie testowej u\u0142atwia por\u00f3wnanie. Tymczasowe logowanie diagnostyczne trackera On-Premise lub queuedtracking=0<\/code> mo\u017ce zaw\u0119zi\u0107 przyczyn\u0119; diagnostyka nie powinna ujawnia\u0107 token\u00f3w ani danych odwiedzaj\u0105cych.<\/p>\n

\n

Pytania i odpowiedzi<\/h2>\n

Sk\u0105d serwer ma wzi\u0105\u0107 poprawny _id, je\u015bli ten sam odwiedzaj\u0105cy jest liczony tak\u017ce w przegl\u0105darce?<\/h3>\n

Tracker JavaScript udost\u0119pnia getVisitorId()<\/code> przez funkcj\u0119 w kolejce _paq<\/code> po inicjalizacji. Pozwala to unikn\u0105\u0107 zale\u017cno\u015bci od nazw i wewn\u0119trznego formatu ciasteczek. Przewidziane w projekcie pomiaru przekazanie danych z przegl\u0105darki do serwera mo\u017ce do\u0142\u0105czy\u0107 identyfikator do wywo\u0142uj\u0105cej akcji. Zgodne identyfikatory wspieraj\u0105 przypisanie, lecz nie znosz\u0105 granic wizyt ani ustawie\u0144 prywatno\u015bci.<\/p>\n

Dla zalogowanych kont Matomo zaleca uid<\/code> zamiast wymuszania identyfikatora odwiedzaj\u0105cego przez cid<\/code>. Sta\u0142y identyfikator wewn\u0119trzny ogranicza zb\u0119dne przesy\u0142anie adresu e-mail. Zwyk\u0142y skr\u00f3t przewidywalnego numeru klienta nie anonimizuje danych i mo\u017ce zosta\u0107 odtworzony przez sprawdzanie kolejnych numer\u00f3w. U\u017cycie identyfikator\u00f3w musi odpowiada\u0107 projektowi pomiaru i wymaganym zgodom; pomiar bez ciasteczek nie uzasadnia automatycznie trwa\u0142ego identyfikatora klienta.<\/p>\n

Dlaczego wszystkie trafienia po stronie serwera pokazuj\u0105 t\u0119 sam\u0105 lokalizacj\u0119?<\/h3>\n

Bezpo\u015brednie \u017c\u0105danie z backendu zwykle niesie adres sieciowy serwera nadawcy. Ustalona lokalizacja mo\u017ce opisywa\u0107 serwer albo pozosta\u0107 niedok\u0142adna. Autoryzowany parametr cip<\/code> pozwala przekaza\u0107 oddzielnie ustalony adres odwiedzaj\u0105cego; konfiguracja zaufanych serwer\u00f3w proxy tak\u017ce wp\u0142ywa na ustalanie adresu. Dowolne nag\u0142\u00f3wki przekazywane dalej nie s\u0105 wiarygodnym \u017ar\u00f3d\u0142em. J\u0119zyk przegl\u0105darki i dostawca geolokalizacji mog\u0105 wp\u0142ywa\u0107 na wynik. Lokalizacja centrum danych jest zatem wskaz\u00f3wk\u0105, a nie pewno\u015bci\u0105.<\/p>\n<\/div>\n

\n

\u0179r\u00f3d\u0142a<\/h2>\n