JavaScript API

كل ما يتيحه mp.js لكودك: الموافقة ومعرّف عميلك والأحداث والخطوات دون تغيير العنوان والخطافات وسمات HTML. لا شيء مطلوب هنا — المقتطف وحده يسجّل.

1. طريقتان للاستدعاء

يُحمّل mp.js بصورة غير متزامنة. يضع الكود السابق للتحميل استدعاءاته في قائمة window.mp_q؛ وينفذها mp.js عند وصوله. بعدها تتاح الوظائف نفسها على window.MousePlayer.

// Before mp.js has loaded - the queue keeps every call: (window.mp_q = window.mp_q || []).push(['consent', true]); // After mp.js has loaded - the same, directly: MousePlayer.setConsent(true);

اكتب دائمًا window.mp_q = window.mp_q || []، وليس window.mp_q = []. يواصل mp.js الاستماع للمصفوفة — الجديدة تبتلع كل استدعاء لاحق، حتى سحب الموافقة.

يعرّف مقتطف التثبيت أيضًا دالة مؤقتة mp(...) تُدرج الاستدعاءات بالطريقة نفسها. تقبل الصيغتان الأوامر نفسها: consent، set، event، step، get، on و off.

2. الموافقة

لا يُسجّل شيء دون موافقة. إن عرف MousePlayer أداتك فلا تحتاج هذا؛ وإلا مرر القرار بنفسك.

MousePlayer.setConsent(true); // the visitor agreed MousePlayer.setConsent(false); // withdrawn: recording stops on this page MousePlayer.getConsentState(); // e.g. 'WAITING', 'GRANTED', 'GRANTED_LATE', 'DENIED', 'WITHDRAWN'

يسري السحب في الصفحة فورًا: تُزال المستمعات وتُهمل البيانات المؤقتة ويُغلق الاتصال. راجع MousePlayer والموافقة.

3. معرّف عميلك

بمعرّفك تصبح أجهزة الشخص الواحد زائرًا واحدًا في القوائم، ويمكن البحث عن حالة دعم بالرقم المعروف. يُطبّق المعرّف على زيارات المتصفح السابقة من آخر 30 يومًا أيضًا.

// After login - your own customer number, not an e-mail address: MousePlayer.setUserId('customer-4711'); // or through the queue (window.mp_q = window.mp_q || []).push(['set', 'user_id', 'customer-4711']);

استخدم رقمًا داخليًا لا بريدًا أو اسمًا. يعرض MousePlayer المعرّف حيث يظهر الزائر.

قراءة المعرّفات

MousePlayer.getSessionUrl(); // replay link of the running session MousePlayer.getSessionId(); MousePlayer.getVisitorId(); // null without consent // Through the queue, with a callback: (window.mp_q = window.mp_q || []).push(['get', 'session_url', function (url) { // e.g. attach it to a support ticket }]);

4. الأحداث المخصّصة

تظهر أحداثك في خط التسجيل الزمني ويمكن أن تصبح أهدافًا وخطوات مسار وتصل إلى Webhooks والأدوات المرتبطة. المعلمات قيم قصيرة: أرقام ونصوص حتى 255 حرفًا ومفاتيح حتى 64 حرفًا.

MousePlayer.trackEvent('newsletter_signup', { source: 'footer' }); MousePlayer.trackEvent('purchase', { value: 129.90, currency: 'EUR' }); (window.mp_q = window.mp_q || []).push(['event', 'add_to_cart', { sku: 'SKU-123' }]);
  • الأسماء: أحرف صغيرة وشرطات سفلية حتى 128 حرفًا. استخدم الاسم نفسه للشيء نفسه دائمًا — يطابق الهدف الأسماء بدقة.
  • لا تضع بيانات شخصية في المعلمات. تُحفظ وتُعرض كأي حدث.

5. خطوات دون تغيير العنوان

إتمام شراء أو معالج يغيّر شاشته لا عنوانه يُعد صفحة واحدة لدى MousePlayer. step() يجعل كل شاشة مشاهدة مستقلة — بلقطة وصف خريطة حرارية وخطوة مسار خاصة بها.

// A wizard that keeps its address: MousePlayer.step('shipping'); MousePlayer.step('payment'); MousePlayer.step(''); // back to the page itself (window.mp_q = window.mp_q || []).push(['step', 'payment']);

