Publiczne API i Klucze API

1. Przegląd

API MousePlayer pozwala pobierać dane z Twojego Workspace do własnych dashboardów, hurtowni danych lub wewnętrznych narzędzi. Poza przypisywaniem identyfikatorów klientów do sesji (identify, wymaga klucza z prawem zapisu, zob. zakresy kluczy) jest ono tylko do odczytu: przez API nie można zmieniać ani usuwać danych.

• Bazowy URL: https://www.mouseplayer.com/api/v1/
• Wszystkie odpowiedzi są w formacie JSON.
• Każde zapytanie jest uwierzytelniane kluczem API i automatycznie ograniczone do Workspace, do którego ten klucz należy — klucz z jednego Workspace nigdy nie zobaczy danych innego, nawet przez przypadek.
• Pełne nagranie Session Replay (ruchy myszy, snapshoty DOM) nie jest udostępniane przez API. Otrzymujesz metadane sesji, pageviews, Custom Events i segmenty — wystarczająco, by budować raporty i dashboardy bez przesyłania surowego payloadu nagrania.

2. Uwierzytelnianie

Twórz i zarządzaj kluczami API w sekcji Klucze API w menu konta (/api-keys). Tylko właściciele i administratorzy Workspace mogą tworzyć lub unieważniać klucze.

Wysyłaj klucz jako token Bearer w nagłówku Authorization każdego zapytania:

Brakujący, błędny lub unieważniony klucz zwraca odpowiedź 401:

Wymagany plan

REST API jest częścią planów Business i Enterprise. Liczy się plan właściciela Workspace — zaproszeni członkowie zespołu go dziedziczą. Sprawdzenie odbywa się przy każdym zapytaniu, nie tylko przy tworzeniu klucza: po obniżeniu planu istniejące klucze zwracają 403.

Zakres uprawnień kluczy

Każdy klucz niesie swój zakres we własnym prefiksie. Po samym kluczu widać, co wolno mu zrobić — w .env, w zgłoszeniu, w terminalu.

3. Limity zapytań (Rate Limits)

Każdy klucz API jest ograniczony do 60 zapytań na minutę, liczonych w kroczącym oknie czasowym. Po przekroczeniu tego limitu zapytania otrzymują odpowiedź 429, aż okno się zresetuje:

4. Endpointy

GET/api/v1/projects

Zwraca listę wszystkich projektów (śledzonych Property) w Twoim Workspace.

GET/api/v1/projects/{channelid}/sessions

Zwraca listę sesji odwiedzających zarejestrowanych dla projektu, od najnowszych. Paginowane.

GET/api/v1/sessions/{session_id}

Metadane pojedynczej sesji wraz z jej pageviews. Pełny payload nagrania jest celowo pominięty — użyj do tego Playera w dashboardzie.

GET/api/v1/sessions/{session_id}/events

Custom Events wywołane w trakcie sesji (te same, które wysyłasz przez mp('event', ...)), wraz z ich parametrami.

GET/api/v1/projects/{channelid}/segments

Zwraca listę segmentów odwiedzających zdefiniowanych dla projektu (zarówno specyficznych dla projektu, jak i wspólnych dla całego Workspace).

5. Dołączanie identyfikatora klienta z własnego backendu

Przeglądarka często w ogóle nie wie, kto przy niej siedzi. W produkcie B2B tożsamość jest znana dopiero po zalogowaniu — a to dzieje się w backendzie. W sklepie dopiero przy potwierdzeniu zamówienia. Dokładnie na ten moment jest ten endpoint.

POST /api/v1/sessions/{session_id}/identify
Authorization: Bearer mp_live_xxxxxxxxxxxx
Content-Type: application/json

{"user_id": "customer-4711"}

// 200 OK
{"data": {"session_id": "s_a1b2c3", "user_id": "customer-4711",
          "changed": true, "previous": null, "webhook_queued": true}}

Identyfikator pojawia się następnie na liście sesji, można go tam wyszukiwać, a webhook session_identified zostaje wysłany — tak trafia do Twojego CRM.

6. Webhooki: weryfikacja podpisu

Webhooki konfiguruje się per projekt w sekcji Integracje; tam znajduje się też sekret podpisu. Każda dostawa niesie te nagłówki:

Podpis to HMAC-SHA256 z timestamp + "." + surowe ciało, kluczowany sekretem podpisu Twojego projektu.

// PHP
$erwartet = 'sha256=' . hash_hmac('sha256', $timestamp . '.' . $rawBody, $secret);
if (!hash_equals($erwartet, $signature)) { http_response_code(401); exit; }

// Node
const expected = 'sha256=' + crypto.createHmac('sha256', secret)
                                     .update(timestamp + '.' + rawBody).digest('hex');

Dostarczanie i ponowienia

Nieudana dostawa jest ponawiana po 1 min, 5 min, 15 min, 1 h i 6 h, potem porzucana. Odpowiedzi 4xx inne niż 408 i 429 nie są ponawiane — mówią "nie w ten sposób", a nie "nie teraz". Odpowiadaj szybko 2xx i pracuj potem; dostawa wygasa po 10 sekundach.

Dostępne zdarzenia

7. Błędy i kody statusu

8. Uwagi dotyczące bezpieczeństwa

• Klucze tylko do odczytu (mp_ro_) niczego nie zmieniają. Klucze z prawem zapisu (mp_rw_) mogą jedynie przypisywać identyfikatory klientów; żaden klucz nie może usuwać danych ani eksportować surowych danych nagrań.
• Każde zapytanie jest automatycznie ograniczone do własnego Workspace klucza — nie ma możliwości podania innego Workspace ID i zobaczenia cudzych danych.
• Możesz w każdej chwili unieważnić klucz w /api-keys; unieważnienie działa natychmiast.
• Traktuj swój klucz API jak hasło. Jeśli przypadkowo umieścisz go w publicznym repozytorium, natychmiast go unieważnij i utwórz nowy.