JavaScript API

Everything mp.js offers your own code: consent, your customer ID, custom events, steps without an address change, hooks and HTML attributes. Nothing here is required - the snippet alone records.

1. Two ways to call it

mp.js loads asynchronously. Code that runs before it has loaded puts its calls into the queue window.mp_q; mp.js works through it as soon as it is there. Afterwards the same functions are available on 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);

Always write window.mp_q = window.mp_q || [], never window.mp_q = []. mp.js keeps listening on that array - a new one would swallow every later call, including a withdrawal of consent.

The installation snippet also defines a stub mp(...) that queues the same way. Both forms take the same commands: consent, set, event, step, get, on and off.

2. Consent

Without consent nothing is recorded. If your consent tool is one MousePlayer recognises, you do not need any of this; otherwise pass the decision on yourself.

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'

A withdrawal takes effect on the page immediately: listeners are removed, buffered data is discarded, the connection is closed. See MousePlayer and consent.

3. Your customer ID

With an ID of your own, all devices of one person become one visitor in the lists, and you can search for a support case by the number you know. The ID is also applied to earlier visits of the same browser from the last 30 days.

// 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']);

Use an internal number, not an e-mail address or a name. MousePlayer shows the ID wherever the visitor appears.

Reading IDs back

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. Custom events

Events you send appear in the timeline of the replay, can be goals and funnel steps, and go to your webhooks and connected tools. Parameters are short values: numbers, strings up to 255 characters, keys up to 64 characters.

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' }]);
  • Names: lower case with underscores, at most 128 characters. Use the same name for the same thing everywhere - a goal matches names exactly.
  • Do not put personal data into parameters. They are stored and shown like any other event.

5. Steps without an address change

A checkout or wizard that changes its screen but not its address is one page to MousePlayer. step() makes each screen a page view of its own - with its own snapshot, heatmap row and funnel 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']);

A name is 1 to 40 characters from a-z, 0-9, _ and -; spaces become hyphens, anything else is rejected with a warning in the console. A real navigation ends the step.

6. Product context

On a product page, tell MousePlayer what is being looked at. Only these keys are accepted; everything else is discarded so that no customer data slips in by accident.

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

Your code can react to what MousePlayer measures on the page. Register through the queue if the hook must not miss the first moment.

// 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);
NameWhenFields
exit_riskthe exit model has scored the first page view (once per visit)risk, reasons, session
churn_riska returning visitor is marked as likely to churnrisk, reasons, session
offer_shownthe exit offer is shownart, risk, grund, session
offer_clickits button is clickedart, risk, grund, session, fehler
offer_dismissit is closedart, risk, grund, session
survey_showna survey openssurvey, trigger, session
survey_answerthe visitor answerssurvey, type, value, option, sentiment, session
survey_textthe follow-up text is sent (already filtered)survey, text, session
survey_dismissthe survey is closed without an answersurvey, step, session

When the GTM bridge is on, the same events also go into the dataLayer (mp_exit_risk and so on). MousePlayer.exitRisk() returns the current exit risk, or null before it is known.

8. HTML attributes

<!-- 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 (or the class mp-masked): text and input inside the element are replaced before they leave the browser - in the snapshot, in changes and in click descriptions.
  • data-mp-ignore (or mp-ignore) on a form field: its value is not recorded at all.
  • data-mp-role: one of 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. Other values are ignored.

9. Excluding your own visits

Open your site once with ?mp_exclude=1 and this browser is not recorded any more; ?mp_exclude=0 undoes it. For a whole office network, enter the IP addresses in the project settings instead.

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. A link for your privacy policy

Visitors can see and delete what was recorded about them. privacyUrl() returns the ready link with this browser's ID - or null if there is none, because without consent nothing was recorded.

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