Veřejné API & klíče API

1. Přehled

API MousePlayer umožňuje načítat data z pracovního prostoru do vlastních dashboardů, datového skladu nebo interních nástrojů. S výjimkou přiřazování ID zákazníků k relacím (identify vyžaduje klíč s rozsahem zápisu, viz Rozsahy klíčů) slouží pouze ke čtení: přes API nelze data měnit ani mazat.

• Základní adresa URL: https://www.mouseplayer.com/api/v1/
• Všechny odpovědi jsou ve formátu JSON.
• Každý požadavek se ověřuje klíčem API a automaticky se omezuje na pracovní prostor, kterému klíč patří — klíč jednoho prostoru nikdy neuvidí data jiného, ani náhodou.
• Úplný záznam relace (pohyby myši, snímky DOM) přes API není dostupný. Získáte metadata relace, zobrazení stránek, vlastní události a segmenty — dost pro vytváření přehledů a dashboardů bez přenosu surových dat záznamu.

2. Ověřování

Klíče API vytvářejte a spravujte v části Klíče API v nabídce účtu (/api-keys). Vytvářet a odvolávat klíče mohou pouze vlastníci a správci pracovního prostoru.

Klíč posílejte jako token Bearer v hlavičce Authorization každého požadavku:

Chybějící, nesprávně vytvořené nebo odvolané klíče dostanou odpověď 401 :

Požadovaný tarif

REST API je součástí tarifů Business a Enterprise . Rozhoduje tarif vlastníka pracovního prostoru, který tak přebírají i pozvaní členové týmu. Kontrola probíhá při každém požadavku, nejen při vytvoření klíče — po přechodu prostoru na nižší tarif přestanou stávající klíče fungovat a vracejí 403.

Rozsahy klíčů

Každý klíč uvádí svůj rozsah ve vlastní předponě, takže jeho možnosti poznáte na pohled — v souboru .env, v požadavku podpory nebo v terminálu.

3. Limity požadavků

Každý klíč API má limit 60 požadavků za minutu, sledovaný v klouzavém časovém okně. Po překročení dostávají požadavky odpověď 429 do uvolnění okna:

4. Endpointy

GET/api/v1/projects

Vypíše všechny projekty (sledované weby) v pracovním prostoru.

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

Vypíše zaznamenané relace návštěvníků projektu, od nejnovější. Se stránkováním.

GET/api/v1/sessions/{session_id}

Metadata jedné relace včetně zobrazení stránek. Úplná data záznamu jsou záměrně vynechána — pro přehrávání použijte přehrávač v dashboardu.

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

Vlastní události spuštěné během relace (stejné, jaké odesíláte pomocí mp('event', ...)), včetně parametrů.

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

Vypíše segmenty návštěvníků definované pro projekt, a to jak specifické pro projekt, tak společné pro pracovní prostor.

5. Přiřazení ID zákazníka z backendu

Prohlížeč často neví, kdo ho používá. V B2B produktu se identita určí po přihlášení — ve vašem backendu. V obchodě při potvrzení objednávky. Tento endpoint je určen právě pro tento okamžik.

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 se pak zobrazí v seznamu relací, lze podle něj hledat a spustí se webhook session_identified — tak se dostane do CRM.

6. Webhooky: ověření podpisu

Webhooky se nastavují pro každý projekt v části Integrace, kde najdete i tajný klíč pro podepisování. Každé doručení obsahuje tyto hlavičky:

Podpis je HMAC-SHA256 z timestamp + "." + raw body, s tajným podpisovým klíčem vašeho 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čení a opakování

Neúspěšné doručení se opakuje po 1 min, 5 min, 15 min, 1 h a 6 h, potom se ukončí. Odpovědi 4xx jiné než 408 a 429 se neopakují — znamenají "ne takto", nikoli "ne právě teď". Odpovězte rychle stavem 2xx a práci proveďte později; doručení vyprší po 10 sekundách.

Dostupné události

7. Chyby & stavové kódy

8. Poznámky k zabezpečení

• Klíče pouze pro čtení (mp_ro_) nemohou nic měnit. Zapisující klíče (mp_rw_) mohou jen přiřazovat ID zákazníků; žádný klíč nemůže mazat data ani exportovat surová data záznamu.
• Každý požadavek je automaticky omezen na vlastní pracovní prostor klíče — nelze předat ID jiného prostoru a prohlížet cizí data.
• Klíč můžete kdykoli odvolat na /api-keys; odvolání platí okamžitě.
• S klíčem API zacházejte jako s heslem. Pokud ho omylem commitnete do veřejného repozitáře, ihned ho odvolejte a vytvořte nový.