API JavaScript

Semua yang disediakan mp.js untuk kode Anda sendiri: persetujuan, ID pelanggan, peristiwa kustom, langkah tanpa perubahan alamat, hook, dan atribut HTML. Tidak ada yang wajib di sini — cuplikan kode saja sudah merekam.

1. Dua Cara Memanggilnya

mp.js dimuat secara asinkron. Kode yang berjalan sebelum pemuatan selesai memasukkan pemanggilannya ke antrean window.mp_q; mp.js memprosesnya segera setelah tersedia. Sesudahnya, fungsi yang sama tersedia pada 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);

Selalu tulis window.mp_q = window.mp_q || [], jangan pernah window.mp_q = []. mp.js terus memantau array itu — array baru akan menelan setiap pemanggilan berikutnya, termasuk penarikan persetujuan.

Cuplikan kode pemasangan juga mendefinisikan stub mp(...) yang mengantre dengan cara sama. Kedua bentuk menerima perintah yang sama: consent, set, event, step, get, on dan off.

2. Persetujuan

Tanpa persetujuan, tidak ada yang direkam. Jika alat persetujuan Anda dikenali MousePlayer, Anda tidak memerlukan semua ini; jika tidak, teruskan sendiri keputusannya.

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'

Penarikan langsung berlaku pada halaman: listener dihapus, data dalam buffer dibuang, koneksi ditutup. Lihat MousePlayer dan persetujuan.

3. ID Pelanggan Anda

Dengan ID sendiri, semua perangkat milik satu orang menjadi satu pengunjung dalam daftar, dan Anda dapat mencari kasus dukungan dengan nomor yang dikenal. ID juga diterapkan pada kunjungan sebelumnya dari browser yang sama selama 30 hari terakhir.

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

Gunakan nomor internal, bukan alamat email atau nama. MousePlayer menampilkan ID di mana pun pengunjung muncul.

Membaca Kembali 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. Peristiwa Kustom

Peristiwa yang Anda kirim muncul pada linimasa pemutaran ulang, dapat menjadi sasaran dan langkah funnel, serta diteruskan ke webhook dan alat terhubung Anda. Parameter berupa nilai singkat: angka, string hingga 255 karakter, kunci hingga 64 karakter.

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' }]);
  • Nama: huruf kecil dengan garis bawah, maksimum 128 karakter. Gunakan nama yang sama untuk hal yang sama di mana pun — sasaran mencocokkan nama secara tepat.
  • Jangan masukkan data pribadi ke parameter. Disimpan dan ditampilkan seperti peristiwa lainnya.

5. Langkah Tanpa Perubahan Alamat

Checkout atau panduan bertahap yang mengubah layar tetapi tidak alamat merupakan satu halaman bagi MousePlayer. step() menjadikan setiap layar tampilan halaman tersendiri — dengan snapshot, baris peta panas, dan langkah funnel sendiri.

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

Nama terdiri dari 1 hingga 40 karakter a-z, 0-9, _ dan -; spasi menjadi tanda hubung, selain itu ditolak dengan peringatan di konsol. Navigasi nyata mengakhiri langkah.

6. Konteks Produk

Pada halaman produk, beri tahu MousePlayer apa yang sedang dilihat. Hanya kunci ini yang diterima; semua yang lain dibuang agar data pelanggan tidak masuk tanpa sengaja.

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

Kode Anda dapat bereaksi terhadap apa yang diukur MousePlayer pada halaman. Daftarkan melalui antrean jika hook tidak boleh melewatkan saat pertama.

// 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);
NamaKapanKolom
exit_riskmodel keluar telah menilai tampilan halaman pertama (sekali per kunjungan)risk, reasons, session
churn_riskpengunjung yang kembali ditandai berisiko tidak kembalirisk, reasons, session
offer_shownpenawaran keluar ditampilkanart, risk, grund, session
offer_clicktombolnya diklikart, risk, grund, session, fehler
offer_dismisspenawaran ditutupart, risk, grund, session
survey_shownsurvei terbukasurvey, trigger, session
survey_answerpengunjung menjawabsurvey, type, value, option, sentiment, session
survey_textteks tindak lanjut dikirim (sudah difilter)survey, text, session
survey_dismisssurvei ditutup tanpa jawabansurvey, step, session

Saat jembatan GTM aktif, peristiwa yang sama juga dikirim ke dataLayer (mp_exit_risk dan seterusnya). MousePlayer.exitRisk() mengembalikan risiko keluar saat ini, atau null sebelum diketahui.

8. Atribut 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 (atau kelas mp-masked): teks dan masukan di dalam elemen diganti sebelum meninggalkan browser — dalam snapshot, perubahan, dan deskripsi klik.
  • data-mp-ignore (atau mp-ignore) pada kolom formulir: nilainya tidak direkam sama sekali.
  • data-mp-role: salah satu dari 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. Nilai lain diabaikan.

9. Mengecualikan Kunjungan Sendiri

Buka situs Anda sekali dengan ?mp_exclude=1 dan browser ini tidak lagi direkam; ?mp_exclude=0 membatalkannya. Untuk seluruh jaringan kantor, masukkan alamat IP dalam pengaturan proyek sebagai gantinya.

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. Tautan untuk Kebijakan Privasi Anda

Pengunjung dapat melihat dan menghapus apa yang direkam tentang mereka. privacyUrl() mengembalikan tautan siap pakai dengan ID browser ini — atau null jika tidak ada, karena tanpa persetujuan tidak ada yang direkam.

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