API na jama’a & mabuɗan API
Shiga wurin aiki ta shiri — karanta ayyuka, zamuka, abubuwan da suka faru na musamman da rukunai, da haɗa IDs na abokan ciniki da zamuka — an tsare da mabuɗan API masu iyakar wurin aiki.
1. Bayani
API na MousePlayer yana ba da damar ɗauko bayanai daga wurin aiki zuwa dashboards, data warehouse, ko kayan aikin ciki na wurin. Ban da haɗa IDs na abokan ciniki da zamuka (identify, yana buƙatar mabuɗi mai izinin rubutawa, duba Faɗin aikin mabuɗi), yana karantawa kaɗai: ba a iya gyara ko goge bayanai ta API.
- URL na tushe:
https://www.mouseplayer.com/api/v1/ - Duk amsoshi JSON ne.
- Ana tabbatar da kowace buƙata da mabuɗin API kuma ana iyakance ta ta atomatik ga wurin aikin da mabuɗin yake nasa — mabuɗi daga wani wurin aiki ba zai taɓa ganin bayanan wani ba, ko da bisa kuskure.
- Cikakken rikodin sake kunna zama (motsin manuni, hotunan DOM) ba ya samuwa ta API. Ana samun metadata na zama, kallon shafuka, abubuwan da suka faru na musamman da rukunai — isasshe don gina rahotanni da dashboards ba tare da tura ɗanyen bayanan sake kunnawa ko’ina ba.
2. Tabbatar da shiga
A ƙirƙira a sarrafa mabuɗan API ƙarƙashin Mabuɗan API a menu na asusu (/api-keys). Masu wurin aiki da shugabanni kaɗai suke iya ƙirƙira ko soke mabuɗai.
A kiyaye sirrin mabuɗi. Yana ba da damar karanta duk abin da yake cikin wurin aiki. Ana nuna cikakken mabuɗi sau ɗaya daidai, nan da nan bayan ƙirƙirarsa — a adana shi a manajan kalmar sirri ko ma’ajiyar sirri. Idan ya ɓace, a soke shi a ƙirƙiri sabo.
A aika mabuɗi a matsayin Bearer token a header na Authorization na kowace buƙata:
Mabuɗin da ya ɓace, yake da tsarin da bai dace ba ko aka soke yana samun amsar 401 :
Buƙatar shiri
REST API yana cikin shirye-shiryen Business da Enterprise . Ana ɗaukar shiri daga mai wurin aiki, don haka membobin ƙungiya da aka gayyata suna gadonsa. Ana duba shi a kowace buƙata, ba lokacin ƙirƙirar mabuɗi kaɗai ba — idan an rage matakin wurin aiki, mabuɗan da suke nan suna daina aiki suna mayar da 403.
Faɗin aikin mabuɗi
Kowane mabuɗi yana ɗauke da faɗin aikinsa a prefix nasa, don a iya sanin abin da yake yi da kallo kawai — a cikin .env, a tikiti, a terminal.
| Prefix | Ma’ana |
|---|---|
mp_ro_ | Karantawa kaɗai. Yana karanta ayyuka, zamuka, abubuwan da suka faru da rukunai. Ba ya iya sauya komai. |
mp_rw_ | Karantawa da rubutawa. Duk abin da yake sama, da haɗa IDs na abokan ciniki ta wurin ƙarshen identify. |
403 da saƙon da yake bayyana nau’in mabuɗi da abin da wurin ƙarshen yake buƙata. Ba a iya sauya faɗin aiki daga baya — a ƙirƙiri sabon mabuɗi a soke tsohon.3. Iyakokin yawan buƙata
Kowane mabuɗin API yana da iyakar buƙatu 60 a minti guda, ana lura da su a zangon lokaci mai motsi. Da zarar an wuce haka, buƙatu suna samun amsar 429 har zangon ya share:
Ana gina abin da yake buƙatar iyaka mafi girma? A tuntuɓe mu ta Taimako a bayyana hanyar amfani.
4. Wuraren ƙarshen
GET/api/v1/projects
Yana jera duk ayyukan yanar gizo (gidajen da ake bi) a wurin aiki.
GET/api/v1/projects/{channelid}/sessions
Yana jera zamukan baƙi da aka rikoda don aiki, sabbi da farko. An raba zuwa shafuka.
| Sigar buƙata | Bayani |
|---|---|
page | Lambar shafi, tsohon saiti 1. |
per_page | Sakamako a kowane shafi, tsohon saiti 25, iyaka 100. |
since | Zamuka da suka fara a wannan kwanan wata ko bayansa kaɗai (YYYY-MM-DD). |
until | Zamuka da suka fara a wannan kwanan wata ko kafinsa kaɗai. |
GET/api/v1/sessions/{session_id}
Metadata na zama guda, tare da kallon shafukansa. Da gangan ba ya haɗa cikakken bayanan sake kunnawa — a yi amfani da na’urar kunnawa ta dashboard don hakan.
GET/api/v1/sessions/{session_id}/events
Abubuwan da suka faru na musamman da aka tayar a zama (abubuwan ɗaya da ake aikawa da mp('event', ...)), har da sigoginsu.
GET/api/v1/projects/{channelid}/segments
Yana jera rukunin baƙi da aka ayyana don aiki (na aikin da na duk wurin aiki).
5. Haɗa ID na abokin ciniki daga bayan fage
Burauza sau da yawa ba ta san wanda yake zaune a can ba. A samfurin B2B ana tabbatar da ganewa bayan shiga — a bayan fage. A shago ana tabbatar da ita da amincewar oda. Wannan wurin ƙarshen na ainihin wannan lokaci ne.
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 sai ya bayyana a jerin zamuka, ana iya nemansa a can, kuma webhook na session_identified yana aiki — haka yake isa CRM.
"changed": false kuma ba a aika webhook. Maimaita oda ba ya ƙirƙirar mai sha’awa na biyu.| Matsayi | Lokaci |
|---|---|
400 | Fili ya ɓace, user_id ya wuce haruffa 128, ko akwai haruffan sarrafawa a ciki. Muna ƙin karɓa maimakon yankewa — ID da aka taƙaita a shiru ba ya dacewa da komai a CRM kuma har yanzu yana kama da nasara. |
404 | Zaman ba ya nan ko ba na wurin aikin ba ne. Da gangan amsa ɗaya ga duka. |
403 | Shirin wurin aiki ba ya haɗa API. |
6. Webhooks: tabbatar da sa hannu
Ana saita webhooks ga kowane aiki ƙarƙashin Haɗe-haɗe, inda ake samun signing secret. Kowace isarwa tana ɗauke da waɗannan headers:
| Header | Ma’ana |
|---|---|
X-MousePlayer-Event | Sunan abin da ya faru, misali session_identified |
X-MousePlayer-Timestamp | Sakannin Unix — cikin rubutun da aka sa wa hannu |
X-MousePlayer-Attempt | 1 a ƙoƙarin farko, mafi girma a sake gwadawa |
X-MousePlayer-Signature | sha256=<hex> |
Sa hannun HMAC-SHA256 ne a kan timestamp + "." + raw body, da signing secret na aikin a matsayin mabuɗi.
// 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');
Isarwa da sake gwadawa
Ana sake gwada isarwar da ta gaza bayan minti 1, mintuna 5, mintuna 15, awa 1 da awanni 6, sannan a daina. 4xx Amsoshin da ba 408 da 429 ba ba a sake gwada su — suna cewa "ba haka ba", ba "ba yanzu ba". A amsa 2xx da sauri a yi aikin daga baya; isarwa tana ƙare lokaci bayan sakan 10.
Abubuwan da suka faru da suke samuwa
| Abin da ya faru | Yana aiki |
|---|---|
session_identified | Idan zama ya fara samun ID na abokin ciniki — daga burauza ko API |
session_ended | Sau ɗaya, idan zama ya rufe |
goal_reached | Sau ɗaya ga zama, idan abin da ya faru na musamman ya cika ɗaya daga manufofi. Manufofi nau’in “event” kaɗai — ba a tantance manufofin URL, tsawon lokaci, kallon shafi da funnel. Yana ɗauke da goal_id, goal_name, goal_value da currency. |
high_value_session | Idan baƙo ya fara ketare iyakar ƙimar wannan aikin a wata rana. Iyakar tana fitowa daga rarrabar makin aikin kansa (kashi na 90 daga kwanaki 90 na ƙarshe), ba tabbatacciyar lamba ba, kuma ba ta samuwa sai an ba baƙi aƙalla 20 maki. Yana ɗauke da visitor_id, value_score, threshold da zaman da ya fi dacewa da kallo na wannan rana. |
funnel_dropoff | A ƙarshen zaman da ya shiga ɗaya daga funnels amma bai kammala shi ba. Yana bayyana matakin da ya tsaya a kai (dropped_at). Barin hanya rashin abin da ya faru ne, don haka ba a iya sani sai zama ya ƙare. Zamukan da ba su taɓa shiga funnel ba ba barin hanya ba ne kuma ba sa tayarwa. |
high_friction_session | Sau ɗaya ga zama, idan makin cikas ya fara kai iyaka (tsohon saiti 60 cikin 100). Yana ɗauke da friction_score, alamomin da suka haifar da shi (reasons) da alamar da ta ketare layi (trigger). |
element_broken | Sau ɗaya, idan abin da ake bi bai sami komai a duk kallon shafukan da aka duba na wasu kwanaki ba — yawanci bayan sake ƙaddamarwa. Yana sake aiki sai bayan alamar ta dace kuma ta sake lalacewa. Wannan abin da ya faru ba na wani zama ba ne: session_id da session_url suna null, link_url yana buɗe alamar maimakon haka, kuma subject_id yana bayyana sunan alamar — ɗaya ga kowace siga, don sabon selector da ya sake lalacewa ya shiga matsalar da take a buɗe. Yana ɗauke da rule_id, rule_name, selector, page, checked_page_views, window_days da last_matched. Babu bayanan baƙo. |
element_recovered | Sanarwar komai ya daidaita don element_broken: sau ɗaya da zarar alamar ta sake samun abu a zahiri — ƙarancin kallon shafi bai isa ba. Ana aikawa sai idan element_broken ya fita ta webhook, kuma ba shi da maɓallin kansa: rajistar element_broken yana haɗa shi. Ɗaya subject_id, don PagerDuty ya warware matsalar kuma Opsgenie ya rufe sanarwar. Yana ɗauke da matched_page_views da checked_page_views a ƙari. |
anomaly_detected | Sau ɗaya a rana, idan jiya ta bambanta a fili da kwanaki 28 da suka gabace ta: zamuka sun yi ƙasa ko yawa sosai, ƙimar manufa ta ragu, zamuka masu cikas ko kurakuran JS sun ƙaru. Ma’auni da shugabanci ɗaya suna yin shiru na mako guda (ana iya daidaitawa). Wannan abin da ya faru ba na wani zama ba ne: session_id da session_url suna null, link_url yana buɗe bayanin aiki, kuma subject_id yana bayyana ma’auni, shugabanci da rana. Yana ɗauke da metric (sessions, goal_rate, friction_rate, js_error_rate, lcp_p75, inp_p75, cls_p75), direction, day, value, expected, sessions, robust_z, z_score da summary mai karantuwa da hint. Babu bayanan baƙo. Don Web Vitals, measurements yana maye gurbin sessions, kuma page (fanko ga duk gidan yanar gizo) da device (desktop ko mobil) suna bayyana inda ya faru; link_url sai ya buɗe shafin Web Vitals. |
rage_click | Idan an gano dannawa cikin fushi |
error_detected | Idan an samu keɓancewar fuskar shafi |
ce | Rajistar haɗaka don abubuwan da suka faru na musamman na wurin. Wannan ba ya haɗa abubuwan da suke sama — suna da maɓallan kansu. |
7. Kurakurai & lambobin matsayi
| Matsayi | Ma’ana |
|---|---|
200 | Nasara. |
401 | Mabuɗin API ya ɓace, yana da tsarin da bai dace ba ko an soke shi. |
404 | Aikin ko zaman da aka nema ba ya nan, ko ba na wurin aikin ba ne. |
429 | An wuce iyakar yawan buƙata — ana aika fiye da buƙatu 60/minti da wannan mabuɗi. |
403 | Shirin wurin aiki ba ya haɗa REST API. Saƙon yana bayyana shirin da ake buƙata da na yanzu. |
8. Bayanan tsaro
- Mabuɗan karantawa kaɗai (mp_ro_) ba sa iya sauya komai. Mabuɗan rubutawa (mp_rw_) suna iya haɗa IDs na abokan ciniki kawai; babu mabuɗin da yake iya goge bayanai ko fitar da ɗanyen bayanan sake kunnawa.
- Ana iyakance kowace buƙata ta atomatik ga wurin aikin mabuɗi kansa — babu hanyar bayar da ID na wani wurin aiki a ga bayanan wani.
- A soke mabuɗi a kowane lokaci daga /api-keys; sokewa tana fara aiki nan take.
- A ɗauki mabuɗin API kamar kalmar sirri. Idan an tura shi bisa kuskure zuwa repository na jama’a, a soke shi nan take a ƙirƙiri sabo.
Shafukan abubuwan da suka faru masu iyaka (API v1, 14 Oktoba 2026)
GET /api/v1/sessions/{session_id}/events yana mayar da abubuwan da suka faru har 100 a tsohon saitin. A saita per_page zuwa cikakkiyar lamba daga 1 zuwa 100. A bi pagination.next_cursor ta aika cursor ba tare da sauyi ba a buƙata ta gaba; a riƙe zama da wurin aiki ɗaya. Ana jera abubuwan da suka faru ta created_at da event_id. An sa wa cursors hannu kuma an ɗaure su da wannan zama da wurin aiki. Ba a mayar da jimlar ƙidaya ko lambar shafi.
Array na data da map na params da suke nan suna ci gaba da samuwa. pagination.returned shi ne ainihin adadin da aka mayar; pagination.has_more yana nuna wani shafi. next_cursor yana null idan an gama. Amsa tana da iyakar bytes 524288, don haka shafi zai iya ɗauke da abubuwa ƙasa da per_page. Ga kowane abin da ya faru, ana mayar da layukan sigogi ba fiye da 128 ba; params_truncated yana true idan akwai ƙari. Sigogin rubutu ɗaya-ɗaya suna riƙe iyakar rumbun bayanai ta haruffa 255. Sigogin da aka yanke ba sa samuwa ta wannan wurin ƙarshen. Rage per_page ba ya ƙara iyakar sigogi.
Girman shafi mara inganci, cursors da aka sauya da cursors na wani zama/wurin aiki suna mayar da 400. Bayanan abu ɗaya da suka yi girma sosai suna mayar da 413. Dubawar shiga da suke nan har yanzu suna mayar da 401, 403, 404 ko 409 yadda ya dace.
Iyaka tana nan a buƙatu 60 da aka tabbatar ga kowane mabuɗin API a minti guda. Ƙare adadi yana mayar da 429 da Retry-After: 60. Idan Redis ko mai iyakancewa ba ya samuwa, buƙatu suna mayar da 503 da Retry-After: 5; ba a taɓa karɓarsu ba tare da iyaka ba. A bi Retry-After a ƙara jinkirin bazata; kada a sake gwadawa cikin zagaye marar tazara. Gazawar rumbun abubuwan da suka faru ma tana mayar da 503. Cursors ba sa daskarar da hoton bayanai: sababbin shigarwa masu tsofaffin timestamps a lokaci guda za su iya buƙatar sabon bincike.
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 hanyar sarrafa bayan fage ce ta Dev kaɗai don preview na native SDK. Tana kasancewa a kashe a production. Backend Bearer keys suna buƙatar read scope don list/replay da write scope don register/grant/delete/disable. Akwai ƙarin dubawar samuwar native-preview. Kada a taɓa saka mabuɗan API na wurin aiki na dindindin a manhajar salula.