Openbare API & API-sleutels

1. Oorsig

Die MousePlayer API laat u data uit u werkruimte na eie kontroleskerms, 'n datapakhuis of interne hulpmiddels haal. Buiten die hegting van klant-ID's aan sessies (identify, vereis 'n sleutel met skryfomvang; sien Sleutelomvang) is dit slegs vir lees: geen data kan deur die API verander of uitgevee word nie.

• Basis-URL: https://www.mouseplayer.com/api/v1/
• Alle antwoorde is JSON.
• Elke versoek word met 'n API-sleutel gestaaf en outomaties tot die sleutel se werkruimte beperk — 'n sleutel van een werkruimte kan nooit 'n ander se data sien nie, nie eens per ongeluk nie.
• Die volledige sessieherspeelopname (muisbewegings, DOM-kiekies) word nie deur die API blootgestel nie. U kry sessiemetadata, bladsybesigtigings, pasgemaakte gebeure en segmente — genoeg vir verslae en kontroleskerms sonder om rou herspeeldata rond te stuur.

2. Stawing

Skep en bestuur u API-sleutels onder API-sleutels in u rekeningkieslys (/api-keys). Net werkruimte-eienaars en administrateurs kan sleutels skep of herroep.

Stuur die sleutel as 'n Bearer-token in elke versoek se Authorization kopskrif:

Ontbrekende, verkeerd gevormde of herroepe sleutels ontvang 'n 401 antwoord:

Planvereiste

Die REST API is deel van die Business en Enterprise planne. Die plan kom van die werkruimte se eienaar en word dus deur genooide spanlede geërf. Die kontrole loop op elke versoek, nie net by sleutelskepping nie — as 'n werkruimte afgegradeer word, hou bestaande sleutels op werk en gee 403terug.

Sleutelomvang

Elke sleutel dra sy omvang in sy voorvoegsel, sodat u deur net daarna te kyk kan sien wat dit doen — in 'n .env, kaartjie of terminaal.

3. Frekwensielimiete

Elke API-sleutel is beperk tot 60 versoeke per minuut, in 'n bewegende tydvenster getel. Ná oorskryding ontvang versoeke 'n 429 antwoord totdat die venster skoon is:

4. Eindpunte

GET/api/v1/projects

Lys elke projek (nagespoorde webwerf) in u werkruimte.

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

Lys besoekersessies vir 'n projek, nuutste eerste. In bladsye verdeel.

GET/api/v1/sessions/{session_id}

Metadata vir een sessie plus sy bladsybesigtigings. Die volle herspeeldata word doelbewus uitgesluit — gebruik daarvoor die kontroleskerm se speler.

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

Pasgemaakte gebeure tydens 'n sessie (dieselfde wat u stuur met mp('event', ...)), met hul parameters.

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

Lys besoekersegmente vir 'n projek (sowel projekspesifieke as werkruimtewye segmente).

5. Heg 'n klant-ID vanuit u agterkant

Die blaaier weet dikwels nie wie daar sit nie. In 'n B2B-produk word die identiteit ná aanmelding bepaal — in u agterkant. In 'n winkel gebeur dit by bestellingsbevestiging. Hierdie eindpunt is juis vir dié oomblik.

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

Die ID verskyn dan in die sessielys, is daar soekbaar en die session_identified webhaak aktiveer — só bereik dit u CRM.

6. Webhake: verifieer die handtekening

Webhake word per projek opgestel onder Integrasies, waar u ook die ondertekeningsgeheim vind. Elke aflewering bevat dié kopskrifte:

Die handtekening is 'n HMAC-SHA256 oor timestamp + "." + raw body, met u projek se ondertekeningsgeheim as sleutel.

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

Aflewering en herprobeerslae

'n Mislukte aflewering word weer probeer ná 1 min, 5 min, 15 min, 1 h en 6 hen dan opgegee. 4xx antwoorde buiten 408 en 429 word nie weer probeer nie — hulle sê "nie só nie", nie "nie nou nie". Antwoord 2xx vinnig en doen die werk daarna; aflewering se tydlimiet is 10 sekondes.

Beskikbare gebeure

7. Foute & statuskodes

8. Sekuriteitsnotas

• Leessleutels (mp_ro_) kan niks verander nie. Skryfsleutels (mp_rw_) kan net klant-ID's heg; geen sleutel kan data uitvee of rou herspeeldata uitvoer nie.
• Elke versoek word outomaties tot die sleutel se eie werkruimte beperk — u kan nie 'n ander werkruimte-ID deurgee en iemand anders se data sien nie.
• Herroep enige tyd 'n sleutel by /api-keys; herroeping geld onmiddellik.
• Behandel u API-sleutel soos 'n wagwoord. As u dit per ongeluk in 'n openbare kodebewaarplek vaslê, herroep dit onmiddellik en skep 'n nuwe een.