API ya Umma & Funguo za API
Ufikiaji wa nafasi yako ya kazi kupitia programu — soma miradi, vipindi, matukio maalumu na makundi, na uambatishe ID za wateja katika vipindi — umelindwa kwa funguo za API zenye wigo wa nafasi ya kazi.
1. Muhtasari
MousePlayer API hukuruhusu kutoa data kutoka nafasi yako ya kazi kwenda dashibodi zako mwenyewe, ghala la data au zana za ndani. Mbali na kuambatisha ID za wateja katika vipindi (identify, inahitaji ufunguo wenye wigo wa kuandika, ona Wigo wa funguo), ni ya kusoma tu: hakuna data inayoweza kubadilishwa au kufutwa kupitia API.
- URL ya msingi:
https://www.mouseplayer.com/api/v1/ - Majibu yote ni JSON.
- Kila ombi huthibitishwa kwa ufunguo wa API na huwekewa wigo kiotomatiki wa nafasi ya kazi ambayo ufunguo ni wake — ufunguo wa nafasi moja ya kazi hauwezi kuona data za nyingine kamwe, hata kwa bahati mbaya.
- Rekodi kamili ya uchezaji tena wa kipindi (miendo ya kipanya, picha za DOM) haipatikani kupitia API. Unapata metadata ya kipindi, utazamaji wa kurasa, matukio maalumu na makundi — vya kutosha kuunda ripoti na dashibodi bila kusafirisha mzigo ghafi wa data za uchezaji tena.
2. Uthibitishaji
Unda na usimamie funguo zako za API chini ya Funguo za API katika menyu ya akaunti yako (/api-keys). Wamiliki na wasimamizi wa nafasi ya kazi pekee wanaweza kuunda au kubatilisha funguo.
Weka ufunguo wako kuwa siri. Hutoa ufikiaji wa kusoma kila kitu katika nafasi yako ya kazi. Ufunguo kamili huonyeshwa mara moja tu, mara tu unapouunda — uhifadhi katika kidhibiti cha manenosiri au hifadhi ya siri. Ukiupoteza, ubatilishe na uunde mpya.
Tuma ufunguo kama tokeni ya Bearer katika kichwa cha Authorization cha kila ombi:
Funguo zinazokosekana, zenye umbo lisilo sahihi au zilizobatilishwa hupokea jibu la 401 kama ifuatavyo:
Mpango unaohitajika
REST API ni sehemu ya mipango ya Business na Enterprise pekee. Mpango huchukuliwa kutoka kwa mmiliki wa nafasi ya kazi, hivyo washiriki wa timu walioalikwa huurithi. Ukaguzi huendeshwa kwa kila ombi, si wakati wa kuunda ufunguo tu — nafasi ya kazi ikishushwa, funguo zilizopo huacha kufanya kazi na kurudisha 403 kama jibu.
Wigo wa funguo
Kila ufunguo hubeba wigo wake katika kiambishi chake cha mwanzo, ili uweze kujua unachofanya kwa kuutazama tu — katika .env, katika tiketi, katika terminal.
| Kiambishi cha mwanzo | Maana |
|---|---|
mp_ro_ | Kusoma tu. Husoma miradi, vipindi, matukio na makundi. Hauwezi kubadilisha chochote. |
mp_rw_ | Kusoma na kuandika. Yote yaliyo hapo juu, pamoja na kuambatisha ID za wateja kupitia endpoint ya identify. |
403 yenye ujumbe unaotaja aina ya ufunguo na mahitaji ya endpoint. Wigo hauwezi kubadilishwa baadaye — unda ufunguo mpya na ubatilishe wa zamani.3. Vikomo vya kiwango
Kila ufunguo wa API una kikomo cha maombi 60 kwa dakika, kinachofuatiliwa katika dirisha linalosogea. Ukizidi hilo, maombi hupokea jibu la 429 hadi dirisha liishe:
Unajenga kitu kinachohitaji kikomo cha juu zaidi? Wasiliana kupitia Usaidizi na utuambie matumizi yako.
4. Endpoint
GET/api/v1/projects
Huorodhesha kila mradi (tovuti inayofuatiliwa) katika nafasi yako ya kazi.
GET/api/v1/projects/{channelid}/sessions
Huorodhesha vipindi vya watembeleaji vilivyorekodiwa kwa mradi, vipya zaidi kwanza. Vimegawanywa katika kurasa.
| Kigezo cha hoja | Maelezo |
|---|---|
page | Nambari ya ukurasa, chaguo-msingi 1 kama thamani. |
per_page | Matokeo kwa ukurasa, chaguo-msingi 25, kiwango cha juu 100 kama kikomo. |
since | Vipindi vinavyoanza katika tarehe hii au baada yake tu (YYYY-MM-DD). |
until | Vipindi vinavyoanza katika tarehe hii au kabla yake tu. |
GET/api/v1/sessions/{session_id}
Metadata ya kipindi kimoja, pamoja na utazamaji wake wa kurasa. Kwa makusudi haijumuishi mzigo kamili wa data za uchezaji tena — tumia Kichezaji cha dashibodi kwa hilo.
GET/api/v1/sessions/{session_id}/events
Matukio maalumu yaliyochochewa katika kipindi (matukio yaleyale unayotuma kwa mp('event', ...)), pamoja na vigezo vyake.
GET/api/v1/projects/{channelid}/segments
Huorodhesha makundi ya watembeleaji yaliyobainishwa kwa mradi (yote mawili, ya mradi pekee na ya nafasi nzima ya kazi).
5. Kuambatisha ID ya mteja kutoka upande wako wa seva
Mara nyingi kivinjari hakijui nani amekaa hapo. Katika bidhaa ya B2B utambulisho hujulikana baada ya kuingia — katika upande wako wa seva. Katika duka hujulikana kwa uthibitisho wa agizo. Endpoint hii ni kwa wakati huo hasa.
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}}Kisha ID huonekana katika orodha ya vipindi, inaweza kutafutwa hapo, na webhook ya session_identified huchochewa — hivyo ndivyo inavyofikia CRM yako.
"changed": false na hakuna webhook inayotumwa. Agizo linalorudiwa haliundi mteja tarajiwa wa pili.| Hali | Wakati |
|---|---|
400 | Sehemu inayokosekana, user_id yenye zaidi ya herufi 128 au herufi za kudhibiti ndani yake. Tunakataa badala ya kukata — ID iliyofupishwa kimyakimya hailingani na chochote katika CRM yako na bado huonekana kama mafanikio. |
404 | Kipindi hakipo au si cha nafasi yako ya kazi. Kwa makusudi jibu ni lilelile kwa yote mawili. |
403 | Mpango wa nafasi ya kazi haujumuishi API. |
6. Webhooks: kuthibitisha saini
Webhook husanidiwa kwa kila mradi chini ya Miunganisho, ambako pia unapata siri ya kutia saini. Kila uwasilishaji hubeba vichwa hivi:
| Kichwa | Maana |
|---|---|
X-MousePlayer-Event | Jina la tukio, k.m. session_identified |
X-MousePlayer-Timestamp | Sekunde za Unix — sehemu ya maandishi yaliyotiwa saini |
X-MousePlayer-Attempt | 1 katika jaribio la kwanza, ya juu zaidi majaribio yanaporudiwa |
X-MousePlayer-Signature | sha256=<hex> |
Saini ni HMAC-SHA256 juu ya timestamp + "." + raw body, kwa kutumia siri ya kutia saini ya mradi wako kama ufunguo.
// 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');
Uwasilishaji na kujaribu tena
Uwasilishaji ulioshindwa hujaribiwa tena baada ya dakika 1, dakika 5, dakika 15, saa 1 na saa 6, kisha huachwa. 4xx Majibu yasiyo 408 na 429 huwa hayajaribiwi tena — husema "si hivi", si "si sasa hivi". Jibu 2xx haraka na ufanye kazi baadaye; muda wa uwasilishaji huisha baada ya sekunde 10.
Matukio yanayopatikana
| Tukio | Huchochewa |
|---|---|
session_identified | Kipindi kinapopata ID ya mteja kwa mara ya kwanza — kutoka kivinjari au API |
session_ended | Mara moja, kipindi kinapofungwa |
goal_reached | Mara moja kwa kipindi, tukio maalumu linapotimiza mojawapo ya malengo yako. Malengo ya aina ya “event” tu — malengo ya URL, muda, utazamaji wa ukurasa na faneli hayakaguliwi. Hubeba goal_id, goal_name, goal_value na currency kama sehemu. |
high_value_session | Mtembeleaji anapovuka kwa mara ya kwanza kizingiti cha thamani cha mradi huu katika siku fulani. Kizingiti hutokana na mgawanyo wako mwenyewe wa alama (persentili ya 90 ya siku 90 zilizopita), si nambari ya kudumu, na hakipatikani hadi angalau watembeleaji 20 wawe wamepewa alama. Hubeba visitor_id, value_score, threshold na kipindi kinachofaa zaidi kutazamwa cha siku hiyo. |
funnel_dropoff | Mwishoni mwa kipindi kilichoingia katika mojawapo ya faneli zako bila kuimaliza. Hutaja hatua kiliposimama (dropped_at). Kuondoka ni kutokuwepo kwa tukio, hivyo kunaweza kujulikana tu kipindi kikiisha. Vipindi ambavyo havikuingia katika faneli si kuondoka na havichochei. |
high_friction_session | Mara moja kwa kipindi, alama yake ya msuguano inapofikia kizingiti kwa mara ya kwanza (chaguo-msingi 60 kati ya 100). Hubeba friction_score, ishara zilizo nyuma yake (reasons) na ishara iliyovuka mstari (trigger). |
element_broken | Mara moja, kipengele kinachofuatiliwa kisipopata chochote katika utazamaji wowote wa ukurasa uliokaguliwa kwa siku kadhaa — kwa kawaida baada ya uzinduzi mpya. Huchochewa tena tu baada ya alama kulingana na kuharibika mara nyingine. Tukio hili si la kipindi chochote: session_id na session_url ni null, link_url hufungua alama badala yake, na subject_id hutaja alama — ileile kwa kila toleo, ili kiteuzi kipya kinachoharibika tena kijiunge na tukio lililo wazi. Hubeba rule_id, rule_name, selector, page, checked_page_views, window_days na last_matched kama sehemu. Hakuna data za watembeleaji. |
element_recovered | Taarifa ya kuwa hali ni salama kwa element_broken: mara alama inapopata kipengele tena kweli — utazamaji mchache mno wa kurasa hautoshi. Hutumwa tu ikiwa element_broken ilitoka kwa webhook, na haina swichi yake yenyewe: kujisajili kwa element_broken huijumuisha. Ni ileile subject_id, hivyo PagerDuty hutatua tukio na Opsgenie hufunga tahadhari. Hubeba matched_page_views na checked_page_views kwa nyongeza. |
anomaly_detected | Mara moja kwa siku, jana ilipotofautiana wazi na siku 28 zilizotangulia: vipindi vichache au vingi zaidi, kiwango cha malengo kilichoshuka, vipindi zaidi vyenye msuguano au hitilafu za JS. Kipimo na mwelekeo uleule hubaki kimya kwa wiki moja (inaweza kurekebishwa). Tukio hili si la kipindi chochote: session_id na session_url ni null, link_url hufungua muhtasari wa mradi, na subject_id hutaja kipimo, mwelekeo na siku. Hubeba metric (sessions, goal_rate, friction_rate, js_error_rate, lcp_p75, inp_p75, cls_p75), direction, day, value, expected, sessions, robust_z, z_score na sehemu inayosomeka ya summary na hint kama sehemu. Hakuna data za watembeleaji. Kwa Web Vitals, measurements huchukua nafasi ya sessions, na page (tupu kwa tovuti nzima) na device (desktop au mobil) husema lilipotokea; link_url kisha hufungua kichupo cha Web Vitals. |
rage_click | Mbofyo wa hasira unapogunduliwa |
error_detected | Hitilafu ya upande wa kivinjari inapotokea |
ce | Usajili wa pamoja kwa matukio yako maalumu mwenyewe. Huu haujumuishi matukio yaliyo hapo juu — hayo yana swichi zake zenyewe. |
7. Hitilafu & misimbo ya hali
| Hali | Maana |
|---|---|
200 | Mafanikio. |
401 | Ufunguo wa API unaokosekana, wenye umbo lisilo sahihi au uliobatilishwa. |
404 | Mradi au kipindi kilichoombwa hakipo, au si cha nafasi yako ya kazi. |
429 | Kikomo cha kiwango kimezidiwa — unatuma zaidi ya maombi 60/dakika kwa ufunguo huu. |
403 | Mpango wa nafasi ya kazi haujumuishi REST API. Ujumbe hutaja mpango unaohitajika na wa sasa. |
8. Maelezo ya usalama
- Funguo za kusoma tu (mp_ro_) haziwezi kubadilisha chochote. Funguo za kuandika (mp_rw_) zinaweza kuambatisha ID za wateja tu; hakuna ufunguo unaoweza kufuta data au kuhamisha data ghafi za uchezaji tena.
- Kila ombi huwekewa wigo kiotomatiki wa nafasi ya kazi ya ufunguo wenyewe — hakuna njia ya kutuma ID tofauti ya nafasi ya kazi na kuona data za mtu mwingine.
- Batilisha ufunguo wakati wowote kutoka /api-keys; kubatilisha huanza kutumika mara moja.
- Tendea ufunguo wako wa API kama nenosiri. Ukiuingiza kwa bahati mbaya katika commit ya hazina ya umma, ubatilishe mara moja na uunde mpya.
Kurasa za matukio zenye vikomo (API v1, 14 Oktoba 2026)
GET /api/v1/sessions/{session_id}/events hurudisha hadi matukio 100 kwa chaguo-msingi. Weka per_page kuwa nambari kamili kutoka 1 hadi 100. Fuata pagination.next_cursor kwa kutuma cursor bila kuibadilisha katika ombi linalofuata; tumia kipindi na nafasi ileile ya kazi. Matukio hupangwa kwa created_at na event_id. Cursor zimetiwa saini na kuhusishwa na kipindi na nafasi hiyo ya kazi. Hakuna jumla ya idadi au ukurasa wa nambari unaorudishwa.
Safu iliyopo ya data na ramani ya params zinaendelea kupatikana. pagination.returned ni idadi halisi iliyorudishwa; pagination.has_more huonyesha ukurasa mwingine. next_cursor ni null ikikamilika. Jibu lina kikomo cha baiti 524288, hivyo ukurasa unaweza kuwa na matukio machache kuliko per_page. Kwa kila tukio, mistari isiyozidi 128 ya vigezo hurudishwa; params_truncated ni true ikiwa kuna zaidi. Vigezo binafsi vya maandishi huhifadhi kikomo cha hifadhidata cha herufi 255. Vigezo vilivyokatwa havipatikani kupitia endpoint hii. Kupunguza per_page hakuongezi kikomo cha vigezo.
Ukubwa wa ukurasa usio halali, cursor zilizobadilishwa na cursor za kipindi/nafasi nyingine ya kazi hurudisha 400. Data kubwa mno za tukio moja hurudisha 413. Ukaguzi uliopo wa ufikiaji bado hurudisha 401, 403, 404 au 409 kulingana na hali.
Kikomo kinabaki maombi 60 yaliyothibitishwa kwa kila ufunguo wa API kwa dakika. Kuisha kwa mgao hurudisha 429 yenye Retry-After: 60. Ikiwa Redis au kidhibiti cha kiwango hakipatikani, maombi hurudisha 503 yenye Retry-After: 5; hayakubaliwi kamwe bila kikomo. Heshimu Retry-After na uongeze muda wa kusubiri wa nasibu; usijaribu tena katika mzunguko wa haraka. Kushindwa kwa hifadhidata ya matukio pia hurudisha 503. Cursor hazifungi picha ya hali: uingizaji wa wakati mmoja wenye mihuri ya muda ya zamani unaweza kuhitaji ukaguzi mpya.
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 ni njia ya udhibiti wa upande wa seva ya Dev pekee kwa hakiki ya native SDK. Hubaki imezimwa katika uzalishaji. Funguo za Bearer za upande wa seva zinahitaji wigo wa kusoma kwa list/replay na wa kuandika kwa register/grant/delete/disable. Ukaguzi wa ziada wa upatikanaji wa native-preview hutumika. Usipachike kamwe funguo za kudumu za API za nafasi ya kazi katika programu ya simu.