عام API او 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 د دې پلانونو برخه دی: سوداګریز او د لویو سوداګریو . پلان د دې له مخې اخیستل کېږي: مالک د کاري چاپېریال، نو رابلل شوي غړي یې په میراث اخلي. کتنه چلېږي په هره غوښتنه، نه یوازې د کیلي د جوړېدو پر مهال — که کاري چاپېریال ټیټ پلان ته ولاړ شي، شته کیليانې کار بندوي او دا بېرته ورکوي: 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 پورې صحیح عدد وټاکئ. pagination.next_cursor د بلې غوښتنې په 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 د مخکتنې لپاره یوازې د پراختیا د شالید د کنټرول لاره ده. په تولید کې بنده پاتې کېږي. د شالید Bearer کیليانې د list/replay لپاره د لوستلو ساحې او د register/grant/delete/disable لپاره د لیکلو ساحې ته اړتیا لري. د اصلي مخکتنې د شتون اضافي کتنې پلي کېږي. هېڅکله د کاري چاپېریال دایمي API کیليانې په موبایل اېپ کې مه نښلوئ.

څنګه مرسته کولای شو؟