প্রকাশ্য API & API কী

প্রোগ্রামের মাধ্যমে ওয়ার্কস্পেসে প্রবেশ — প্রকল্প, সেশন, কাস্টম ইভেন্ট ও সেগমেন্ট পড়ুন এবং সেশনে গ্রাহক ID যুক্ত করুন — ওয়ার্কস্পেসের মধ্যে সীমিত API কী দিয়ে সুরক্ষিত।

1. সারসংক্ষেপ

MousePlayer API দিয়ে ওয়ার্কস্পেসের ডেটা নিজের ড্যাশবোর্ড, ডেটা ওয়্যারহাউস বা অভ্যন্তরীণ সরঞ্জামে নিতে পারেন। সেশনে গ্রাহক ID যুক্ত করা ছাড়া (identify, লেখার পরিসরের কী দরকার, কী-এর পরিসর দেখুন) এটি শুধু পড়ার জন্য: API দিয়ে ডেটা বদলানো বা মোছা যায় না।

মূল URL: https://www.mouseplayer.com/api/v1/
সব উত্তর JSON।
প্রতিটি রিকোয়েস্ট API কী দিয়ে প্রমাণীকৃত হয় এবং স্বয়ংক্রিয়ভাবে কী-এর ওয়ার্কস্পেসে সীমিত থাকে — এক ওয়ার্কস্পেসের কী অন্যটির ডেটা কখনো দেখতে পারে না, ভুল করেও নয়।
পুরো সেশন রিপ্লে রেকর্ডিং (মাউসের নড়াচড়া, DOM স্ন্যাপশট) API দিয়ে প্রকাশ করা হয় না । সেশনের মেটাডেটা, পৃষ্ঠা দেখা, কাস্টম ইভেন্ট ও সেগমেন্ট পান — অপরিশোধিত রিপ্লের পেলোড ছড়ানো ছাড়াই প্রতিবেদন ও ড্যাশবোর্ড তৈরির জন্য যথেষ্ট।

2. প্রমাণীকরণ

অ্যাকাউন্ট মেনুতে এই বিভাগে API কী তৈরি ও পরিচালনা করুন: API কী (/api-keys)। শুধু ওয়ার্কস্পেসের মালিক ও অ্যাডমিন কী তৈরি বা প্রত্যাহার করতে পারেন।

কী গোপন রাখুন। ওয়ার্কস্পেসের সবকিছু পড়ার অনুমতি দেয়। তৈরি করার ঠিক পরে পুরো কী মাত্র একবার দেখায় — পাসওয়ার্ড ম্যানেজার বা সিক্রেট ভল্টে রাখুন। হারালে প্রত্যাহার করে নতুনটি তৈরি করুন।

প্রতিটি রিকোয়েস্টে Bearer টোকেন হিসেবে কী পাঠান এই Authorization হেডারে:

# List projects in your workspace curl -H "Authorization: Bearer mp_live_..." \ https://www.mouseplayer.com/api/v1/projects

অনুপস্থিত, ভুল বিন্যাসের বা প্রত্যাহার করা কী পায় একটি 401 উত্তর:

{ "error": "Invalid or missing API key. Use: Authorization: Bearer <key>" }

প্রয়োজনীয় প্ল্যান

REST API এই প্ল্যানগুলোর অংশ: Business ও Enterprise । প্ল্যান নেওয়া হয় ওয়ার্কস্পেসের মালিকের কাছ থেকে, তাই আমন্ত্রিত সদস্যরাও তা পান। পরীক্ষা হয় প্রতিটি রিকোয়েস্টে, শুধু কী তৈরির সময় নয় — ওয়ার্কস্পেসের প্ল্যান নামালে বিদ্যমান কী কাজ বন্ধ করে ফেরায় 403।

কী-এর পরিসর

প্রতিটি কী-এর প্রিফিক্সেই তার পরিসর থাকে, তাই দেখেই কাজ বোঝা যায় — একটি .env-এ, টিকিটে বা টার্মিনালে।

প্রিফিক্স	অর্থ
`mp_ro_`	শুধু পড়া। প্রকল্প, সেশন, ইভেন্ট ও সেগমেন্ট পড়ে। কিছু বদলাতে পারে না।
`mp_rw_`	পড়া ও লেখা। উপরের সব, সঙ্গে identify এন্ডপয়েন্ট দিয়ে গ্রাহক ID যুক্ত করা।

