Matomo Tracking API: hity po stronie serwera, parametry obowiązkowe i błędy, które mimo to zwracają 200

Matomo może zapisać odsłonę, zdarzenie albo cel przez żądanie HTTP do matomo.php. Pomiar po stronie serwera obejmuje także działania poza przeglądarką, na przykład potwierdzone zamówienie lub anulowaną subskrypcję. Hit oznacza jedno żądanie pomiarowe; wizyta może obejmować wiele hitów.

HTTP to mechanizm żądań i odpowiedzi używany w sieci WWW. API jest interfejsem Matomo odbierającym dane z programów. Kod odpowiedzi, np. 200 lub 204, opisuje wynik na tym interfejsie. Zapisana akcja i przypisana witryna nadal wymagają kontroli. Kolejka przechowuje żądania pomiarowe do późniejszego przetworzenia.

Udana odpowiedź HTTP nie dowodzi poprawnego zapisu w odpowiedniej witrynie. Zwykła odpowiedź często zawiera przezroczysty GIF; send_image=0 żąda HTTP 204 bez obrazka. Przesłanie, przetworzenie i przypisanie danych wymagają osobnych kontroli, zwłaszcza przy wykluczonym ruchu lub kolejce pomiarowej.

Parametry obowiązkowe i wymagania akcji

Ogólne wymagania API obejmują idsite oraz rec=1: identyfikator witryny i przełącznik zapisu. url i action_name są zalecane, lecz nie należą do ogólnych parametrów obowiązkowych. Zrozumiały adres strony i tytuł nadal ułatwiają interpretację raportów.

Dalsze wymagania zależą od akcji: zdarzenia potrzebują niepustych wartości e_c i e_a, a skonfigurowane cele korzystają z idgoal. Zamówienia e-commerce wymagają odpowiednich pól, w tym identyfikatora zamówienia i przychodu. Tekst wymaga kodowania URL, aby np. spacje i znaki & nie zostały potraktowane jako separatory żądania. Prawidłowe żądanie odsłony nie staje się automatycznie prawidłowym żądaniem zakupu.

Identyfikator odwiedzającego a granice wizyty

Udokumentowany format _id obejmuje dokładnie 16 znaków szesnastkowych: cyfry 0–9 i litery a–f. UUID i pełny skrót MD5 są nieodpowiednimi formatami wejściowymi. Sprawdzona implementacja Matomo 5.x może jednak skrócić dłuższe _id przed dekodowaniem zamiast odrzucić wartość. Nadawca powinien sprawdzać udokumentowany format, zamiast polegać na tym zachowaniu.

Bez użytecznego identyfikatora odwiedzającego Matomo może wykorzystać czasowy identyfikator konfiguracji oparty na takich cechach jak adres IP, przeglądarka i język. Jednakowe cechy serwera mogą połączyć niezwiązane działania. Nie oznacza to jednej wizyty przez cały dzień: identyfikacja odwiedzającego i granice wizyty to osobne kwestie, a domyślny limit bezczynności wynosi 30 minut. Sama duża liczba zdarzeń nie odróżnia zadania wsadowego od ruchu botów.

Numer i zakres wymiaru

Wymiar to dodatkowe pole raportowe, np. plan abonamentowy. Zakres określa, czy wartość dotyczy całej wizyty, czy jednej akcji.

dimension1 wskazuje skonfigurowany wymiar o ID 1 w wybranej witrynie. Wymiar musi istnieć i być aktywny; numer nie tworzy automatycznie nowego pola.

Wymiar na poziomie wizyty przechowuje ostatnią przekazaną wartość dla tej wizyty. Wymiar na poziomie akcji przechowuje wartość dla konkretnej akcji. Aktualny plan abonamentowy może opisywać wizytę; plan wybrany podczas konkretnego zdarzenia może opisywać to zdarzenie. Oba zakresy pozwalają filtrować raporty, np. do wizyt lub akcji z określonym planem abonamentowym.

Uprawnienia, czas i przechowywanie danych

cip nadpisuje adres IP; nadpisywanie lokalizacji i starsze znaczniki czasu również wymagają uprawnień. cdt przyjmuje datę i czas UTC (wspólny punkt odniesienia bez lokalnego przesunięcia strefy czasowej) albo znacznik Unix (sekundy od 1 stycznia 1970 UTC). Czas z ostatnich 24 godzin zwykle nie wymaga tokenu wyłącznie z powodu cdt; starszy czas wymaga tokenu. Brak uprawnień może wywołać błąd, ale HTTP 400 nie stanowi pełnej ani uniwersalnej reguły diagnostycznej.

Token jest tajnym poświadczeniem dostępu. Token pomiarowy nie zapewnia wyłącznie prawa zapisu. Zależnie od uprawnień token_auth umożliwia także pobieranie raportów lub operacje administracyjne. Osobne konto powinno otrzymać tylko niezbędne prawo zapisu do właściwej witryny. Tokeny Matomo 5 dziedziczą uprawnienia konta; Matomo 6 dodatkowo obsługuje limit uprawnień tokenu. Tokeny powinny pozostawać w serwerowym magazynie sekretów i treści żądań HTTPS POST, poza kodem przeglądarki i logami adresów URL. Tokeny ograniczone do bezpiecznych żądań wymagają obsługiwanego sposobu przesyłania przez POST.

Przed importem wcześniejszych działań potrzebna jest kontrola czasu przechowywania pojedynczych rekordów pomiarowych, czyli danych surowych. Sprawdzona implementacja 5.x odrzuca daty przekraczające skonfigurowaną granicę usuwania, uwzględniającą odstęp między cyklami usuwania. Nieprawidłowa lub przyszła data może zostać zastąpiona czasem żądania, dlatego kontrola powinna obejmować zapisany czas. Raporty historyczne wymagają następnie ponownego przeliczenia. Przeliczenie nie odtwarza już usuniętych rekordów surowych.

Kontrola brakujących lub błędnie przypisanych hitów

Wpis w dzienniku odwiedzin potwierdza zapis wyświetlanej akcji. Brak wpisu nie dowodzi odrzucenia: kontroli wymagają witryna, data, strefa czasowa, segment, dostępność widoków dziennika oraz kolejka pomiarowa. Mały test w osobnej witrynie testowej ułatwia porównanie. Tymczasowe logowanie diagnostyczne trackera we własnej instalacji Matomo (On-Premise) lub queuedtracking=0 może zawęzić przyczynę; diagnostyka nie powinna ujawniać tokenów ani danych odwiedzających.