Verejné API & API kľúče

1. Prehľad

API MousePlayer umožňuje získavať údaje z pracovného priestoru do vlastných prehľadov, dátového skladu či interných nástrojov. Okrem pripájania ID zákazníkov k reláciám (identify, vyžaduje kľúč s právom zápisu, pozrite Rozsahy kľúčov) je určené iba na čítanie: cez API nemožno údaje upravovať ani vymazávať.

• Základná URL: https://www.mouseplayer.com/api/v1/
• Všetky odpovede sú vo formáte JSON.
• Každá požiadavka sa overuje API kľúčom a automaticky obmedzuje na pracovný priestor, ku ktorému kľúč patrí — kľúč jedného pracovného priestoru nikdy neuvidí údaje iného, ani náhodou.
• Úplný záznam prehrávania relácie (pohyby myši, snímky DOM) nie je sprístupnený cez API. Dostanete metadáta relácií, zobrazenia stránok, vlastné udalosti a segmenty — dosť na tvorbu správ a prehľadov bez prenášania surových dátových balíkov prehrávania.

2. Overovanie

API kľúče vytvárate a spravujete v časti API kľúče v ponuke účtu (/api-keys). Kľúče môžu vytvárať a odvolávať iba vlastníci a administrátori pracovného priestoru.

Kľúč posielajte ako token Bearer v hlavičke Authorization každej požiadavky:

Chýbajúce, nesprávne formátované alebo odvolané kľúče dostanú odpoveď 401:

Požiadavka na program

REST API je súčasťou programov Business a Enterprise. Program sa preberá od vlastníka pracovného priestoru, takže ho zdedia aj pozvaní členovia tímu. Kontrola prebieha pri každej požiadavke, nielen pri vytvorení kľúča — pri prechode pracovného priestoru na nižší program prestanú existujúce kľúče fungovať a vracajú 403.

Rozsahy kľúčov

Každý kľúč nesie svoj rozsah vo vlastnej predpone, takže jeho účel poznáte pohľadom — v .env, v požiadavke podpory či v termináli.

3. Limity požiadaviek

Každý API kľúč je obmedzený na 60 požiadaviek za minútu, sledovaných v priebežnom časovom okne. Po prekročení dostávajú požiadavky odpoveď 429 až do uvoľnenia okna:

4. Koncové body

GET/api/v1/projects

Vypíše všetky projekty (sledované weby) v pracovnom priestore.

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

Vypíše relácie návštevníkov zaznamenané pre projekt, od najnovších. Stránkované.

GET/api/v1/sessions/{session_id}

Metadáta jednej relácie a jej zobrazenia stránok. Úplný dátový balík prehrávania je zámerne vynechaný — naň použite prehrávač v prehľade.

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

Vlastné udalosti spustené počas relácie (tie isté udalosti, ktoré posielate cez mp('event', ...)) vrátane ich parametrov.

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

Vypíše segmenty návštevníkov definované pre projekt (projektové aj pre celý pracovný priestor).

5. Pripojenie ID zákazníka zo serverového systému

Prehliadač často nevie, kto pri ňom sedí. V produkte B2B sa identita určí po prihlásení — vo vašom serverovom systéme. V obchode pri potvrdení objednávky. Tento koncový bod je určený presne na tento okamih.

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}}

ID sa potom zobrazí v zozname relácií, možno ho tam vyhľadať a spustí sa webhook session_identified — takto sa dostane do vášho CRM.

6. Webhooky: Overenie podpisu

Webhooky sa konfigurujú za projekt v časti Integrácie, kde nájdete aj tajný podpisový kľúč. Každé doručenie obsahuje tieto hlavičky:

Podpis je HMAC-SHA256 nad timestamp + "." + raw bodys tajným podpisovým kľúčom vášho 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');

Doručovanie a opakované pokusy

Neúspešné doručenie sa opakuje po 1 min, 5 min, 15 min, 1 h a 6 h, potom sa ukončí. 4xx odpovede iné než 408 a 429 sa neopakujú — hovoria "nie takto", nie "nie teraz". Odpovedzte 2xx rýchlo a prácu vykonajte neskôr; časový limit doručenia je 10 sekúnd.

Dostupné udalosti

7. Chyby & stavové kódy

8. Bezpečnostné poznámky

• Kľúče iba na čítanie (mp_ro_) nemôžu nič meniť. Kľúče zápisu (mp_rw_) môžu iba pripájať ID zákazníkov; žiadny kľúč nemôže vymazávať údaje ani exportovať surové údaje prehrávania.
• Každá požiadavka sa automaticky obmedzuje na vlastný pracovný priestor kľúča — nemožno odovzdať ID iného pracovného priestoru a vidieť cudzie údaje.
• Kľúč môžete kedykoľvek odvolať na /api-keys; odvolanie sa prejaví okamžite.
• S API kľúčom zaobchádzajte ako s heslom. Ak ho omylom commitnete do verejného repozitára, okamžite ho odvolajte a vytvorte nový.