Javni API & API ključi

1. Pregled

API MousePlayer omogoča pridobivanje podatkov iz delovnega prostora v lastne nadzorne plošče, podatkovno skladišče ali interna orodja. Razen pripenjanja ID-jev strank sejam (identify, zahteva ključ z obsegom pisanja, glejte Obsegi ključev) je samo za branje: prek API-ja podatkov ni mogoče spreminjati ali brisati.

• Osnovni URL: https://www.mouseplayer.com/api/v1/
• Vsi odgovori so JSON.
• Vsaka zahteva se overi z API ključem in samodejno omeji na njegov delovni prostor — ključ enega delovnega prostora nikoli ne vidi podatkov drugega, niti po pomoti.
• Celoten posnetek seje (gibanje miške, posnetki stanja DOM) prek API-ja ni dostopen. Dobite metapodatke sej, oglede strani, prilagojene dogodke in segmente — dovolj za poročila in nadzorne plošče brez prenašanja neobdelanih podatkov za predvajanje.

2. Preverjanje pristnosti

API ključe ustvarite in upravljate pod API ključi v meniju računa (/api-keys). Samo lastniki in administratorji delovnega prostora lahko ustvarjajo ali preklicujejo ključe.

Ključ pošljite kot žeton Bearer v glavi Authorization vsake zahteve:

Manjkajoči, napačno oblikovani ali preklicani ključi prejmejo odgovor 401:

Zahtevani paket

REST API je del paketov Business in Enterprise. Paket se določi po lastniku delovnega prostora, zato ga povabljeni člani ekipe podedujejo. Preverjanje se izvede pri vsaki zahtevi, ne le ob ustvarjanju ključa — pri prehodu delovnega prostora na nižji paket obstoječi ključi prenehajo delovati in vrnejo 403.

Obsegi ključev

Vsak ključ ima obseg v lastni predponi, zato že po videzu veste, kaj omogoča — v .env, zahtevku ali terminalu.

3. Omejitve pogostosti

Vsak API ključ je omejen na 60 zahtev na minuto, spremljanih v drsečem časovnem oknu. Ko omejitev presežete, zahteve do sprostitve okna prejmejo odgovor 429:

4. Končne točke

GET/api/v1/projects

Navede vse projekte (sledena spletna mesta) v delovnem prostoru.

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

Navede posnete seje obiskovalcev projekta, najnovejše najprej. S straničenjem.

GET/api/v1/sessions/{session_id}

Metapodatki posamezne seje in njeni ogledi strani. Namenoma brez celotnih podatkov za predvajanje — uporabite predvajalnik nadzorne plošče.

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

Prilagojeni dogodki seje (isti dogodki, ki jih pošiljate z mp('event', ...)), vključno s parametri.

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

Navede segmente obiskovalcev projekta (projektne in za celoten delovni prostor).

5. Pripenjanje ID-ja stranke iz zaledja

Brskalnik pogosto ne ve, kdo je na drugi strani. V izdelku B2B se identiteta določi po prijavi — v vašem zaledju. V trgovini se določi s potrditvijo naročila. Ta končna točka je za natanko ta trenutek.

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 nato prikaže na seznamu sej, kjer ga je mogoče iskati, sproži pa se tudi Webhook session_identified — tako prispe v vaš CRM.

6. Webhooks: preverjanje podpisa

Webhooks nastavite za vsak projekt pod Integracije, kjer najdete tudi skrivnost za podpisovanje. Vsaka dostava vsebuje naslednje glave:

Podpis je HMAC-SHA256 nad timestamp + "." + raw body, s skrivnostjo za podpisovanje vašega projekta.

// 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');

Dostava in ponovni poskusi

Neuspešna dostava se ponovi po 1 min, 5 min, 15 min, 1 h in 6 h, nato se opusti. 4xx odgovori razen 408 in 429 se ne ponavljajo — pomenijo "ne tako", ne "ne zdaj". Hitro odgovorite z 2xx in delo opravite pozneje; časovna omejitev dostave je 10 sekund.

Razpoložljivi dogodki

7. Napake & kode stanja

8. Varnostne opombe

• Ključi samo za branje (mp_ro_) ne morejo ničesar spremeniti. Ključi za pisanje (mp_rw_) lahko samo pripenjajo ID-je strank; noben ključ ne more brisati podatkov ali izvažati neobdelanih posnetkov.
• Vsaka zahteva je samodejno omejena na delovni prostor ključa — ni mogoče posredovati ID-ja drugega delovnega prostora in videti tujih podatkov.
• Ključ kadar koli prekličite pod /api-keys; preklic začne veljati takoj.
• API ključ obravnavajte kot geslo. Če ga pomotoma objavite v javnem repozitoriju, ga takoj prekličite in ustvarite novega.