API JavaScript

همهٔ امکانات 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. رویداد اختصاصی

رویداد ارسالی در خط زمانی بازپخش می‌آید، می‌تواند هدف و مرحلهٔ قیف باشد و به وب‌هوک و ابزار متصل می‌رود. پارامتر مقدار کوتاه است: عدد، متن تا 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;