কী তৈরির সময় পরিসর বেছে নিন; ডিফল্ট শুধু পড়া। লেখার এন্ডপয়েন্টে শুধু পড়ার কী ব্যবহার করলে ফেরায় 403 , বার্তায় কী-এর ধরন ও এন্ডপয়েন্টের প্রয়োজন জানায়। পরে পরিসর বদলানো যায় না — নতুন কী তৈরি করে পুরোনোটি প্রত্যাহার করুন।

3. রিকোয়েস্টের হারসীমা

প্রতিটি API কী-এর সীমা প্রতি মিনিটে 60টি রিকোয়েস্ট, চলমান সময়সীমায় গণনা হয়। ছাড়িয়ে গেলে রিকোয়েস্ট পায় একটি 429 উত্তর, সময়সীমা খালি না হওয়া পর্যন্ত:

{ "error": "Rate limit exceeded. Max 60 requests per minute." }

বেশি সীমা দরকার এমন কিছু তৈরি করছেন? যোগাযোগ করুন সহায়তায় এবং আপনার ব্যবহারের কথা জানান।

4. এন্ডপয়েন্ট

GET/api/v1/projects

ওয়ার্কস্পেসের প্রতিটি প্রকল্প (ট্র্যাক করা ওয়েব প্রপার্টি) দেখায়।

{ "data": [ { "channelid": "955a45df5ee842cb", "domain": "yourdomain.com", "status": "active", "total_traffic_bytes": 27304765, "created_at": "2026-07-19 22:06:39", "last_used": "2026-08-05 01:12:55" } ] }

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

প্রকল্পের রেকর্ড করা দর্শকের সেশন দেখায়, নতুনগুলো আগে। পৃষ্ঠায় ভাগ করা।

কোয়েরি প্যারামিটার	বিবরণ
`page`	পৃষ্ঠার নম্বর, ডিফল্ট `1`।
`per_page`	প্রতি পৃষ্ঠায় ফল, ডিফল্ট `25`, সর্বোচ্চ `100`।
`since`	শুধু এই তারিখে বা তার পরে শুরু সেশন (`YYYY-MM-DD`)।
`until`	শুধু এই তারিখে বা তার আগে শুরু সেশন।

{ "data": [ { "session_id": "s_kfmist058_1785795295504", "visitor_id": "v_sv90jdpzo_1785795296042", "custom_user_id": null, "country": "DE", "device_type": "desktop", "is_bot": 0, "start_time": "2026-08-04 00:14:56", "end_time": "2026-08-04 00:16:41", "duration_seconds": 105 } ], "pagination": { "page": 1, "per_page": 25, "total": 142, "total_pages": 6 } }

GET/api/v1/sessions/{session_id}

একক সেশনের মেটাডেটা ও পৃষ্ঠা দেখা। ইচ্ছাকৃতভাবে পুরো রিপ্লে পেলোড বাদ থাকে — সে জন্য ড্যাশবোর্ডের প্লেয়ার ব্যবহার করুন।

{ "data": { "session_id": "s_kfmist058_1785795295504", "channelid": "955a45df5ee842cb", "visitor_id": "v_sv90jdpzo_1785795296042", "country": "DE", "asn_org": "Deutsche Telekom AG", "referrer": "https://duckduckgo.com/", "device_type": "desktop", "start_time": "2026-08-04 00:14:56", "end_time": "2026-08-04 00:16:41", "duration_seconds": 105, "pageviews": [ { "pageview_id": 1199, "url": "https://yourdomain.com/pricing", "page_title": "Pricing", "start_time": "2026-08-04 00:14:56", "end_time": "2026-08-04 00:16:41" } ] } }

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

সেশনে চালু কাস্টম ইভেন্ট (এই পদ্ধতিতে পাঠানো একই ইভেন্ট: mp('event', ...)), প্যারামিটারসহ।

{ "data": [ { "event_id": 61, "pageview_id": 1199, "event_name": "add_to_cart", "created_at": "2026-08-04 00:14:59", "params": { "item_id": "SKU_98765", "price": 299.99 } } ] }

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

প্রকল্পে নির্ধারিত দর্শকের সেগমেন্ট দেখায় (প্রকল্পের নিজস্ব ও পুরো ওয়ার্কস্পেসের দুটোই)।

{ "data": [ { "segment_id": 4, "name": "High Intent Visitors", "description": "Pageviews > 5", "badge_color": "cyan", "is_global": 0, "created_at": "2026-08-03 00:00:43" } ] }

5. ব্যাকএন্ড থেকে গ্রাহক ID যুক্ত করা

