API gbangba & API Key
Ààyè fún ètò sí àgbègbè iṣẹ́ yín — ka iṣẹ́ akanṣe, ìgbà ìlò, ìṣẹ̀lẹ̀ tiyín àti ẹ̀ka, kí ẹ sì so ID oníbàárà mọ́ ìgbà ìlò — pẹ̀lú ààbò API key tó ní ààlà àgbègbè iṣẹ́.
1. Àkótán
API MousePlayer ń jẹ́ kí ẹ fa dátà láti àgbègbè iṣẹ́ yín sínú dashboard tiyín, data warehouse tàbí irinṣẹ́ inú. Àyàfi sísopọ̀ ID oníbàárà mọ́ ìgbà ìlò (identify, ó nílò key pẹ̀lú write scope, ẹ wo Àgbègbè ipa key), ó jẹ́ fún kíka nìkan: a kò lè yí tàbí pa dátà rẹ́ nípasẹ̀ API.
- URL ìpìlẹ̀:
https://www.mouseplayer.com/api/v1/ - Gbogbo ìdáhùn jẹ́ JSON.
- Gbogbo ìbéèrè ní ìjẹ́rìí API key, a sì ń fi ààlà sí àgbègbè iṣẹ́ tí key jẹ́ tirẹ̀ fúnra rẹ̀ — key láti àgbègbè iṣẹ́ kan kò lè rí dátà àgbègbè iṣẹ́ mìíràn láéláé, kódà ní àṣìṣe.
- Gbogbo ìgbàsílẹ̀ ìtúnṣeré ìgbà ìlò (ìṣípò eku, àwòrán DOM) kò hàn nípasẹ̀ API. Ẹ gba metadata ìgbà ìlò, ìwò ojú ìwé, ìṣẹ̀lẹ̀ tiyín àti ẹ̀ka — tó láti kọ ìròyìn àti dashboard láìgbé payload ìtúnṣeré àìṣe àgbékalẹ̀ káàkiri.
2. Ìjẹ́rìí
Ẹ ṣẹ̀dá kí ẹ sì ṣàkóso API key yín lábẹ́ API Keys nínú àkójọ àkáǹtì yín (/api-keys). Olówó àti alábòójútó àgbègbè iṣẹ́ nìkan ló lè ṣẹ̀dá tàbí fagilé key.
Ẹ pa key yín mọ́ ní àṣírí. Ó ń fún ní àṣẹ kíka gbogbo ohun nínú àgbègbè iṣẹ́ yín. A fi gbogbo key hàn lẹ́ẹ̀kan gẹ́lẹ́, lẹ́sẹ̀kẹsẹ̀ lẹ́yìn tí ẹ ṣẹ̀dá rẹ̀ — ẹ pa á mọ́ nínú olùṣàkóso ọ̀rọ̀ aṣínà tàbí ibi ààbò àṣírí. Bí ẹ bá pàdánù rẹ̀, ẹ fagilé e, kí ẹ sì ṣẹ̀dá tuntun.
Ẹ fi key ránṣẹ́ gẹ́gẹ́ bí Bearer token nínú header Authorization gbogbo ìbéèrè:
Key tí kò sí, tí ìrísí rẹ̀ kò tọ́ tàbí tí a fagilé ń gba ìdáhùn 401 :
Ètò iṣẹ́ tí a nílò
REST API jẹ́ apá ètò iṣẹ́ Business àti Enterprise . A gba ètò iṣẹ́ láti ọ̀dọ̀ olówó àgbègbè iṣẹ́, nítorí náà ọmọ ẹgbẹ́ tí a pè ń jogún rẹ̀. Àyẹ̀wò ń ṣiṣẹ́ lórí gbogbo ìbéèrè, kì í ṣe nígbà tí a ṣẹ̀dá key nìkan — bí a bá dín ipele àgbègbè iṣẹ́ kù, key tó wà tẹ́lẹ̀ dá iṣẹ́ dúró, wọ́n sì ń dá 403 padà.
Àgbègbè ipa key
Gbogbo key ní àgbègbè ipa rẹ̀ nínú ìṣáájú tirẹ̀, kí ẹ lè mọ ohun tí key ń ṣe ní wíwò ó nìkan — nínú .env, nínú ticket, nínú terminal.
| Ìṣáájú | Ìtumọ̀ |
|---|---|
mp_ro_ | Kíka nìkan. Ó ń ka iṣẹ́ akanṣe, ìgbà ìlò, ìṣẹ̀lẹ̀ àti ẹ̀ka. Kò lè yí ohunkóhun padà. |
mp_rw_ | Kíka àti kíkọ. Gbogbo ohun lókè, pẹ̀lú sísopọ̀ ID oníbàárà nípasẹ̀ identify endpoint. |
403 padà pẹ̀lú ìfiránṣẹ́ tó dárúkọ ohun tí key jẹ́ àti ohun tí endpoint nílò. A kò lè yí àgbègbè ipa padà lẹ́yìn náà — ẹ ṣẹ̀dá key tuntun kí ẹ sì fagilé àtijọ́.3. Ààlà ìwọ̀n ìbéèrè
API key kọ̀ọ̀kan ní ààlà ìbéèrè 60 fún ìṣẹ́jú kan, a ń tọ́pa ní àkókò tó ń rìn. Ní kété tí ẹ bá kọjá èyí, ìbéèrè ń gba ìdáhùn 429 títí àkókò náà yóò fi tú:
Ṣé ẹ ń kọ ohun tó nílò ààlà gíga sí i? Ẹ kàn sí wa nípasẹ̀ Ìrànlọ́wọ́ kí ẹ sì sọ ọ̀nà ìlò yín fún wa.
4. Endpoint
GET/api/v1/projects
Ó ń tò gbogbo iṣẹ́ akanṣe (ojúlé tí a tọ́pa) nínú àgbègbè iṣẹ́ yín.
GET/api/v1/projects/{channelid}/sessions
Ó ń tò ìgbà ìlò àlejò tí a gbàsílẹ̀ fún iṣẹ́ akanṣe kan, tuntun jù kọ́kọ́. A pín sí ojú ìwé.
| Query param | Àpèjúwe |
|---|---|
page | Nọ́ńbà ojú ìwé, àkọ́kọ́ 1. |
per_page | Àbájáde fún ojú ìwé kan, àkọ́kọ́ 25, tó pọ̀ jù 100. |
since | Ìgbà ìlò tó bẹ̀rẹ̀ ní/lẹ́yìn ọjọ́ yìí nìkan (YYYY-MM-DD). |
until | Ìgbà ìlò tó bẹ̀rẹ̀ ní/ṣáájú ọjọ́ yìí nìkan. |
GET/api/v1/sessions/{session_id}
Metadata fún ìgbà ìlò kan ṣoṣo, pẹ̀lú ìwò ojú ìwé rẹ̀. A mọ̀ọ́mọ̀ yọ gbogbo payload ìtúnṣeré kúrò — ẹ lo Ẹ̀rọ ìtúnṣeré dashboard fún ìyẹn.
GET/api/v1/sessions/{session_id}/events
Ìṣẹ̀lẹ̀ tiyín tó ṣiṣẹ́ ní ìgbà ìlò kan (ìṣẹ̀lẹ̀ kan náà tí ẹ fi ránṣẹ́ pẹ̀lú mp('event', ...)), pẹ̀lú parameter wọn.
GET/api/v1/projects/{channelid}/segments
Ó ń tò ẹ̀ka àlejò tí a ṣàlàyé fún iṣẹ́ akanṣe kan (ẹ̀ka ti iṣẹ́ akanṣe àti ti gbogbo àgbègbè iṣẹ́ méjèèjì).
5. Sísopọ̀ ID oníbàárà láti backend yín
Aṣàwákiri kì í sábà mọ ẹni tó jókòó níbẹ̀. Nínú ọjà B2B, ìdánimọ̀ ń parí lẹ́yìn ìwọlé — nínú backend yín. Nínú ilé ìtajà, ó ń parí pẹ̀lú ìmúdájú àṣẹ ọjà. Endpoint yìí wà fún àkókò gangan yẹn.
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 ń hàn nínú àtòjọ ìgbà ìlò lẹ́yìn náà, ó ṣeé wá níbẹ̀, webhook session_identified sì ń ṣiṣẹ́ — bí ó ṣe ń dé CRM yín nìyẹn.
"changed": false a kò sì fi webhook kankan ránṣẹ́. Àṣẹ ọjà tí a tún ṣe kò ṣẹ̀dá ẹni tó lè rà kejì.| Ipò | Ìgbà |
|---|---|
400 | Pápá kò sí, user_id tó ju lẹ́tà 128 lọ, tàbí ó ní control character. A ń kọ̀ dípò gígé kúrú — ID tí a gé kúrú láìpariwo kò bá ohunkóhun mu nínú CRM yín, ó sì ṣì dà bí àṣeyọrí. |
404 | Ìgbà ìlò kò sí tàbí kì í ṣe ti àgbègbè iṣẹ́ yín. A mọ̀ọ́mọ̀ lo ìdáhùn kan náà fún méjèèjì. |
403 | Ètò iṣẹ́ àgbègbè iṣẹ́ kò ní API. |
6. Webhook: ṣíṣàyẹ̀wò ìbuwọlu
A ń ṣètò webhook fún iṣẹ́ akanṣe kọ̀ọ̀kan lábẹ́ Ìsopọ̀, níbi tí ẹ tún ti rí signing secret. Gbogbo ìfijiṣẹ́ ní header wọ̀nyí:
| Header | Ìtumọ̀ |
|---|---|
X-MousePlayer-Event | Orúkọ ìṣẹ̀lẹ̀, bí session_identified |
X-MousePlayer-Timestamp | Ìṣẹ́jú àáyá Unix — apá ọ̀rọ̀ tí a buwọ́ lu |
X-MousePlayer-Attempt | 1 ní ìgbìyànjú àkọ́kọ́, ó ga sí i ní àtúngbìyànjú |
X-MousePlayer-Signature | sha256=<hex> |
Ìbuwọlu jẹ́ HMAC-SHA256 lórí timestamp + "." + raw body, pẹ̀lú signing secret iṣẹ́ akanṣe yín gẹ́gẹ́ bí 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');
Ìfijiṣẹ́ àti àtúngbìyànjú
A ń tún gbìyànjú ìfijiṣẹ́ tó kùnà lẹ́yìn ìṣẹ́jú 1, ìṣẹ́jú 5, ìṣẹ́jú 15, wákàtí 1 àti wákàtí 6, lẹ́yìn náà a jáwọ́. 4xx Ìdáhùn tó yàtọ̀ sí 408 àti 429 ni a kò tún gbìyànjú — wọ́n ń sọ "kì í ṣe báyìí", kì í ṣe "kì í ṣe ní báyìí". Ẹ dá 2xx padà kíákíá kí ẹ sì ṣe iṣẹ́ lẹ́yìn náà; ìfijiṣẹ́ ń parí àkókò lẹ́yìn ìṣẹ́jú àáyá 10.
Ìṣẹ̀lẹ̀ tó wà
| Ìṣẹ̀lẹ̀ | Ó ń ṣiṣẹ́ |
|---|---|
session_identified | Nígbà tí ìgbà ìlò kọ́kọ́ gba ID oníbàárà — láti aṣàwákiri tàbí láti API |
session_ended | Lẹ́ẹ̀kan, nígbà tí ìgbà ìlò bá pa dé |
goal_reached | Lẹ́ẹ̀kan fún ìgbà ìlò, nígbà tí ìṣẹ̀lẹ̀ tiyín bá mú ọ̀kan nínú àfojúsùn yín ṣẹ. Àfojúsùn irú “event” nìkan — a kò ṣàyẹ̀wò àfojúsùn URL, àkókò, ìwò ojú ìwé àti funnel. Ó ní goal_id, goal_name, goal_value àti currency. |
high_value_session | Nígbà tí àlejò kọ́kọ́ kọjá ààlà iye iṣẹ́ akanṣe yìí ní ọjọ́ kan. Ààlà ni a ṣe àgbéjáde láti ìpínpín àmì tiyín (percentile 90 ọjọ́ 90 tó kọjá), kì í ṣe nọ́ńbà tí kò yípadà, kò sì sí títí a ó fi fún ó kéré tán àlejò 20 ní àmì. Ó ní visitor_id, value_score, threshold àti ìgbà ìlò tó yẹ kí a wò jù ní ọjọ́ náà. |
funnel_dropoff | Ní òpin ìgbà ìlò tó wọ ọ̀kan nínú funnel yín ṣùgbọ́n tí kò parí rẹ̀. Ó dárúkọ ìgbésẹ̀ tí ó dúró sí (dropped_at). Kíkúrò jẹ́ àìsí ìṣẹ̀lẹ̀ kan, nítorí náà a lè mọ̀ ọ́ nígbà tí ìgbà ìlò bá parí nìkan. Ìgbà ìlò tí kò wọ funnel rí kì í ṣe kíkúrò, wọn kò sì mú ṣiṣẹ́. |
high_friction_session | Lẹ́ẹ̀kan fún ìgbà ìlò, nígbà tí àmì ìdènà rẹ̀ kọ́kọ́ dé ààlà (àkọ́kọ́ 60 nínú 100). Ó ní friction_score, àmì tó fà á (reasons) àti àmì tó kọjá ìlà (trigger). |
element_broken | Lẹ́ẹ̀kan, nígbà tí ohun tí a tọ́pa kò rí ohunkóhun nínú ìwò ojú ìwé kankan tí a ṣàyẹ̀wò fún ọjọ́ púpọ̀ — ó sábà jẹ́ lẹ́yìn àtúnfilọ́lẹ̀. Ó tún ń ṣiṣẹ́ lẹ́yìn tí àmì yíyan bá bá mu tí ó sì tún bàjẹ́ nìkan. Ìṣẹ̀lẹ̀ yìí kì í ṣe ti ìgbà ìlò kankan: session_id àti session_url jẹ́ null, link_url ń ṣí àmì yíyan dípò rẹ̀, subject_id sì ń dárúkọ àmì yíyan — kan náà fún gbogbo ẹ̀dà, kí selector tuntun tó tún bàjẹ́ darapọ̀ mọ́ ìṣẹ̀lẹ̀ tó ṣí. Ó ní rule_id, rule_name, selector, page, checked_page_views, window_days àti last_matched. Kò sí dátà àlejò. |
element_recovered | Àmì ìyanjú fún element_broken: lẹ́ẹ̀kan tí àmì yíyan bá rí ohun kan gan-an lẹ́ẹ̀kan sí i — ìwò ojú ìwé tó kéré jù kò tó. A fi ránṣẹ́ bí element_broken bá ti jáde ní webhook nìkan, kò sì ní ṣọ́ọ̀ṣì tirẹ̀: fíforúkọ sí element_broken ní i nínú. Kan náà subject_id, kí PagerDuty yanjú ìṣẹ̀lẹ̀, kí Opsgenie sì pa ìkìlọ̀ dé. Ó ní matched_page_views àti checked_page_views ní àfikún. |
anomaly_detected | Lẹ́ẹ̀kan lójoojúmọ́, nígbà tí àná yàtọ̀ kedere sí ọjọ́ 28 ṣáájú: ìgbà ìlò tó kéré tàbí tó pọ̀ gan-an, ìwọ̀n àfojúsùn tó dín kù, ìgbà ìlò pẹ̀lú ìdènà tàbí àṣìṣe JS sí i. Ìwọ̀n àti ìtọ́sọ́nà kan náà ń dákẹ́ fún ọ̀sẹ̀ kan (ṣeé ṣàtúnṣe). Ìṣẹ̀lẹ̀ yìí kì í ṣe ti ìgbà ìlò kankan: session_id àti session_url jẹ́ null, link_url ń ṣí àkótán iṣẹ́ akanṣe, subject_id sì ń dárúkọ ìwọ̀n, ìtọ́sọ́nà àti ọjọ́. Ó ní metric (sessions, goal_rate, friction_rate, js_error_rate, lcp_p75, inp_p75, cls_p75), direction, day, value, expected, sessions, robust_z, z_score àti summary tó ṣeé kà àti hint. Kò sí dátà àlejò. Fún Web Vitals, measurements ń rọ́pò sessions, àti page (òfo fún gbogbo ojúlé) àti device (desktop tàbí mobil) ń sọ ibi tí ó ti ṣẹlẹ̀; link_url ń ṣí táàbù Web Vitals nígbà náà. |
rage_click | Lórí ìtẹ̀ ìbínú tí a rí |
error_detected | Lórí àṣìṣe front-end |
ce | Ìforúkọsílẹ̀ àpapọ̀ fún ìṣẹ̀lẹ̀ tiyín. Kò ní ìṣẹ̀lẹ̀ lókè nínú — wọ̀nyẹn ní ṣọ́ọ̀ṣì tiwọn. |
7. Àṣìṣe & status code
| Ipò | Ìtumọ̀ |
|---|---|
200 | Àṣeyọrí. |
401 | API key kò sí, ìrísí rẹ̀ kò tọ́ tàbí a fagilé e. |
404 | Iṣẹ́ akanṣe tàbí ìgbà ìlò tí a béèrè kò sí, tàbí kì í ṣe ti àgbègbè iṣẹ́ yín. |
429 | A kọjá ààlà ìwọ̀n ìbéèrè — ẹ ń fi ìbéèrè tó ju 60/ìṣẹ́jú lọ ránṣẹ́ pẹ̀lú key yìí. |
403 | Ètò iṣẹ́ àgbègbè iṣẹ́ kò ní REST API. Ìfiránṣẹ́ dárúkọ ètò iṣẹ́ tí a nílò àti ti lọ́wọ́lọ́wọ́ méjèèjì. |
8. Àkíyèsí ààbò
- Key kíka nìkan (mp_ro_) kò lè yí ohunkóhun padà. Key kíkọ (mp_rw_) lè so ID oníbàárà pọ̀ nìkan; kò sí key tó lè pa dátà rẹ́ tàbí gbé dátà ìtúnṣeré àìṣe àgbékalẹ̀ jáde.
- A fi ààlà gbogbo ìbéèrè sí àgbègbè iṣẹ́ key fúnra rẹ̀ fúnra rẹ̀ — kò sí ọ̀nà láti fi ID àgbègbè iṣẹ́ tó yàtọ̀ ránṣẹ́ kí a sì rí dátà ẹlòmíràn.
- Ẹ fagilé key nígbàkigbà láti /api-keys; ìfagilé ní ipa lẹ́sẹ̀kẹsẹ̀.
- Ẹ bá API key yín lò bí ọ̀rọ̀ aṣínà. Bí ẹ bá commit ọ̀kan sínú repository gbangba ní àṣìṣe, ẹ fagilé e lẹ́sẹ̀kẹsẹ̀, kí ẹ sì ṣẹ̀dá tuntun.
Ojú ìwé ìṣẹ̀lẹ̀ tó ní ààlà (API v1, 14 Ọ̀wàrà 2026)
GET /api/v1/sessions/{session_id}/events ń dá títí dé ìṣẹ̀lẹ̀ 100 padà láti ìbẹ̀rẹ̀. Ẹ ṣètò per_page sí odidi láti 1 sí 100. Ẹ tẹ̀lé pagination.next_cursor nípa fífi cursor ránṣẹ́ láìyípadà nínú ìbéèrè tó kàn; ẹ pa ìgbà ìlò àti àgbègbè iṣẹ́ kan náà mọ́. A tò ìṣẹ̀lẹ̀ nípa created_at àti event_id. A buwọ́ lu cursor, a sì dè wọ́n mọ́ ìgbà ìlò àti àgbègbè iṣẹ́ náà. A kò dá àpapọ̀ iye tàbí nọ́ńbà ojú ìwé padà.
Data array àti params map tó wà tẹ́lẹ̀ ṣì wà. pagination.returned ni iye gangan tí a dá padà; pagination.has_more ń tọ́ka sí ojú ìwé mìíràn. next_cursor jẹ́ null nígbà tí ó bá pé. Ààlà ìdáhùn jẹ́ báìtì 524288, nítorí náà ojú ìwé lè ní ìṣẹ̀lẹ̀ díẹ̀ ju per_page lọ. Fún ìṣẹ̀lẹ̀ kọ̀ọ̀kan, a dá ìlà parameter 128 tó pọ̀ jù padà; params_truncated jẹ́ true bí ó bá sí sí i. Parameter ọ̀rọ̀ kọ̀ọ̀kan pa ààlà ibi ìpamọ́ dátà lẹ́tà 255 mọ́. Parameter tí a gé kúrú kò sí nípasẹ̀ endpoint yìí. Dídín per_page kù kò gbé ààlà parameter ga.
Ìwọ̀n ojú ìwé tí kò tọ́, cursor tí a yí padà àti cursor fún ìgbà ìlò/àgbègbè iṣẹ́ mìíràn ń dá 400 padà. Dátà ìṣẹ̀lẹ̀ kọ̀ọ̀kan tó tóbi jù ń dá 413 padà. Àyẹ̀wò àṣẹ tó wà tẹ́lẹ̀ ṣì ń dá 401, 403, 404 tàbí 409 padà gẹ́gẹ́ bí ó ṣe yẹ.
Ààlà ṣì jẹ́ ìbéèrè 60 tí a jẹ́rìí fún API key kan ní ìṣẹ́jú kan. Ìparí ìpín ń dá 429 padà pẹ̀lú Retry-After: 60. Bí Redis tàbí olùdínà kò bá sí, ìbéèrè ń dá 503 padà pẹ̀lú Retry-After: 5; a kò gbà wọ́n láìsí ààlà láéláé. Ẹ bọ̀wọ̀ fún Retry-After kí ẹ sì fi ìdúró àrìnàkò kún un; ẹ má ṣe tún gbìyànjú nínú loop tó yara. Ìkùnà ibi ìpamọ́ dátà ìṣẹ̀lẹ̀ tún ń dá 503 padà. Cursor kò di àwòrán mú: fífi sínú rẹ̀ lẹ́ẹ̀kan náà pẹ̀lú timestamp àtijọ́ lè nílò scan tuntun.
GET /api/v1/sessions/s_example/events?per_page=25 GET /api/v1/sessions/s_example/events?per_page=25&cursor=SIGNED_CURSOR
/api/v1/native jẹ́ ọ̀nà ìṣàkóso backend Dev nìkan fún àwòrán àkọ́kọ́ SDK native. Ó ṣì kò ṣiṣẹ́ nínú ètò gidi. Backend Bearer key nílò read scope fún list/replay àti write scope fún register/grant/delete/disable. Àyẹ̀wò àfikún wíwà native-preview kan án. Ẹ má fi API key àgbègbè iṣẹ́ tí kò parí sínú ètò alágbèéká láéláé.