واجهة API العامة ومفاتيح API

1. نظرة عامة

تتيح MousePlayer API سحب بيانات المساحة إلى لوحاتك أو مستودعك أو أدواتك الداخلية. باستثناء إرفاق معرّفات العملاء بالجلسات (identify، يتطلب نطاق كتابة، راجع نطاقات المفاتيح)، فهي للقراءة فقط: لا تعديل أو حذف للبيانات عبر API.

URL الأساسي: https://www.mouseplayer.com/api/v1/
كل الردود JSON.
يصادق كل طلب بمفتاح API ويُقيّد تلقائيًا بمساحته — لا يرى مفتاح مساحة بيانات أخرى مطلقًا، حتى بالخطأ.
تسجيل إعادة التشغيل الكامل (حركات الفأرة ولقطات DOM) غير متاح عبر API. تحصل على بيانات وصفية ومشاهدات صفحات وأحداث مخصّصة وشرائح — لبناء التقارير دون نقل حمولة التسجيل الخام.

2. المصادقة

أنشئ مفاتيحك وأدرها تحت مفاتيح 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.

اختر النطاق عند الإنشاء؛ الافتراضي قراءة فقط. استخدام مفتاح قراءة في نقطة كتابة يعيد 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. إرفاق معرّف عميل من الخلفية

لا يعرف المتصفح غالبًا الجالس أمامه. في 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}}

يظهر المعرّف في قائمة الجلسات ويمكن البحث به، ويعمل Webhook session_identified — وهكذا يصل إلى CRM.

الاستدعاء مرتين بالمعرّف نفسه آمن. يعود الرد مع "changed": false ولا يُرسل Webhook. الطلب المكرر لا يُنشئ عميلًا محتملًا ثانيًا.

الحالة	متى
`400`	حقل مفقود أو قيمة `user_id` أطول من 128 حرفًا أو بها محارف تحكم. نرفض بدل البتر — المعرّف المختصر بصمت لا يطابق CRM ويظل يبدو نجاحًا.
`404`	الجلسة غير موجودة أو لا تتبع مساحتك. الجواب نفسه متعمد للحالتين.
`403`	لا تشمل خطة المساحة API.

6. Webhooks: التحقق من التوقيع

تُعد Webhooks لكل مشروع تحت التكاملات، حيث سر التوقيع أيضًا. تحمل كل عملية تسليم الترويسات التالية:

الترويسة	المعنى
`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`	عند حصول الجلسة على معرّف عميل أول مرة — من المتصفح أو 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` عبر 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 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 بحسب الحالة.

يبقى الحد 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 مسار تحكم خلفي لـ Dev فقط لمعاينة SDK الأصلي. يبقى معطلًا بالإنتاج. تحتاج مفاتيح Bearer الخلفية نطاق قراءة لـ list/replay وكتابة لـ register/grant/delete/disable. تنطبق فحوص توفر إضافية للمعاينة الأصلية. لا تضمّن مفاتيح API دائمة لمساحة العمل في تطبيق جوال مطلقًا.

كيف يمكننا المساعدة؟