عوامي API & API key

پنهنجي ڪم جي جاءِ تائين پروگرام ذريعي رسائي — پروجيڪٽ، سيشن، پنهنجي ٺاهيل واقعا ۽ ڀاڱا پڙهو، ۽ سيشنن سان گراهڪ ID ڳنڍيو — ڪم جي جاءِ تائين محدود API key سان محفوظ.

1. جائزو

MousePlayer API ڪم جي جاءِ مان ڊيٽا پنهنجي ڊيش بورڊ، data warehouse يا اندروني اوزارن ۾ وٺڻ ڏئي ٿي. سيشنن سان گراهڪ ID ڳنڍڻ کان سواءِ (identify، لکڻ جي دائري واري key گهرجي، Key جا دائرا ڏسو)، هي آهي رڳو پڙهڻ لاءِ: API ذريعي ڪا ڊيٽا بدلائي يا ختم نٿي ڪري سگهجي.

  • بنيادي URL: https://www.mouseplayer.com/api/v1/
  • سڀ جواب JSON آهن.
  • هر درخواست API key سان تصديق ۽ پاڻمرادو انهيءَ ڪم جي جاءِ تائين محدود ٿئي ٿي جنهن جي key آهي — هڪ ڪم جي جاءِ جي key ٻي جي ڊيٽا ڪڏهن به نٿي ڏسي سگهي، اتفاق سان به نه.
  • مڪمل سيشن ٻيهر پلے رڪارڊنگ (مائوس حرڪتون، DOM تصويرون) API ذريعي نه ڏني وڃي ٿي. سيشن ميٽاڊيٽا، صفحن جا ڏيک، پنهنجي ٺاهيل واقعا ۽ ڀاڱا ملن ٿا — خام ٻيهر پلے ڊيٽا گهمائڻ کان سواءِ رپورٽون ۽ ڊيش بورڊ ٺاهڻ لاءِ ڪافي.

2. تصديق

پنهنجون API key هتي ٺاهيو ۽ سنڀاليو API key اڪائونٽ مينيو ۾ (/api-keys). رڳو ڪم جي جاءِ جا مالڪ ۽ ايڊمن key ٺاهي يا واپس وٺي سگهن ٿا.

پنهنجي key ڳجهي رکو. ڪم جي جاءِ جي سڀني شين تائين پڙهڻ جي رسائي ڏئي ٿي. پوري key بلڪل هڪ ڀيرو، ٺاهڻ کان فوراً پوءِ ڏيکارجي ٿي — پاس ورڊ مينيجر يا راز جي محفوظ جاءِ ۾ رکو. وڃايو ته واپس وٺي نئين ٺاهيو.

هر درخواست جي هن ۾ key، Bearer token طور موڪليو Authorization Header:

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

غير موجود، غلط صورت يا واپس ورتل key کي هي 401 جواب ملي ٿو:

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

پلان جي گهرج

REST API هنن جو حصو آهي Business ۽ Enterprise پلان. پلان ورتو وڃي ٿو ڪم جي جاءِ جي هن کان مالڪ ، تنهنڪري دعوت ڏنل ٽيم ميمبر اهو ورثي ۾ وٺن ٿا. جاچ هلي ٿي هر درخواست تي، رڳو key ٺاهڻ وقت نه — ڪم جي جاءِ جو درجو گهٽجي ته موجوده key ڪم بند ڪري هي موٽائين ٿيون 403.

Key جا دائرا

هر key پنهنجو دائرو پنهنجي اڳياڙي ۾ کڻي ٿي، تنهنڪري رڳو ڏسي ڄاڻي سگهو ٿا ته ڇا ڪري ٿي — هن ۾ .env، ticket ۾ يا terminal ۾.

اڳياڙيمطلب
mp_ro_رڳو پڙهڻ. پروجيڪٽ، سيشن، واقعا ۽ ڀاڱا پڙهي ٿي. ڪجهه بدلائي نٿي سگهي.
mp_rw_پڙهڻ ۽ لکڻ. مٿيون سڀ، ۽ identify endpoint ذريعي گراهڪ ID ڳنڍڻ.
Key ٺاهڻ وقت دائرو چونڊيو؛ ڊفالٽ رڳو پڙهڻ آهي. لکڻ واري endpoint تي رڳو پڙهڻ واري key هي موٽائي ٿي 403 ، پيغام سان ته key ڇا آهي ۽ endpoint کي ڇا گهرجي. پوءِ دائرو نٿو بدلجي — نئين key ٺاهي پراڻي واپس وٺو.

3. درخواستن جون حدون

هر API key جي حد آهي هر منٽ 60 درخواستون، هلندڙ وقت جي دري تي ڳڻيل. وڌيڪ ٿيو ته درخواستن کي هي 429 جواب ملي ٿو جيستائين دري صاف ٿئي:

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

وڌيڪ حد گهرندڙ شيءِ ٺاهيو ٿا؟ رابطو ڪريو هن ذريعي مدد ۽ پنهنجو استعمال ٻڌايو.

4. Endpoint

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

پروجيڪٽ لاءِ رڪارڊ ٿيل مهمان سيشن ڏيکاري ٿو، نوان پهرين. صفحن ۾ ورهايل.

Query پيراميٽروضاحت
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. پنهنجي backend مان گراهڪ ID ڳنڍڻ

برائوزر اڪثر نٿو ڄاڻي ته ڪير ويٺو آهي. 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}}

پوءِ ID سيشن فهرست ۾ اچي، اتي ڳولي سگهجي ٿو، ۽ هي session_identified webhook هلي ٿو — ائين توهان جي CRM تائين پهچي ٿو.

