JavaScript API

Mọi thứ mp.js cung cấp cho mã của bạn: sự đồng ý, ID khách hàng riêng, sự kiện tùy chỉnh, bước không đổi địa chỉ, hook và thuộc tính HTML. Không có gì ở đây là bắt buộc - chỉ đoạn mã đã đủ để ghi.

1. Hai cách gọi

mp.js tải bất đồng bộ. Mã chạy trước khi tải xong đưa lệnh gọi vào hàng đợi window.mp_q; mp.js xử lý ngay khi có mặt. Sau đó các hàm tương tự có sẵn trên 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);

Luôn viết window.mp_q = window.mp_q || [], không bao giờ viết window.mp_q = []. mp.js tiếp tục lắng nghe trên mảng đó - mảng mới sẽ làm mất mọi lệnh gọi sau, kể cả rút lại sự đồng ý.

Đoạn mã cài đặt còn định nghĩa hàm tạm mp(...) để đưa vào hàng đợi theo cùng cách. Cả hai dạng nhận cùng các lệnh: consent, set, event, step, get, on và off.

2. Sự đồng ý

Không có sự đồng ý thì không ghi gì. Nếu công cụ quản lý sự đồng ý được MousePlayer nhận diện, bạn không cần phần này; nếu không, hãy tự truyền quyết định.

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'

Rút lại sự đồng ý có hiệu lực ngay trên trang: gỡ trình lắng nghe, bỏ dữ liệu đệm, đóng kết nối. Xem MousePlayer và sự đồng ý.

3. ID khách hàng của bạn

Với ID riêng, mọi thiết bị của một người trở thành một khách trong danh sách và bạn có thể tìm trường hợp hỗ trợ bằng mã đã biết. ID cũng áp dụng cho các lượt truy cập trước của cùng trình duyệt trong 30 ngày qua.

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

Dùng mã nội bộ, không dùng email hay tên. MousePlayer hiển thị ID ở mọi nơi khách xuất hiện.

Đọc lại 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. Sự kiện tùy chỉnh

Sự kiện bạn gửi xuất hiện trên dòng thời gian phát lại, có thể là mục tiêu và bước phễu, được chuyển đến webhook và công cụ kết nối. Tham số là giá trị ngắn: số, chuỗi tối đa 255 ký tự, khóa tối đa 64 ký tự.

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' }]);
  • Tên: chữ thường với dấu gạch dưới, tối đa 128 ký tự. Dùng cùng tên cho cùng nội dung ở mọi nơi - mục tiêu đối chiếu tên chính xác.
  • Không đưa dữ liệu cá nhân vào tham số. Chúng được lưu và hiển thị như mọi sự kiện khác.

5. Bước không đổi địa chỉ

Bước thanh toán hoặc trình hướng dẫn đổi màn hình nhưng không đổi địa chỉ được MousePlayer coi là một trang. step() biến mỗi màn hình thành lượt xem trang riêng - với ảnh chụp, hàng bản đồ nhiệt và bước phễu riêng.

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

Tên dài 1 đến 40 ký tự từ a-z, 0-9, _ và -; khoảng trắng thành dấu gạch nối, mọi thứ khác bị từ chối kèm cảnh báo trong bảng điều khiển. Điều hướng thực kết thúc bước.

6. Ngữ cảnh sản phẩm

Trên trang sản phẩm, cho MousePlayer biết nội dung đang được xem. Chỉ các khóa này được chấp nhận; mọi thứ khác bị bỏ để dữ liệu khách hàng không vô tình lọt vào.

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

Mã của bạn có thể phản ứng với những gì MousePlayer đo trên trang. Đăng ký qua hàng đợi nếu hook không được bỏ lỡ thời điểm đầu tiên.

// 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);
TênKhi nàoTrường
exit_riskmô hình rời đi đã chấm điểm lượt xem trang đầu (một lần mỗi lượt truy cập)risk, reasons, session
churn_riskkhách quay lại được đánh dấu có khả năng không quay lạirisk, reasons, session
offer_shownưu đãi khi rời trang được hiển thịart, risk, grund, session
offer_clicknút của ưu đãi được nhấpart, risk, grund, session, fehler
offer_dismissưu đãi được đóngart, risk, grund, session
survey_shownkhảo sát mởsurvey, trigger, session
survey_answerkhách trả lờisurvey, type, value, option, sentiment, session
survey_textvăn bản bổ sung được gửi (đã lọc)survey, text, session
survey_dismisskhảo sát đóng mà không có câu trả lờisurvey, step, session

Khi cầu nối GTM bật, cùng các sự kiện được đưa vào dataLayer (mp_exit_risk và tương tự). MousePlayer.exitRisk() trả nguy cơ rời đi hiện tại hoặc null nếu chưa biết.

8. Thuộc tính 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 (hoặc lớp mp-masked): văn bản và dữ liệu nhập trong phần tử được thay trước khi rời trình duyệt - trong ảnh chụp, thay đổi và mô tả lượt nhấp.
  • data-mp-ignore (hoặc mp-ignore) trên trường biểu mẫu: giá trị hoàn toàn không được ghi.
  • data-mp-role: một trong 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. Giá trị khác bị bỏ qua.

9. Loại trừ lượt truy cập của bạn

Mở trang một lần với ?mp_exclude=1 và trình duyệt này không còn được ghi; ?mp_exclude=0 hoàn tác việc đó. Với cả mạng văn phòng, thay vào đó nhập địa chỉ IP trong cài đặt dự án.

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. Liên kết cho chính sách quyền riêng tư

Khách có thể xem và xóa dữ liệu được ghi về họ. privacyUrl() trả liên kết sẵn có kèm ID trình duyệt này - hoặc null nếu không có vì không có sự đồng ý thì không ghi gì.

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