ব্রাউজার প্রায়ই জানে না কে বসে আছেন। B2B পণ্যে প্রবেশের পরে ব্যাকএন্ডে পরিচয় ঠিক হয় — দোকানে অর্ডার নিশ্চিতকরণে। এন্ডপয়েন্ট ঠিক সেই মুহূর্তের জন্য।

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 সেশন তালিকায় দেখায়, সেখানে খোঁজা যায় এবং এই session_identified ওয়েবহুক পাঠায় — এভাবেই CRM-এ পৌঁছায়।

একই ID দিয়ে দুবার কল করা নিরাপদ। উত্তরে আসে "changed": false , আর ওয়েবহুক পাঠানো হয় না। একই অর্ডার আবার এলে দ্বিতীয় লিড তৈরি হয় না।

স্ট্যাটাস	কখন
`400`	ঘর নেই, `user_id` 128 অক্ষরের বেশি অথবা নিয়ন্ত্রণ অক্ষর আছে। ছোট না করে প্রত্যাখ্যান করি — নীরবে ছোট ID CRM-এ কিছু মেলায় না, অথচ সফল মনে হয়।
`404`	সেশন নেই অথবা আপনার ওয়ার্কস্পেসের নয়। ইচ্ছাকৃতভাবে দুটোতেই একই উত্তর।
`403`	ওয়ার্কস্পেসের প্ল্যানে API নেই।

6. ওয়েবহুক: স্বাক্ষর যাচাই

প্রতি প্রকল্পে ওয়েবহুক কনফিগার করা হয় এখানে: ইন্টিগ্রেশন, যেখানে স্বাক্ষরের সিক্রেটও পাবেন। প্রতিটি ডেলিভারিতে এই হেডার থাকে:

হেডার	অর্থ
`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');

স্বাক্ষর করুন অপরিবর্তিত বডিতে, JSON পার্স করার আগে। আবার সিরিয়ালাইজ করলে কী-এর ক্রম ও ফাঁকা স্থান বদলায়, স্বাক্ষর আর মিলবে না। কয়েক মিনিটের চেয়ে পুরোনো টাইমস্ট্যাম্পও প্রত্যাখ্যান করুন — টাইমস্ট্যাম্প সে জন্যই।

পাঠানো ও পুনরায় চেষ্টা

ব্যর্থ ডেলিভারিতে আবার চেষ্টা হয় এই ব্যবধানে: 1 মিনিট, 5 মিনিট, 15 মিনিট, 1 ঘণ্টা ও 6 ঘণ্টা, তারপর বাদ যায়। 4xx উত্তরগুলোর মধ্যে ব্যতিক্রম শুধু 408 ও 429 ; অন্যগুলোর ক্ষেত্রে হয় না পুনরায় চেষ্টা — তারা বলে "এভাবে নয়", "এখন নয়" নয়। উত্তর দিন 2xx দ্রুত, কাজ পরে করুন; ডেলিভারি 10 সেকেন্ডে সময়সীমা ছাড়ায়।

যেসব ইভেন্ট আছে

ইভেন্ট	পাঠায় যখন
`session_identified`	সেশনে প্রথম গ্রাহক ID যুক্ত হলে — ব্রাউজার বা API থেকে
`session_ended`	একবার, সেশন বন্ধ হলে
`goal_reached`	প্রতি সেশনে একবার, কাস্টম ইভেন্ট আপনার কোনো লক্ষ্য পূরণ করলে। শুধু “event” ধরনের লক্ষ্য — URL, সময়কাল, পৃষ্ঠা দেখা ও ফানেলের লক্ষ্য মূল্যায়ন হয় না। পাঠায় `goal_id`, `goal_name`, `goal_value` ও `currency`।
`high_value_session`	কোনো দিনে দর্শক প্রথমবার এই প্রকল্পের মূল্যসীমা পার করলে। সীমা হলো আপনার নিজের স্কোরের বণ্টন থেকে নির্ধারিত (শেষ 90 দিনের 90তম পার্সেন্টাইল), নির্দিষ্ট সংখ্যা নয়, এবং অন্তত 20 জন দর্শকের স্কোর না হওয়া পর্যন্ত থাকে না। পাঠায় `visitor_id`, `value_score`, `threshold` ও ওই দিনের সবচেয়ে দেখার মতো সেশন।
`funnel_dropoff`	আপনার কোনো ফানেলে ঢুকে শেষ না করা সেশনের শেষে। যে ধাপে থেমেছে বলে (`dropped_at`)। ঝরে পড়া মানে ইভেন্ট না ঘটা, তাই সেশন শেষ হলেই জানা যায়। ফানেলে কখনো না ঢোকা সেশন ঝরে পড়া নয়, ইভেন্টও পাঠায় না।
`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` ওয়েবহুকে পাঠানো হয়েছিল; নিজস্ব সুইচ নেই: এই ইভেন্টে সাবস্ক্রাইব করলে `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_) শুধু গ্রাহক ID যুক্ত করতে পারে; কোনো কী ডেটা মুছতে বা অপরিশোধিত রিপ্লে ডেটা এক্সপোর্ট করতে পারে না।
প্রতিটি রিকোয়েস্ট স্বয়ংক্রিয়ভাবে কী-এর নিজের ওয়ার্কস্পেসে সীমিত — অন্য ওয়ার্কস্পেস ID দিয়ে অন্যের ডেটা দেখার উপায় নেই।
যেকোনো সময় কী প্রত্যাহার করুন এই বিভাগ থেকে: /api-keys; সঙ্গে সঙ্গে কার্যকর হয়।
API কী পাসওয়ার্ডের মতো রাখুন। ভুলে প্রকাশ্য রিপোজিটরিতে কমিট করলে সঙ্গে সঙ্গে প্রত্যাহার করে নতুনটি তৈরি করুন।

