JavaScript API - MousePlayer

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. Hooks

הקוד שלך יכול להגיב למדידות MousePlayer בדף. אם ה-hook חייב לתפוס את הרגע הראשון, יש לרשום אותו דרך התור.

// 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

<section data-mp-mask> ... </section>  <input name="voucher" data-mp-ignore>  <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  https://www.your-shop.com/?mp_exclude=0

10. קישור למדיניות הפרטיות שלך

מבקרים יכולים לראות ולמחוק את מה שהוקלט עליהם. privacyUrl() מחזיר קישור מוכן עם מזהה דפדפן זה — או null אם אין מזהה, כי ללא הסכמה לא הוקלט דבר.

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

איך אפשר לעזור?