ساڳئي ID سان ٻه ڀيرا سڏڻ محفوظ آهي. جواب هن سان واپس اچي ٿو "changed": false ۽ ڪو webhook نٿو موڪلجي. ورجايل آرڊر ٻيو lead نٿو ٺاهي.
حالتڪڏهن
400خانو موجود ناهي، user_id 128 اکرن کان مٿي، يا ان ۾ ڪنٽرول اکر. ڪٽڻ بدران رد ڪريون ٿا — خاموشي سان مختصر ڪيل ID، CRM ۾ ڪجهه نٿو ملائي ۽ اڃا ڪاميابي لڳي ٿو.
404سيشن موجود ناهي يا توهان جي ڪم جي جاءِ جو ناهي. ٻنهي لاءِ ڄاڻي واڻي ساڳيو جواب.
403ڪم جي جاءِ جي پلان ۾ API شامل ناهي.

6. Webhook: صحي جي تصديق

Webhook هر پروجيڪٽ لاءِ هن هيٺ ترتيب ڏجن ٿا ڳانڍاپا، جتي صحي وارو secret به ملي ٿو. هر ترسيل هي header کڻي ٿي:

Headerمطلب
X-MousePlayer-Eventواقعي جو نالو، مثال طور session_identified
X-MousePlayer-TimestampUnix سيڪنڊ — صحيح ٿيل متن جو حصو
X-MousePlayer-Attemptپهرين ڪوشش تي 1، ٻيهر ڪوششن تي وڌيڪ
X-MousePlayer-Signaturesha256=<hex>

صحي HMAC-SHA256 آهي، هن تي timestamp + "." + raw body، توهان جي پروجيڪٽ جي صحي واري secret سان.

// 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');
صحي ڪريو هن تي خام Body، ڪنهن JSON parsing کان اڳ. ٻيهر JSON ٺاهڻ key ترتيب ۽ خالي جايون بدلائي ٿو، ۽ صحي ڪڏهن نه ملندي. ڪجهه منٽن کان پراڻي timestamp واري هر شيءِ به رد ڪريو — وقت رکڻ ان لاءِ آهي.

ترسيل ۽ ٻيهر ڪوششون

ناڪام ترسيل جي ٻيهر ڪوشش ٿيندي آهي هن کان پوءِ 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هون percentile)، مقرر عدد نه، ۽ گهٽ ۾ گهٽ 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 نشان جو نالو ٻڌائي ٿو — هر ورزن لاءِ ساڳيو، ته وري خراب ٿيندڙ نئون selector کليل واقعي ۾ ڳنڍجي. هي کڻي ٿو 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_detectedFront-end استثنا تي
ceپنهنجن واقعن لاءِ گڏيل رڪنيت. اها نه ٿي شامل ڪري مٿيان واقعا — انهن جا پنهنجا سوئچ آهن.

7. غلطيون & Status Code

حالتمطلب
200ڪاميابي.
401غير موجود، غلط صورت يا واپس ورتل API key.
404گهربل پروجيڪٽ يا سيشن موجود ناهي، يا توهان جي ڪم جي جاءِ جو ناهي.
429درخواستن جي حد ٽپي وئي — هن key سان هر منٽ 60 کان وڌيڪ درخواستون موڪليو ٿا.
403ڪم جي جاءِ جي پلان ۾ REST API شامل ناهي. پيغام گهربل ۽ موجوده پلان ٻنهي جا نالا ٻڌائي ٿو.

8. سيڪيورٽي نوٽ

  • رڳو پڙهڻ واري key (mp_ro_) ڪجهه نٿي بدلائي سگهي. لکڻ واري key (mp_rw_) رڳو گراهڪ ID ڳنڍي سگهي ٿي؛ ڪا key ڊيٽا ختم يا خام ٻيهر پلے ڊيٽا ايڪسپورٽ نٿي ڪري سگهي.
  • هر درخواست پاڻمرادو key جي پنهنجي ڪم جي جاءِ تائين محدود آهي — ٻي ڪم جي جاءِ جو ID ڏئي ڪنهن جي ڊيٽا ڏسڻ جو رستو ناهي.
  • ڪنهن به وقت هتان key واپس وٺو /api-keys؛ واپس وٺڻ فوري لاڳو ٿئي ٿو.
  • API key کي پاس ورڊ وانگر رکو. اتفاق سان عوامي 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 array ۽ params map موجود رهن ٿا. 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 key لاءِ هر منٽ 60 تصديق ٿيل درخواستون رهي ٿي. ختم ٿيڻ تي 429، Retry-After: 60 سان موٽائي ٿو. Redis يا limiter موجود نه هجي ته درخواستون 503، Retry-After: 5 سان موٽن ٿيون؛ بنا حد ڪڏهن قبول نٿيون ٿين. Retry-After مڃي بي ترتيب انتظار وڌايو؛ تيز لڳاتار ٻيهر ڪوشش نه ڪريو. واقعي جي ڊيٽابيس جي ناڪامي به 503 موٽائي ٿي. Cursor تصوير منجمد نٿا ڪن: پراڻين timestamp سان ساڳئي وقت وڌايل داخلائن لاءِ نئون scan گهربل ٿي سگهي ٿو.

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 وارو backend ڪنٽرول رستو آهي. پروڊڪشن ۾ بند رهي ٿو. Backend Bearer key کي list/replay لاءِ پڙهڻ ۽ register/grant/delete/disable لاءِ لکڻ جو دائرو گهرجي. اضافي native-preview موجودگي جاچون لاڳو آهن. موبائل ايپ ۾ مستقل ڪم جي جاءِ API key ڪڏهن شامل نه ڪريو.