الاسم من 1 إلى 40 حرفًا من a-z و0-9 و_ و-؛ تتحول الفراغات لشرطات ويُرفض غيرها بتحذير في وحدة التحكم. التنقل الفعلي ينهي الخطوة.

6. سياق المنتج

أخبر MousePlayer بما يُعرض في صفحة المنتج. تُقبل المفاتيح هذه فقط؛ يُهمل غيرها لمنع تسرب بيانات عميل بالخطأ.

MousePlayer.setContext({ page_type: 'product', product_id: 'SKU-123', variant_id: 'SKU-123-42', price: 89.90, currency: 'EUR', category: 'running-shoes', in_stock: true, cart_value: 0, cart_items: 0 });

7. الخطافات

يمكن لكودك الاستجابة لقياسات MousePlayer في الصفحة. سجّل عبر القائمة إن كان الخطاف يجب ألا يفوّت أول لحظة.

// Register early - exit_risk fires once, a few seconds after the visit starts: (window.mp_q = window.mp_q || []).push(['on', 'exit_risk', function (e) { console.log(e.risk, e.reasons, e.session); }]); function onAnswer(e) { /* e.survey, e.value, e.sentiment */ } MousePlayer.on('survey_answer', onAnswer); MousePlayer.off('survey_answer', onAnswer);
الاسممتىالحقول
exit_riskقيّم نموذج المغادرة أول مشاهدة (مرة لكل زيارة)risk, reasons, session
churn_riskعُلّم زائر عائد كمعرّض لعدم العودةrisk, reasons, session
offer_shownظهر عرض المغادرةart, risk, grund, session
offer_clickنُقر زرهart, risk, grund, session, fehler
offer_dismissأُغلقart, risk, grund, session
survey_shownفُتح استطلاعsurvey, trigger, session
survey_answerأجاب الزائرsurvey, type, value, option, sentiment, session
survey_textأُرسل نص المتابعة (مرشّح بالفعل)survey, text, session
survey_dismissأُغلق الاستطلاع دون إجابةsurvey, step, session

عند تفعيل جسر GTM، تدخل الأحداث نفسها dataLayer أيضًا (mp_exit_risk وهكذا). MousePlayer.exitRisk() يعيد خطر المغادرة الحالي، أو null قبل معرفته.

8. سمات HTML

<!-- Nothing typed in here leaves the browser as text --> <section data-mp-mask> ... </section> <!-- The value of this field is never recorded --> <input name="voucher" data-mp-ignore> <!-- Tell MousePlayer what an element is --> <span class="amount" data-mp-role="price">89,90 EUR</span>
  • data-mp-mask (أو الفئة mp-masked): يُستبدل النص والإدخال داخل العنصر قبل مغادرة المتصفح — في اللقطة والتغييرات وأوصاف النقر.
  • data-mp-ignore (أو mp-ignore) في حقل نموذج: لا تُسجّل قيمته مطلقًا.
  • data-mp-role: إحدى price وprice_old وcta_cart وcta_checkout وproduct_image وvariant وshipping_info وreturns_info وreviews وrating وstock وcoupon وpayment_methods وsearch وfilter وheading وarticle_body وnav وmedia وform_field وcontact_info. تُتجاهل بقية القيم.

9. استبعاد زياراتك

افتح موقعك مرة مع ?mp_exclude=1 فلا يُسجّل هذا المتصفح بعد ذلك؛ وتُلغي ?mp_exclude=0 ذلك. لشبكة مكتب كاملة أدخل عناوين IP في إعدادات المشروع بدلًا منه.

https://www.your-shop.com/?mp_exclude=1 <!-- this browser is not recorded any more --> https://www.your-shop.com/?mp_exclude=0 <!-- recorded again -->

10. رابط لسياسة الخصوصية

يستطيع الزوار عرض ما سُجّل عنهم وحذفه. privacyUrl() يعيد الرابط الجاهز بمعرّف المتصفح — أو null إن غاب، لأنه لم يُسجّل شيء دون موافقة.

var link = MousePlayer.privacyUrl(); // language from <html lang>, or e.g. privacyUrl('de') if (link) document.getElementById('my-data').href = link;