Pampublikong API & mga API Key

1. Pangkalahatang-ideya

Sa API ng MousePlayer, makukuha ninyo ang datos ng inyong workspace para sa sarili ninyong dashboard, data warehouse o internal na mga tool. Bukod sa paglakip ng customer ID sa session (identify, kailangan ng key na may write scope, tingnan ang Mga saklaw ng key), ito ay read-only: walang datos na mababago o mabubura sa API.

• Base URL: https://www.mouseplayer.com/api/v1/
• JSON ang lahat ng response.
• Bawat request ay pinatutunayan gamit ang API key at awtomatikong saklaw lamang ang workspace ng key — hindi kailanman makikita ng key ng isang workspace ang datos ng iba, kahit aksidente.
• Ang buong recording ng replay ng session (galaw ng mouse, mga snapshot ng DOM) ay hindi inilalabas sa API. Metadata ng session, mga page view, custom event at segment ang makukuha — sapat para sa ulat at dashboard nang hindi inililipat ang raw na payload ng replay.

2. Pagpapatunay

Gumawa at mamahala ng mga API key sa Mga API Key sa menu ng inyong account (/api-keys). Mga may-ari at admin lamang ng workspace ang maaaring gumawa o bumawi ng key.

Ipadala ang key bilang Bearer token sa header na Authorization ng bawat request:

Tumatanggap ng response na 401 ang mga nawawala, maling anyo o binawing key:

Kinakailangang Plan

Bahagi ang REST API ng mga plan na Business at Enterprise. Sinusunod ang plan ng may-ari ng workspace, kaya namamana ito ng inimbitahang miyembro ng team. Sinusuri ito sa bawat request, hindi lamang sa paggawa ng key — kung ibababa ang plan ng workspace, titigil ang mga dating key at magbabalik ng 403.

Mga Saklaw ng Key

Nasa sariling prefix ng bawat key ang saklaw, kaya malalaman ang ginagawa nito sa pagtingin lamang — sa .env, sa ticket, sa terminal.

3. Mga Limitasyon sa Rate

Bawat API key ay limitado sa 60 request bawat minuto, sinusukat sa rolling window. Kapag lumampas, tatanggap ang mga request ng response na 429 hanggang ma-clear ang window:

4. Mga Endpoint

GET/api/v1/projects

Inililista ang bawat project (sinusubaybayang site) sa inyong workspace.

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

Inililista ang mga na-record na session ng bisita para sa project, pinakabago muna. May pagination.

GET/api/v1/sessions/{session_id}

Metadata ng isang session, kasama ang mga page view. Sadyang hindi kasama ang buong payload ng replay — gamitin ang Player ng dashboard para roon.

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

Mga custom event na na-trigger sa session (parehong mga event na ipinapadala gamit ang mp('event', ...)), kasama ang mga parameter.

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

Inililista ang mga segment ng bisita na tinukoy sa project (kapwa para sa project at para sa buong workspace).

5. Paglakip ng Customer ID Mula sa Inyong Backend

Madalas hindi alam ng browser kung sino ang gumagamit. Sa B2B na produkto, nalalaman ang pagkakakilanlan pagkatapos ng login — sa inyong backend. Sa tindahan, sa kumpirmasyon ng order. Para mismo sa sandaling iyon ang endpoint na ito.

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

Lumilitaw pagkatapos ang ID sa listahan ng session, mahahanap doon, at gumagana ang webhook na session_identified — na nagdadala nito sa inyong CRM.

6. Mga Webhook: Pagsuri ng Pirma

Ise-set up ang mga webhook sa bawat project sa Mga Integration, kung saan makikita rin ang signing secret. Bawat paghahatid ay may mga header na ito:

HMAC-SHA256 ang pirma sa timestamp + "." + raw body, gamit ang signing secret ng inyong project bilang key.

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

Paghahatid at Muling Pagsubok

Muling sinusubukan ang bigong paghahatid pagkatapos ng 1 min, 5 min, 15 min, 1 h at 6 h, pagkatapos ay itinitigil. 4xx na response, maliban sa 408 at 429, ay hindi muling sinusubukan — sinasabi nilang "hindi sa ganitong paraan", hindi "hindi ngayon". Tumugon ng 2xx agad at saka gawin ang trabaho; nagta-timeout ang paghahatid pagkalipas ng 10 segundo.

Mga Available na Event

7. Mga Error & Status Code

8. Mga Paalala sa Seguridad

• Walang mababago ang mga read-only key (mp_ro_). Makapaglalakip lamang ng customer ID ang mga write key (mp_rw_); walang key na makabubura ng datos o makapag-e-export ng raw na datos ng replay.
• Awtomatikong saklaw lamang ng bawat request ang sariling workspace ng key — walang paraan upang magpasa ng ibang workspace ID at makita ang datos ng iba.
• Bawiin ang key anumang oras mula sa /api-keys; agad na magkakabisa ang pagbawi.
• Ituring na password ang API key. Kung aksidenteng ma-commit sa pampublikong repository, bawiin agad at gumawa ng bago.