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

Matomo da się zasilać bez jednej linii JavaScriptu: pojedyncze zapytanie HTTP do matomo.php niesie odsłonę, zdarzenie albo cel. Czyni to z niego oczywistą drogę do zapisania tego, czego przeglądarka nigdy nie widzi – zamówienia potwierdzonego w zapleczu, członkostwa wypowiedzianego telefonicznie, zakończonego zadania wsadowego.

Cecha, która czyni go wygodnym, jest zarazem tą, która utrudnia szukanie błędów. Punkt końcowy odpowiada niemal na każde zapytanie tak samo: HTTP 200 i pusty obrazek, niezależnie od tego, czy trafienie zapisano, po cichu odrzucono, czy zaliczono do niewłaściwej witryny. Wszystko poniżej dotyczy rozróżnienia tych trzech przypadków bez pomocy ze strony odpowiedzi.

Czego trafienie wymaga co najmniej

O tym, czy cokolwiek zostanie zapisane, rozstrzygają trzy parametry: idsite dla witryny, do której trafienie należy, rec=1 jako przełącznik zamieniający zapytanie w zapis oraz coś, co trafienie nazywa – url, action_name albo jedno i drugie. Bez rec=1 zapytanie zostaje obsłużone dokładnie tak samo, a zapisane nie zostaje nic.

Wszystko dalsze jest dobrowolne w tym sensie, że trafienie przetrwa i bez tego, a rzadko dobrowolne w tym sensie, że raport pozostanie użyteczny. Trafienie bez adresu pojawia się w raportach bez nazwy – to ten rodzaj wpisu, który zauważa się po miesiącach i którego już nie da się do niczego przypisać.

Identyfikator odwiedzającego rozstrzyga o całej reszcie

Parametr _id to identyfikator odwiedzającego złożony z dokładnie szesnastu znaków szesnastkowych. Nie piętnastu, nie UUID z myślnikami, nie trzydziestu dwóch znaków skrótu MD5 – co chybia format, Matomo pomija po cichu, a nacisk leży na słowie po cichu.

To, co dzieje się dalej, jest gorsze niż błąd. Bez użytecznego _id Matomo wyprowadza odwiedzającego z adresu IP i identyfikatora przeglądarki, co w przeglądarce działa znośnie, a na serwerze się załamuje: każde trafienie przychodzi z tego samego adresu z tym samym identyfikatorem, więc ruch całego dnia scala się w jednego odwiedzającego o niezwykłej liczbie akcji.

Rozpoznaje się to po raporcie, w którym jeden odwiedzający skupia większość zdarzeń, podczas gdy liczba wizyt pozostaje płaska. To nie bot, tylko zadanie wsadowe bez identyfikatora.

Wymiary własne to tylko numery

Wymiary przekazuje się jako dimension1, dimension2 i tak dalej, a numer nie jest nazwą – odsyła do miejsca, które musi istnieć w interfejsie Matomo, zanim da się cokolwiek do niego zapisać. Wartość wysłana pod nieskonfigurowany numer zostaje przyjęta i odrzucona.

Drugą rzeczą do trafienia jest zakres. Wymiar o zakresie wizyty trzyma jedną wartość na wizytę i zostaje nadpisany przez każde późniejsze trafienie, które go niesie; wymiar o zakresie akcji trzyma jedną wartość na akcję. Nazwa taryfy w niewłaściwym zakresie daje albo wartość zmieniającą się z ostatnią odsłoną, albo taką, której nie da się użyć jako segmentu w obrębie wizyty.

Co wolno wysłać wyłącznie serwerowi

Garść parametrów zmienia dane, których zapytanie normalnie nie może dotykać: cip dla prawdziwego adresu IP odwiedzającego, cdt dla momentu innego niż teraz, do tego pola geograficzne. Wszystkie wymagają token_auth, cdt jednak dopiero dla momentów sprzed ponad 24 godzin. Bez tokenu tam, gdzie jest wymagany, Matomo odrzuca całe zapytanie z kodem HTTP 400.

Token należy do serwera i do nikąd indziej. W przeglądarce odczyta go każdy odwiedzający, a daje on nie prawo odczytu, lecz zapisu: kto go ma, zapisuje dowolne trafienia do statystyk, których potem nie sposób odróżnić od prawdziwych. Tam, gdzie strona sama musi wysyłać trafienia, po prostu nie dołącza tych parametrów.

Z tokenem Matomo przyjmuje także starsze znaczniki czasu, o ile nie wykraczają poza ustawiony okres usuwania surowych danych. Tydzień historii da się więc uzupełnić przez cdt; raporty za te dni wymagają potem jednak ponownego przetworzenia.

Dlaczego trafienie znika bez słowa

Kontrolą, która kończy większość z tego w minutę, jest dziennik odwiedzin z otwartym podglądem na żywo w chwili wysyłania zapytania. Trafienie, które się tam pojawi, jest zapisane; to, którego brak, zostało odrzucone, a powyższa lista mówi, gdzie szukać. Odpowiedź nie powie tego nigdy.