عوامی API اور API کلیدیں

1. جائزہ

MousePlayer API سے ورکاسپیس کا ڈیٹا اپنے ڈیشبورڈز، ڈیٹا گودام یا اندرونی ٹولز میں لے سکتے ہیں۔ سیشنز سے گاہک IDs جوڑنے کے علاوہ (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 اینڈپوائنٹ سے گاہک IDs جوڑنا۔

کلید بناتے وقت دائرہ چنیں؛ طے شدہ صرف پڑھنا ہے۔ لکھنے والے اینڈپوائنٹ پر صرف پڑھنے کی کلید یہ لوٹاتی ہے: 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_) صرف گاہک IDs جوڑ سکتی ہیں؛ کوئی کلید ڈیٹا حذف یا خام ریکارڈنگ برآمد نہیں کر سکتی۔
ہر درخواست خودکار طور پر کلید کے اپنے ورکاسپیس تک محدود ہے — دوسری ورکاسپیس 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 کے لیے لکھنے کا دائرہ چاہیے۔ مقامی پیش منظر کی دستیابی کی اضافی جانچیں لاگو ہیں۔ موبائل ایپ میں مستقل ورکاسپیس API کلیدیں کبھی شامل نہ کریں۔

ہم کیسے مدد کر سکتے ہیں؟