Ëffentlech API & API-Schlësselen

1. Iwwerbléck

Mat der MousePlayer-API kënnt Dir Donnéeën aus Ärem Aarbechtsberäich an Är eegen Dashboards, Äert Datewarehouse oder intern Instrumenter ofruffen. Ausser dem Zouuerdne vu Clients-IDen u Sessiounen (identify, brauch e Schlëssel mat Schreifscope, kuckt Schlësselscopen) erlaabt si nëmme Liesen: Iwwer d'API kënne keng Donnéeë geännert oder geläscht ginn.

• Basis-URL: https://www.mouseplayer.com/api/v1/
• All Äntwerte si JSON.
• All Ufro gëtt mat engem API-Schlëssel authentifizéiert an automatesch op deen Aarbechtsberäich begrenzt, deem de Schlëssel gehéiert — e Schlëssel aus engem Aarbechtsberäich kann ni d'Donnéeë vun engem anere gesinn, och net zoufälleg.
• Déi komplett Sessiouns-Widdergab-Opnam (Mausbeweegungen, DOM-Ofbiller) ass net iwwer d'API zougänglech. Dir kritt Sessiounsmetadonnéeën, Säitenusiichten, eege Eventer a Segmenter — genuch, fir Berichter an Dashboards ze bauen, ouni déi réi Ofspilldonnéeë ronderëm ze verschécken.

2. Authentifikatioun

Erstellt a verwalt Är API-Schlësselen ënner API-Schlësselen an Ärem Kontmenü (/api-keys). Nëmme Besëtzer an Administrateure vum Aarbechtsberäich kënne Schlësselen erstellen oder zréckzéien.

Schéckt de Schlëssel als Bearer-Token am Header Authorization vun all Ufro:

Feelend, falsch formatéiert oder zréckgezunne Schlëssele kréien eng Äntwert 401 :

Tarifviraussetzung

D'REST-API ass Deel vun de Tariffer Business an Enterprise . Et gëllt den Tarif vum Besëtzer vum Aarbechtsberäich; agelueden Ekippmembere profitéieren also dovun. D'Kontroll geschitt bei all Ufro, net nëmmen, wann e Schlëssel erstallt gëtt — wann den Aarbechtsberäich op e méi klengen Tarif wiesselt, hale bestoend Schlësselen op ze funktionéieren a liwweren 403zeréck.

Schlësselscopen

All Schlëssel dréit säi Scope am eegene Präfix. Dir erkennt also schonn un him, wat e mécht — an engem .env, an engem Ticket, an engem Terminal.

3. Ufrogrenzen

All API-Schlëssel ass op 60 Ufroe pro Minuttbegrenzt, an enger rullender Zäitfënster gezielt. Wann Dir dat iwwerschreit, kréien Ufroen eng Äntwert 429 , bis d'Zäitfënster nees fräi ass:

4. Endpunkten

GET/api/v1/projects

Lëscht all Projet (verfollegt Websäit) an Ärem Aarbechtsberäich op.

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

Lëscht déi fir e Projet opgeholl Visiteursessiounen op, déi neisten als Éischt. Mat Säitenopdeelung.

GET/api/v1/sessions/{session_id}

Metadonnéeë vun enger eenzeler Sessioun plus hir Säitenusiichten. Déi komplett Ofspilldonnéeë si bewosst ausgeschloss — benotzt dofir de Player um Dashboard.

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

Eegendefinéiert Eventer, déi wärend enger Sessioun ausgeléist goufen (déi selwecht Eventer, déi Dir mat mp('event', ...)schéckt), mat hire Parameteren.

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

Lëscht d'Visiteurssegmenter op, déi fir e Projet definéiert sinn (souwuel projetsspezifesch ewéi iwwer den Aarbechtsberäich ewech).

5. Eng Clients-ID aus Ärem Backend zouuerdnen

De Browser weess dacks net, wien do sëtzt. Bei engem B2B-Produit gëtt d'Identitéit nom Umellen gekläert — an Ärem Backend. Bei engem Shop mat der Bestellbestätegung. Dësen Endpunkt ass genee fir dee Moment geduecht.

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

D'ID erschéngt duerno an der Sessiounslëscht, ass do sichbar, an de Webhook session_identified gëtt ausgeléist — esou erreecht se Äert CRM.

6. Webhooks: D'Ënnerschrëft iwwerpréiwen

Webhooks ginn pro Projet ënner Integratiounenageriicht; do fannt Dir och d'Ënnerschrëftsgeheimnis. All Liwwerung enthält dës Headeren:

D'Ënnerschrëft ass en HMAC-SHA256 iwwer timestamp + "." + raw body, mam Ënnerschrëftsgeheimnis vun Ärem Projet als Schlëssel.

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

Liwwerung a Widderhuelungen

Eng feelgeschloe Liwwerung gëtt no 1 Min., 5 Min., 15 Min., 1 St. a 6 St.widderholl; duerno gëtt opgehalen. 4xx Äntwerten ausser 408 an 429 ginn net widderholl — si soen "net esou", net "net elo". Äntwert séier mat 2xx a maacht d'Aarbecht duerno; d'Liwwerung leeft no 10 Sekonnen an eng Zäitlimit.

Verfügbar Eventer

7. Feeler & Statuscoden

8. Sécherheetshinweiser

• Reng Lieschlësselen (mp_ro_) kënnen näischt änneren. Schreifschlësselen (mp_rw_) kënnen nëmme Clients-IDen zouuerdnen; kee Schlëssel kann Donnéeë läschen oder réi Ofspilldonnéeën exportéieren.
• All Ufro ass automatesch op den eegenen Aarbechtsberäich vum Schlëssel begrenzt — et gëtt kee Wee, eng aner Aarbechtsberäichs-ID matzeginn an d'Donnéeë vun aneren ze gesinn.
• Zitt e Schlëssel zu all Moment ënner /api-keyszeréck; d'Zréckzéie wierkt direkt.
• Behandelt Ären API-Schlëssel ewéi e Passwuert. Wann Dir een zoufälleg an en ëffentlecht Repository committ, zitt en direkt zeréck an erstellt en neien.