Nyilvános API & API-kulcsok
Programozott hozzáférés munkaterületéhez — projektek, munkamenetek, egyedi események és szegmensek olvasása, ügyfélazonosítók munkamenetekhez kapcsolása — munkaterületre korlátozott API-kulcsokkal védve.
1. Áttekintés
A MousePlayer API-val munkaterülete adatait saját irányítópultjaiba, adattárházába vagy belső eszközeibe kérheti le. Az ügyfélazonosítók munkamenetekhez kapcsolását kivéve (identify, írási hatókörű kulcs kell hozzá, lásd A kulcsok hatóköre) az API csak olvasható: nem módosítható és nem törölhető rajta adat.
- Alap-URL:
https://www.mouseplayer.com/api/v1/ - Minden válasz JSON.
- Minden kérés API-kulccsal hitelesített, és automatikusan a kulcs munkaterületére korlátozott — egy munkaterület kulcsa véletlenül sem láthatja másik munkaterület adatait.
- A teljes munkamenet-visszajátszási felvétel (egérmozgások, DOM-pillanatképek) nem érhető el az API-n át. Munkamenet-metaadatokat, oldalmegtekintéseket, egyedi eseményeket és szegmenseket kap — eleget jelentésekhez és irányítópultokhoz a nyers visszajátszási adatcsomag mozgatása nélkül.
2. Hitelesítés
API-kulcsait a fiókmenü API-kulcsok részében hozhatja létre és kezelheti (/api-keys). Csak munkaterületi tulajdonosok és adminisztrátorok hozhatnak létre vagy vonhatnak vissza kulcsot.
Tartsa titokban kulcsát. A munkaterület minden adatához olvasási hozzáférést ad. A teljes kulcs pontosan egyszer, közvetlenül létrehozás után látható — mentse jelszókezelőbe vagy titkosadat-tárolóba. Ha elveszíti, vonja vissza, és hozzon létre újat.
A kulcsot minden kérés Authorization fejlécében Bearer tokenként küldje:
Hiányzó, hibás formátumú vagy visszavont kulcsra 401 válasz érkezik:
Csomagkövetelmény
A REST API a Business és Enterprise csomag része. A munkaterület tulajdonosának csomagját vesszük alapul, így a meghívott csapattagok öröklik. Az ellenőrzés minden kérésnél lefut, nem csupán kulcslétrehozáskor — ha a munkaterület alacsonyabb csomagra vált, a meglévő kulcsok leállnak, válaszuk pedig 403.
A kulcsok hatóköre
Minden kulcs a saját előtagjában hordozza hatókörét, így ránézésre látszik, mire való — egy .env fájlban, jegyen vagy terminálban.
| Előtag | Jelentés |
|---|---|
mp_ro_ | Csak olvasás. Projekteket, munkameneteket, eseményeket és szegmenseket olvas. Semmit nem módosíthat. |
mp_rw_ | Olvasás és írás. A fentiek mellett ügyfélazonosítókat is kapcsolhat az azonosítási végponton át. |
403 válasz érkezik, üzenetében a kulcs képességével és a végpont igényével. A hatókör utólag nem módosítható — hozzon létre új kulcsot, és vonja vissza a régit.3. Kéréskorlátok
API-kulcsonként a korlát percenként 60 kérés, gördülő időablakban számolva. Túllépéskor a kérések 429 választ kapnak az időablak felszabadulásáig:
Magasabb korlátot igénylő megoldást épít? Keressen minket a Támogatás oldalon, és írja le felhasználási esetét.
4. Végpontok
GET/api/v1/projects
A munkaterület minden projektjét (követett webhelyét) listázza.
GET/api/v1/projects/{channelid}/sessions
Egy projekthez rögzített látogatói munkameneteket listázza, a legújabbal kezdve. Lapozható.
| Lekérdezési paraméter | Leírás |
|---|---|
page | Oldalszám, alapértelmezetten 1. |
per_page | Találatok oldalanként, alapértelmezetten 25, legfeljebb 100. |
since | Csak az ezen a napon vagy utána kezdődő munkamenetek (YYYY-MM-DD). |
until | Csak az ezen a napon vagy előtte kezdődő munkamenetek. |
GET/api/v1/sessions/{session_id}
Egyetlen munkamenet metaadatai és oldalmegtekintései. A teljes visszajátszási adatcsomag szándékosan hiányzik — ahhoz használja az irányítópult lejátszóját.
GET/api/v1/sessions/{session_id}/events
A munkamenet során kiváltott egyedi események (amelyeket ezzel küld: mp('event', ...)), paramétereikkel együtt.
GET/api/v1/projects/{channelid}/segments
A projekthez megadott látogatói szegmenseket listázza (a projektspecifikus és a teljes munkaterületi szegmenseket is).
5. Ügyfélazonosító kapcsolása a backendből
A böngésző gyakran nem tudja, ki ül előtte. B2B-termékben az azonosítás bejelentkezés után dől el — az Ön backendjében. Webáruházban a rendelés visszaigazolásakor. Ez a végpont pontosan erre a pillanatra való.
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}}Az azonosító ezután megjelenik a munkamenetlistában, ott kereshető, és a session_identified webhook aktiválódik — így jut el a CRM-be.
"changed": false szerepel, és nem küldünk webhookot. Az ismételt rendelés nem hoz létre második érdeklődőt.| Állapot | Mikor |
|---|---|
400 | Hiányzó mező, user_id 128 karakternél hosszabb, vagy vezérlőkaraktert tartalmaz. Csonkolás helyett elutasítjuk — az észrevétlenül rövidített azonosító semmivel nem egyezik a CRM-ben, mégis sikernek látszik. |
404 | A munkamenet nem létezik vagy nem tartozik munkaterületéhez. Szándékosan ugyanaz a válasz mindkét esetben. |
403 | A munkaterület csomagja nem tartalmazza az API-t. |
6. Webhookok: az aláírás ellenőrzése
A webhookokat projektenként az Integrációk alatt állíthatja be; itt találja az aláírási titkot is. Minden kézbesítés az alábbi fejléceket tartalmazza:
| Fejléc | Jelentés |
|---|---|
X-MousePlayer-Event | Eseménynév, például session_identified |
X-MousePlayer-Timestamp | Unix-másodpercek — az aláírt szöveg része |
X-MousePlayer-Attempt | Az első kísérletnél 1, újrapróbáláskor nagyobb |
X-MousePlayer-Signature | sha256=<hex> |
Az aláírás HMAC-SHA256 ezen a szövegen: timestamp + "." + raw body, projektje aláírási titkát használva kulcsként.
// 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');
Kézbesítés és újrapróbálások
Sikertelen kézbesítés után az újrapróbálások időközei: 1 perc, 5 perc, 15 perc, 1 óra és 6 óra, utána feladjuk. 4xx válaszoknál, a 408 és 429 kivételével nem próbálkozunk újra — jelentésük "nem így", nem "nem most". Gyorsan válaszoljon 2xx állapottal, a munkát utána végezze; a kézbesítés 10 másodperc után időtúllépéssel leáll.
Elérhető események
| Esemény | Aktiválás |
|---|---|
session_identified | Amikor a munkamenet először kap ügyfélazonosítót — a böngészőből vagy az API-ból |
session_ended | Egyszer, a munkamenet lezárásakor |
goal_reached | Munkamenetenként egyszer, ha egy egyedi esemény teljesíti valamelyik célját. Csak „event” típusú célok — az URL-, időtartam-, oldalmegtekintés- és tölcsércélokat nem értékeli. Tartalmazza: goal_id, goal_name, goal_value és currency. |
high_value_session | Amikor a látogató egy adott napon először átlépi a projekt értékküszöbét. A küszöböt saját pontszámeloszlásából számítjuk (az utolsó 90 nap 90. percentilise), nem rögzített szám, és legalább 20 értékelt látogatóig nem létezik. Tartalmazza: visitor_id, value_score, threshold és a nap leginkább megtekintésre érdemes munkamenetét. |
funnel_dropoff | Az egyik tölcsérébe belépő, de azt be nem fejező munkamenet végén. Megnevezi a megszakítás lépését (dropped_at). A lemorzsolódás egy esemény hiánya, ezért csak a munkamenet lezárása után állapítható meg. A tölcsérbe be sem lépő munkamenet nem lemorzsolódás, és nem váltja ki. |
high_friction_session | Munkamenetenként egyszer, amikor súrlódási pontszáma először eléri a küszöböt (alapértelmezetten 60 a 100-ból). Tartalmazza: friction_score, a mögöttes jelzéseket (reasons) és a küszöböt átlépő jelzést (trigger). |
element_broken | Egyszer, ha egy követett elem több napon át egyetlen ellenőrzött oldalmegtekintésen sem talált semmit — jellemzően újraindítás után. Csak akkor aktiválódik újra, ha a megjelölés ismét talált, majd újra elromlott. Ez az esemény egyetlen munkamenethez sem tartozik: session_id és session_url értéke null, a link_url helyette a megjelölést nyitja meg, a subject_id pedig a megjelölést nevezi meg — minden verziónál ugyanazt, így az újra elromló új szelektor a nyitott incidenshez kapcsolódik. Tartalmazza: rule_id, rule_name, selector, page, checked_page_views, window_days és last_matched. Nincsenek látogatói adatok. |
element_recovered | Az element_broken esemény feloldó jelzése: amint a megjelölés ténylegesen újra elemet talál — a túl kevés oldalmegtekintés nem elég. Csak akkor küldjük, ha az element_broken webhookként kiment; nincs saját kapcsolója: az element_broken feliratkozás ezt is tartalmazza. Ugyanaz a subject_id, így a PagerDuty feloldja az incidenst, az Opsgenie lezárja a riasztást. Ezenfelül tartalmazza: matched_page_views és checked_page_views. |
anomaly_detected | Naponta egyszer, ha a tegnap egyértelműen eltért az előző 28 naptól: sokkal kevesebb vagy több munkamenet, visszaesett célelérési arány, több súrlódást vagy JS-hibát tartalmazó munkamenet. Azonos mutató és irány egy hétig csendben marad (állítható). Ez az esemény egyetlen munkamenethez sem tartozik: session_id és session_url értéke null, a link_url a projektáttekintést nyitja meg, a subject_id pedig megnevezi a mutatót, irányt és napot. Tartalmazza: metric (sessions, goal_rate, friction_rate, js_error_rate, lcp_p75, inp_p75, cls_p75), direction, day, value, expected, sessions, robust_z, z_score és egy olvasható summary és hint értéket. Nincsenek látogatói adatok. Web Vitals esetén a measurements váltja ezt: sessions, a page (a teljes webhelynél üres) és a device (desktop vagy mobil) jelzi, hol történt; a link_url ekkor a Web Vitals lapot nyitja meg. |
rage_click | Észlelt dühös kattintáskor |
error_detected | Frontendkivétel esetén |
ce | Gyűjtőfeliratkozás saját egyedi eseményeire. Ez nem foglalja magában a fenti eseményeket — azoknak saját kapcsolójuk van. |
7. Hibák & állapotkódok
| Állapot | Jelentés |
|---|---|
200 | Siker. |
401 | Hiányzó, hibás formátumú vagy visszavont API-kulcs. |
404 | A kért projekt vagy munkamenet nem létezik, vagy nem tartozik munkaterületéhez. |
429 | Kéréskorlát túllépve — percenként több mint 60 kérést küld ezzel a kulccsal. |
403 | A munkaterület csomagja nem tartalmazza a REST API-t. Az üzenet megnevezi a szükséges és a jelenlegi csomagot is. |
8. Biztonsági megjegyzések
- A csak olvasási kulcsok (mp_ro_) semmit nem módosíthatnak. Az írókulcsok (mp_rw_) csak ügyfélazonosítókat kapcsolhatnak; egyetlen kulcs sem törölhet adatot vagy exportálhat nyers visszajátszási adatokat.
- Minden kérés automatikusan a kulcs saját munkaterületére korlátozott — más munkaterület-azonosító átadásával sem láthatók más adatai.
- Kulcsát bármikor visszavonhatja itt: /api-keys; a visszavonás azonnal életbe lép.
- API-kulcsát jelszóként kezelje. Ha véletlenül nyilvános tárolóba committolja, azonnal vonja vissza, és hozzon létre újat.
Korlátozott méretű eseményoldalak (API v1, 2026. október 14.)
A GET /api/v1/sessions/{session_id}/events alapértelmezetten legfeljebb 100 eseményt ad vissza. A per_page értékét 1 és 100 közötti egész számra állítsa. A pagination.next_cursor követéséhez a következő kérésben változatlanul küldje el a cursor értékét; a munkamenet és a munkaterület maradjon ugyanaz. Az események sorrendje created_at, majd event_id szerinti. A kurzorok aláírtak, az adott munkamenethez és munkaterülethez kötöttek. Teljes elemszámot vagy számozott oldalt nem adunk vissza.
A meglévő data tömb és params leképezés továbbra is elérhető. A pagination.returned a ténylegesen visszaadott darabszám; a pagination.has_more további oldalt jelez. Befejezéskor a next_cursor null. A válasz felső mérethatára 524288 bájt, ezért egy oldal a per_page értékénél kevesebb eseményt is tartalmazhat. Eseményenként legfeljebb 128 paramétersort adunk vissza; több esetén a params_truncated true. Az egyedi szöveges paramétereknél megmarad az adatbázis 255 karakteres korlátja. A levágott paraméterek e végponton nem érhetők el. A per_page csökkentése nem növeli a paraméterkorlátot.
Érvénytelen oldalméret, módosított kurzor vagy más munkamenethez/munkaterülethez tartozó kurzor esetén 400 a válasz. Túlméretes egyedi eseményadatokra 413. A meglévő hozzáférés-ellenőrzések továbbra is a megfelelő 401, 403, 404 vagy 409 választ adják.
A korlát továbbra is API-kulcsonként percenként 60 hitelesített kérés. Kimerítésekor 429 a válasz, Retry-After: 60 fejléccel. Ha a Redis vagy a korlátozó nem elérhető, a kérések 503-at kapnak Retry-After: 5 fejléccel; korlát nélkül soha nem engedjük át őket. Tartsa be a Retry-After értékét, és alkalmazzon véletlen várakozást; ne próbálkozzon szoros ciklusban. Az eseményadatbázis hibái is 503-at adnak. A kurzorok nem rögzítenek pillanatképet: a párhuzamosan beszúrt, régebbi időbélyegű sorok miatt új bejárásra lehet szükség.
GET /api/v1/sessions/s_example/events?per_page=25 GET /api/v1/sessions/s_example/events?per_page=25&cursor=SIGNED_CURSOR
A /api/v1/native kizárólag Dev környezetben elérhető backendvezérlési útvonal a natív SDK előnézetéhez. Éles környezetben kikapcsolva marad. A backend Bearer-kulcsoknak list/replay művelethez olvasási, register/grant/delete/disable művelethez írási hatókör kell. További natívelőnézet-elérhetőségi ellenőrzések is érvényesek. Állandó munkaterületi API-kulcsot soha ne ágyazzon mobilalkalmazásba.