පොදු API & API යතුරු
ඔබේ වැඩ අවකාශයට ක්‍රමලේඛන ප්‍රවේශය — ව්‍යාපෘති, සැසි, අභිරුචි සිදුවීම් සහ ඛණ්ඩ කියවා පාරිභෝගික අංක සැසිවලට එක් කරන්න — වැඩ අවකාශයට සීමා කළ API යතුරුවලින් ආරක්ෂිතයි.
1. දළ විශ්ලේෂණය
MousePlayer API ඔබේ වැඩ අවකාශයෙන් ඔබේම dashboard, දත්ත ගබඩාව හෝ අභ්‍යන්තර මෙවලම් වෙත දත්ත ලබාගැනීමට ඉඩ දෙයි. පාරිභෝගික අංක සැසිවලට එක් කිරීම හැර (identify, ලිවීමේ විෂය පථය සහිත යතුරක් අවශ්‍යයි; යතුරු විෂය පථ බලන්න) එය කියවීමට පමණි: API හරහා දත්ත වෙනස් කිරීමට හෝ මැකීමට නොහැකිය.
- මූලික URL:
https://www.mouseplayer.com/api/v1/ - සියලු පිළිතුරු JSON වේ.
- සෑම ඉල්ලීමක්ම API යතුරකින් සත්‍යාපනය කර ස්වයංක්‍රීයව යතුර අයත් වැඩ අවකාශයට සීමා කරයි — එක් වැඩ අවකාශයක යතුරකට අහම්බෙන්වත් අනෙකේ දත්ත දැකිය නොහැකිය.
- සම්පූර්ණ සැසි නැවත ධාවන පටිගත කිරීම (මූසික චලන, DOM සැණරු) නොලැබේ API හරහා. සැසි පාරදත්ත, පිටු දසුන්, අභිරුචි සිදුවීම් සහ ඛණ්ඩ ලැබේ — මුල් නැවත ධාවන දත්ත යවන්නේ නැතිව වාර්තා සහ dashboard සෑදීමට ප්‍රමාණවත්ය.
2. සත්‍යාපනය
API යතුරු සාදා කළමනාකරණය කරන්න: API යතුරු ගිණුම් මෙනුවේ (/api-keys). යතුරු සෑදීමට හෝ අවලංගු කිරීමට හැක්කේ වැඩ අවකාශ හිමිකරුවන්ට සහ පරිපාලකයන්ට පමණි.
යතුර රහසක් ලෙස තබාගන්න. වැඩ අවකාශයේ සියල්ලට කියවීමේ ප්‍රවේශය ලබා දෙයි. සම්පූර්ණ යතුර පෙන්වන්නේ හරියටම එක් වරක්, සෑදූ වහාමය — මුරපද කළමනාකරු හෝ රහස් ගබඩාවක තබන්න. නැතිවුවහොත් අවලංගු කර අලුත් එකක් සාදන්න.
සෑම ඉල්ලීමකම පහත ශීර්ෂයේ Bearer ටෝකනයක් ලෙස යතුර යවන්න: Authorization ශීර්ෂය:
නැති, වැරදි හැඩයේ හෝ අවලංගු යතුරුවලට ලැබෙන්නේ 401 පිළිතුර:
සැලසුම් අවශ්‍යතාව
REST API ඇතුළත් වන්නේ Business සහ Enterprise සැලසුම්වලය. සැලසුම ගන්නේ වැඩ අවකාශයේ හිමිකරුගෙනි ; එබැවින් ආරාධිත කණ්ඩායම් සාමාජිකයන්ටද එය අදාළ වේ. පරීක්ෂාව සිදු වන්නේ සෑම ඉල්ලීමකදීමය, යතුර සාදන විට පමණක් නොවේ — වැඩ අවකාශය පහත මට්ටමකට මාරු කළහොත් පවතින යතුරු ක්‍රියා නොකර පහත ලබා දෙයි: 403.
යතුරු විෂය පථ
සෑම යතුරකම විෂය පථය තම උපසර්ගයේ ඇති බැවින් බැලීමෙන්ම කරන දේ දැනගත හැකිය — පහත තුළ, .env, ඉල්ලීමක හෝ ටර්මිනලයක.
| උපසර්ගය | අර්ථය |
|---|---|
mp_ro_ | කියවීමට පමණි. ව්‍යාපෘති, සැසි, සිදුවීම් සහ ඛණ්ඩ කියවයි. කිසිවක් වෙනස් කළ නොහැකිය. |
mp_rw_ | කියවීම සහ ලිවීම. ඉහත සියල්ල සහ identify endpoint හරහා පාරිභෝගික අංක එක් කිරීම. |
403 යතුර කුමක්ද සහ endpoint ට අවශ්‍ය දේ නම් කරන පණිවිඩයක් සමඟය. පසුව විෂය පථය වෙනස් කළ නොහැකිය — අලුත් යතුරක් සාදා පැරණි එක අවලංගු කරන්න.3. ඉල්ලීම් අනුපාත සීමා
සෑම API යතුරක්ම සීමා වන්නේ විනාඩියකට ඉල්ලීම් 60 කටය, ගමන් කරන කාල කවුළුවකින් ලුහුබඳියි. එය ඉක්මවූ විට ඉල්ලීම්වලට ලැබෙන්නේ 429 පිළිතුර, කාල කවුළුව නිදහස් වන තුරු:
වැඩි සීමාවක් අවශ්‍ය දෙයක් සාදනවාද? අමතන්න: සහාය ඔබේ භාවිත අවස්ථාව ගැන කියන්න.
4. Endpoint
GET/api/v1/projects
ඔබේ වැඩ අවකාශයේ සෑම ව්‍යාපෘතියක්ම (ලුහුබඳින අඩවියක්) ලැයිස්තුගත කරයි.
GET/api/v1/projects/{channelid}/sessions
ව්‍යාපෘතියකට පටිගත කළ අමුත්තන්ගේ සැසි අලුත්ම ඒවා මුලින් ලැයිස්තුගත කරයි. පිටුකරණය ඇත.
| විමසුම් පරාමිතිය | විස්තරය |
|---|---|
page | පිටු අංකය, පෙරනිමිය 1. |
per_page | පිටුවකට ප්‍රතිඵල, පෙරනිමිය 25, උපරිමය 100. |
since | මෙම දිනයේ හෝ ඉන්පසු ඇරඹෙන සැසි පමණි (YYYY-MM-DD). |
until | මෙම දිනයේ හෝ ඊට පෙර ඇරඹෙන සැසි පමණි. |
GET/api/v1/sessions/{session_id}
එක් සැසියක පාරදත්ත සහ එහි පිටු දසුන්. සම්පූර්ණ නැවත ධාවන දත්ත හිතාමතා බැහැර කරයි — ඒ සඳහා dashboard ධාවකය භාවිත කරන්න.
GET/api/v1/sessions/{session_id}/events
සැසියකදී ජනනය වූ අභිරුචි සිදුවීම් (ඔබ පහත මඟින් යවන සිදුවීම්මය: mp('event', ...)), ඒවායේ පරාමිතිද සමඟ.
GET/api/v1/projects/{channelid}/segments
ව්‍යාපෘතියකට නිර්වචනය කළ අමුත්තන්ගේ ඛණ්ඩ ලැයිස්තුගත කරයි (ව්‍යාපෘති-විශේෂ සහ වැඩ අවකාශය පුරා ඛණ්ඩ දෙකම).
5. ඔබේ backend වෙතින් පාරිභෝගික අංකයක් එක් කිරීම
බ්‍රවුසරය බොහෝ විට එහි සිටින්නේ කවුදැයි නොදනී. B2B නිෂ්පාදනයක පිවිසීමෙන් පසු අනන්‍යතාව තහවුරු වන්නේ — ඔබේ backend තුළය. වෙළඳසැලක එය තහවුරු වන්නේ ඇණවුම තහවුරු කිරීමේදීය. මෙම endpoint හරියටම එම මොහොත සඳහාය.
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}}ඉන්පසු අංකය සැසි ලැයිස්තුවේ පෙනී එහි සෙවිය හැකි වන අතර පහත session_identified webhook ක්‍රියාත්මක වේ — එසේ ඔබේ CRM වෙත ළඟා වේ.
"changed": false සහ කිසිදු webhook නොයවයි. නැවත කළ ඇණවුමක් දෙවන විකිණුම් ඉඟියක් නොසාදයි.| තත්ත්වය | අවස්ථාව |
|---|---|
400 | නැති ක්ෂේත්‍රයක්, user_id අක්ෂර 128 ට වැඩි හෝ පාලන අක්ෂර අඩංගුය. කෙටි කරනවා වෙනුවට ප්‍රතික්ෂේප කරයි — නිහඬව කෙටි කළ අංකයක් CRM හි කිසිවකට නොගැළපෙන නමුත් සාර්ථක ලෙස පෙනේ. |
404 | සැසිය නොපවතී හෝ ඔබේ වැඩ අවකාශයට අයත් නොවේ. දෙකටම හිතාමතා එකම පිළිතුරයි. |
403 | වැඩ අවකාශ සැලසුමට API ඇතුළත් නැත. |
6. Webhook: අත්සන තහවුරු කිරීම
ව්‍යාපෘතියකට webhook වින්‍යාස කරන්නේ පහත යටතේය: ඒකාබද්ධතා, අත්සන් රහස් යතුරද එහි ඇත. සෑම බෙදාහැරීමකම මෙම ශීර්ෂ ඇත:
| ශීර්ෂය | අර්ථය |
|---|---|
X-MousePlayer-Event | සිදුවීම් නම, උදා. session_identified |
X-MousePlayer-Timestamp | Unix තත්පර — අත්සන් කළ පෙළේ කොටසකි |
X-MousePlayer-Attempt | මුල් උත්සාහයේ 1, නැවත උත්සාහවල වැඩිය |
X-MousePlayer-Signature | sha256=<hex> |
අත්සන පහත මත HMAC-SHA256 වේ: timestamp + "." + raw body, ඔබේ ව්‍යාපෘතියේ අත්සන් රහස් යතුර යොදා.
// 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');
බෙදාහැරීම සහ නැවත උත්සාහ
අසාර්ථක බෙදාහැරීමක් නැවත උත්සාහ කරන්නේ පහත පසුවය: විනාඩි 1, විනාඩි 5, විනාඩි 15, පැය 1 සහ පැය 6, ඉන්පසු අත්හරියි. 4xx පහත හැර වෙනත් පිළිතුරු 408 සහ 429 නැවත උත්සාහ නොකරයි — ඒවා කියන්නේ "මෙහෙම නොවේ" යන්නයි, "දැන් නොවේ" නොවේ. පිළිතුරු දෙන්න: 2xx ඉක්මනින්; වැඩ පසුව කරන්න; බෙදාහැරීම තත්පර 10 කින් කල් ඉකුත් වේ.
ලබාගත හැකි සිදුවීම්
| සිදුවීම | ක්‍රියාත්මක වන අවස්ථාව |
|---|---|
session_identified | සැසියකට මුලින් පාරිභෝගික අංකයක් ලැබෙන විට — බ්‍රවුසරයෙන් හෝ API වෙතින් |
session_ended | එක් වරක්, සැසිය වසන විට |
goal_reached | එක් සැසියකට එක් වරක්, අභිරුචි සිදුවීමක් ඔබේ ඉලක්කයක් ඉටු කරන විට. “event” වර්ගයේ ඉලක්ක පමණි — URL, කාලය, පිටු දසුන් සහ funnel ඉලක්ක ඇගයෙන්නේ නැත. රැගෙන යන්නේ goal_id, goal_name, goal_value සහ currency. |
high_value_session | අමුත්තකු නිශ්චිත දිනක මෙම ව්‍යාපෘතියේ වටිනාකම් සීමාව මුලින් ඉක්මවන විට. සීමාව ඔබේම ලකුණු ව්‍යාප්තියෙන් ලබාගනී (පසුගිය දින 90 හි 90 වන ප්‍රතිශතකය), ස්ථිර සංඛ්‍යාවක් නොවේ; අවම අමුත්තන් 20 කට ලකුණු දෙන තුරු එය නොපවතී. රැගෙන යන්නේ visitor_id, value_score, threshold සහ එම දිනයේ වඩාත් නැරඹීමට වටිනා සැසියයි. |
funnel_dropoff | ඔබේ funnel එකකට ඇතුළු වූ නමුත් අවසන් නොකළ සැසියක් අවසන් වන විට. නැවතුණු පියවර නම් කරයි (dropped_at). අත්හැරීමක් සිදුවීමක් නොමැති වීම වන නිසා දැනගත හැක්කේ සැසිය අවසන් වූ පසුවය. funnel වෙත කිසිදා නොපිවිසුණු සැසි අත්හැරීම් නොවන අතර ප්‍රේරණය නොකරයි. |
high_friction_session | එක් සැසියකට එක් වරක්, බාධා ලකුණු මුලින් සීමාවට ළඟා වන විට (පෙරනිමිය 60, උපරිමය 100). රැගෙන යන්නේ friction_score, ඒ පිටුපස සංඥා (reasons) සහ සීමාව ඉක්මවූ සංඥාව (trigger). |
element_broken | එක් වරක්, සලකුණු කළ අංගයක් දින කිහිපයක් පරීක්ෂා කළ කිසිදු පිටු දසුනක කිසිවක් සොයා නොගත් විට — සාමාන්‍යයෙන් නැවත දියත් කිරීමකට පසුව. සලකුණ නැවත ගැළපී තවත් වරක් බිඳුණු පසුව පමණක් නැවත ක්‍රියාත්මක වේ. මෙම සිදුවීම කිසිදු සැසියකට අයත් නොවේ: session_id සහ session_url වන්නේ null, link_url ඒ වෙනුවට සලකුණ විවෘත කරයි, සහ subject_id සලකුණ නම් කරයි — සෑම අනුවාදයකටම එකම නම නිසා නැවත බිඳුණු අලුත් තේරීම්කාරකයක් විවෘත සිද්ධියට එක් වේ. රැගෙන යන්නේ rule_id, rule_name, selector, page, checked_page_views, window_days සහ last_matched. අමුත්තන්ගේ දත්ත නැත. |
element_recovered | පහත සඳහා යථා තත්ත්වයට පත්වීමේ සංඥාව: element_broken: සලකුණ සැබෑවට නැවත අංගයක් සොයාගත් විට — පිටු දසුන් අඩුවීම පමණක් ප්‍රමාණවත් නැත. යවන්නේ පහත element_broken webhook හරහා යැවී ඇත්නම් පමණි; එයට වෙනම ස්විචයක් නැත: පහතට දායක වීමෙන් element_broken මෙයද ඇතුළත් වේ. එකම subject_id, එබැවින් PagerDuty සිද්ධිය විසඳන අතර Opsgenie දැනුම්දීම වසයි. රැගෙන යන්නේ matched_page_views සහ checked_page_views අමතරව. |
anomaly_detected | දිනකට වරක්, පෙර දිනය ඊට පෙර දින 28 ට වඩා පැහැදිලිව වෙනස් වූ විට: බෙහෙවින් අඩු හෝ වැඩි සැසි, අඩු වූ ඉලක්ක අනුපාතය, බාධා හෝ JS දෝෂ ඇති වැඩි සැසි. එකම මිනුම සහ දිශාව සතියක් නිහඬව පවතී (සකස් කළ හැකිය). මෙම සිදුවීම කිසිදු සැසියකට අයත් නොවේ: session_id සහ session_url වන්නේ null, link_url ව්‍යාපෘති දළ විශ්ලේෂණය විවෘත කරයි, සහ subject_id මිනුම, දිශාව සහ දිනය නම් කරයි. රැගෙන යන්නේ metric (sessions, goal_rate, friction_rate, js_error_rate, lcp_p75, inp_p75, cls_p75), direction, day, value, expected, sessions, robust_z, z_score සහ කියවිය හැකි summary සහ hint. අමුත්තන්ගේ දත්ත නැත. Web Vitals සඳහා, measurements ප්‍රතිස්ථාපනය කරන්නේ sessions, සහ page (මුළු අඩවිය සඳහා හිස්) සහ device (desktop හෝ mobil) සිදු වූ තැන කියයි; link_url එවිට Web Vitals ටැබය විවෘත කරයි. |
rage_click | හඳුනාගත් කෝපයෙන් ක්ලික් කිරීමකදී |
error_detected | ඉදිරිපස ව්‍යතිරේකයකදී |
ce | ඔබේම අභිරුචි සිදුවීම් සඳහා සාමූහික දායකත්වය. එයට ඇතුළත් නොවේ ඉහත සිදුවීම් — ඒවාට තමන්ගේම ස්විච ඇත. |
7. දෝෂ & තත්ත්ව කේත
| තත්ත්වය | අර්ථය |
|---|---|
200 | සාර්ථකයි. |
401 | නැති, වැරදි හැඩයේ හෝ අවලංගු API යතුර. |
404 | ඉල්ලූ ව්‍යාපෘතිය හෝ සැසිය නොපවතී, නැතහොත් ඔබේ වැඩ අවකාශයට අයත් නොවේ. |
429 | අනුපාත සීමාව ඉක්මවීය — මෙම යතුරෙන් විනාඩියකට ඉල්ලීම් 60 ට වඩා යවයි. |
403 | වැඩ අවකාශ සැලසුමට REST API ඇතුළත් නැත. පණිවිඩය අවශ්‍ය සහ වත්මන් සැලසුම් දෙකම නම් කරයි. |
8. ආරක්ෂක සටහන්
- කියවීමට පමණක් යතුරුවලට (mp_ro_) කිසිවක් වෙනස් කළ නොහැකිය. ලිවීමේ යතුරුවලට (mp_rw_) පාරිභෝගික අංක එක් කළ හැක්කේ පමණි; කිසිදු යතුරකට දත්ත මැකීමට හෝ මුල් නැවත ධාවන දත්ත අපනයනය කිරීමට නොහැකිය.
- සෑම ඉල්ලීමක්ම ස්වයංක්‍රීයව යතුරේම වැඩ අවකාශයට සීමා වේ — වෙනත් වැඩ අවකාශ අංකයක් සපයා අනෙකකුගේ දත්ත දැකිය නොහැකිය.
- ඕනෑම වේලාවක යතුර අවලංගු කරන්න: /api-keys; අවලංගු කිරීම වහා ක්‍රියාත්මක වේ.
- API යතුර මුරපදයක් මෙන් සලකන්න. අහම්බෙන් පොදු repository එකකට commit කළහොත් වහා අවලංගු කර අලුත් එකක් සාදන්න.
සීමා කළ සිදුවීම් පිටු (API v1, 14 ඔක්තෝබර් 2026)
GET /api/v1/sessions/{session_id}/events පෙරනිමියෙන් උපරිම සිදුවීම් 100 ක් ලබා දෙයි. per_page සඳහා 1 සිට 100 දක්වා පූර්ණ සංඛ්‍යාවක් සකසන්න. ඊළඟ ඉල්ලීමේදී cursor නොවෙනස්ව යවා pagination.next_cursor අනුගමනය කරන්න; එකම සැසිය සහ වැඩ අවකාශය තබාගන්න. සිදුවීම් created_at සහ event_id අනුව පෙළගස්වා ඇත. cursor අත්සන් කර එම සැසියට සහ වැඩ අවකාශයට බැඳී ඇත. මුළු ගණනක් හෝ සංඛ්‍යාත්මක පිටුවක් ලබා නොදෙයි.
පවතින data අරාව සහ params සිතියම තවම ලබාගත හැකිය. pagination.returned සැබෑවට ලබා දුන් ගණනයි; pagination.has_more තවත් පිටුවක් දක්වයි. සම්පූර්ණ වූ විට next_cursor යනු null ය. පිළිතුර බයිට් 524288 කට සීමා කරන නිසා පිටුවක per_page ට අඩු සිදුවීම් තිබිය හැකිය. එක් සිදුවීමකට උපරිම පරාමිති පේළි 128 ක් ලබා දෙයි; වැඩිපුර ඇත්නම් params_truncated යනු true ය. තනි පෙළ පරාමිතිවල දත්ත සමුදා සීමාව අක්ෂර 255 ක් ලෙස පවතී. කෙටි කළ පරාමිති මෙම endpoint හරහා ලබාගත නොහැකිය. per_page අඩු කිරීමෙන් පරාමිති සීමාව වැඩි නොවේ.
වලංගු නොවන පිටු ප්‍රමාණ, වෙනස් කළ cursor සහ වෙනත් සැසියක/වැඩ අවකාශයක cursor සඳහා 400 ලැබේ. ප්‍රමාණය වැඩි තනි සිදුවීම් දත්ත සඳහා 413 ලැබේ. පවතින ප්‍රවේශ පරීක්ෂාවලින් තවමත් අදාළ ලෙස 401, 403, 404 හෝ 409 ලැබේ.
සීමාව API යතුරකට විනාඩියකට සත්‍යාපිත ඉල්ලීම් 60 ක් ලෙස පවතී. එය අවසන් වූ විට 429 ලැබේ, Retry-After: 60 සමඟ. Redis හෝ සීමාකරු ලබාගත නොහැකි නම් 503 ලැබේ, Retry-After: 5 සමඟ; සීමාවක් නැතිව කිසිදා ඉඩ නොදෙයි. Retry-After පිළිපැද අහඹු ප්‍රමාදයක් එක් කරන්න; දැඩි ලූපයක නැවත උත්සාහ නොකරන්න. සිදුවීම් දත්ත සමුදා අසාර්ථකත්වවලටද 503 ලැබේ. cursor සැණරුවක් ස්ථාවර නොකරයි: පැරණි වේලා සටහන් සහිත සමගාමී ඇතුළත් කිරීම් සඳහා අලුත් පිරික්සුමක් අවශ්‍ය විය හැකිය.
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 යනු native SDK පෙරදසුන සඳහා Dev-පමණක් backend පාලන මාර්ගයකි. නිෂ්පාදනයේ එය අක්‍රියව පවතී. Backend Bearer යතුරුවලට list/replay සඳහා කියවීමේ විෂය පථයත් register/grant/delete/disable සඳහා ලිවීමේ විෂය පථයත් අවශ්‍යයි. අමතර native-preview ලබාගත හැකි බව පරීක්ෂා කිරීම් අදාළ වේ. ස්ථිර වැඩ අවකාශ API යතුරු ජංගම යෙදුමක කිසිදා ඇතුළත් නොකරන්න.