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.

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. Ciągi znaków wymagają poprawnego kodowania URL. 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. 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

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 obsługują segmentację.

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 albo znacznik Unix. 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 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 historii potrzebna jest kontrola zasad przechowywania 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 On-Premise lub queuedtracking=0 może zawęzić przyczynę; diagnostyka nie powinna ujawniać tokenów ani danych odwiedzających.