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. Власні події

Надіслані події з’являються на часовій шкалі відтворення, можуть бути цілями й кроками воронки та надходять до вебхуків і підключених інструментів. Параметри — короткі значення: числа, рядки до 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;