সীমিত ইভেন্ট পৃষ্ঠা (API v1, 14 অক্টোবর 2026)

GET /api/v1/sessions/{session_id}/events ডিফল্টভাবে সর্বোচ্চ 100টি ইভেন্ট দেয়। per_page-এ 1 থেকে 100-এর পূর্ণসংখ্যা দিন। পরের রিকোয়েস্টে cursor অপরিবর্তিত পাঠিয়ে pagination.next_cursor অনুসরণ করুন; একই সেশন ও ওয়ার্কস্পেস রাখুন। ইভেন্ট created_at ও event_id অনুযায়ী সাজানো। কার্সর স্বাক্ষরিত এবং ওই সেশন ও ওয়ার্কস্পেসে বাঁধা। মোট সংখ্যা বা সংখ্যার পৃষ্ঠা ফেরানো হয় না।

বিদ্যমান data অ্যারে ও params ম্যাপ থাকে। pagination.returned আসলে ফেরানো সংখ্যা; pagination.has_more আরেকটি পৃষ্ঠা নির্দেশ করে। শেষ হলে next_cursor null। উত্তর সর্বোচ্চ 524288 বাইট, তাই পৃষ্ঠায় per_page-এর চেয়ে কম ইভেন্ট থাকতে পারে। প্রতি ইভেন্টে সর্বোচ্চ 128টি প্যারামিটারের সারি আসে; বেশি থাকলে params_truncated true। একক লেখার প্যারামিটারে ডেটাবেসের 255 অক্ষরের সীমা থাকে। বাদ পড়া প্যারামিটার এই এন্ডপয়েন্টে পাওয়া যায় না। per_page কমালে প্যারামিটারের সীমা বাড়ে না।

অকার্যকর পৃষ্ঠার আকার, বদলানো কার্সর এবং অন্য সেশন/ওয়ার্কস্পেসের কার্সরে 400 আসে। অতিরিক্ত বড় একক ইভেন্টের ডেটায় 413 আসে। আগের প্রবেশাধিকার পরীক্ষা যথাযথভাবে 401, 403, 404 বা 409 ফেরায়।

সীমা এখনও প্রতি API কী-তে মিনিটে 60টি প্রমাণীকৃত রিকোয়েস্ট। সীমা শেষ হলে 429 ও Retry-After: 60 আসে। Redis বা সীমা নিয়ন্ত্রক না থাকলে 503 ও Retry-After: 5 আসে; সীমা ছাড়া কখনো অনুমতি দেওয়া হয় না। Retry-After মেনে এলোমেলো অপেক্ষা যোগ করুন; বিরতিহীন লুপে আবার চেষ্টা করবেন না। ইভেন্ট ডেটাবেসের ব্যর্থতাতেও 503 আসে। কার্সর স্থির স্ন্যাপশট ধরে না: সমসাময়িক পুরোনো টাইমস্ট্যাম্পের ইনসার্টে নতুন স্ক্যান লাগতে পারে।

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 নেটিভ SDK পূর্বরূপের শুধু Dev-এর ব্যাকএন্ড নিয়ন্ত্রণ পথ। প্রোডাকশনে বন্ধই থাকে। ব্যাকএন্ড Bearer কী-তে list/replay-এর জন্য পড়ার পরিসর এবং register/grant/delete/disable-এর জন্য লেখার পরিসর দরকার। অতিরিক্ত native-preview উপলব্ধতার পরীক্ষা প্রযোজ্য। মোবাইল অ্যাপে স্থায়ী ওয়ার্কস্পেস API কী কখনো বসাবেন না।

আমরা কীভাবে সাহায্য করতে পারি?