JavaScript API

mp.js 向您自己的代码提供的全部功能:同意、客户 ID、自定义事件、不改变地址的步骤、钩子和 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. 您的客户 ID

通过自己的 ID,同一人的全部设备会在列表中合为一个访客,您也可用已知编号搜索支持请求。该 ID 还会应用于同一浏览器最近 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 就会显示此 ID。

读取 ID

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. 自定义事件

发送的事件出现在回放时间线中,可作为目标与漏斗步骤,并传至 Webhook 及已连接工具。参数是短值:数字、最多 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() 返回带此浏览器 ID 的现成链接;若不存在则返回 null,因为未同意就不会录制任何内容。

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