API JavaScript - MousePlayer

1. Două moduri de apelare

mp.js se încarcă asincron. Codul care rulează înainte de încărcare își adaugă apelurile în coada window.mp_q; mp.js le procesează imediat ce este disponibil. Ulterior, aceleași funcții sunt disponibile î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);

Scrieți întotdeauna window.mp_q = window.mp_q || [], niciodată window.mp_q = []. mp.js continuă să asculte acea listă — una nouă ar înghiți toate apelurile ulterioare, inclusiv retragerea consimțământului.

Fragmentul de instalare definește și o funcție provizorie mp(...) care adaugă apelurile în coadă în același mod. Ambele forme acceptă aceleași comenzi: consent, set, event, step, get, on și off.

2. Consimțământ

Fără consimțământ nu se înregistrează nimic. Dacă instrumentul dvs. de consimțământ este recunoscut de MousePlayer, nu aveți nevoie de nimic din această secțiune; altfel, transmiteți dvs. decizia.

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'

Retragerea intră în vigoare imediat pe pagină: ascultătorii sunt eliminați, datele din buffer sunt șterse, conexiunea este închisă. Consultați MousePlayer și consimțământul.

3. ID-ul dvs. de client

Cu un ID propriu, toate dispozitivele unei persoane devin un singur vizitator în liste și puteți căuta un caz de asistență după numărul cunoscut. ID-ul se aplică și vizitelor anterioare din același browser din ultimele 30 de zile.

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

Folosiți un număr intern, nu o adresă de e-mail sau un nume. MousePlayer afișează ID-ul oriunde apare vizitatorul.

Citirea ID-urilor

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. Evenimente personalizate

Evenimentele pe care le trimiteți apar în cronologia redării, pot fi obiective și pași de pâlnie și ajung la webhookurile și instrumentele conectate. Parametrii sunt valori scurte: numere, șiruri de cel mult 255 de caractere, chei de cel mult 64 de caractere.

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

Nume: litere mici cu liniuțe de subliniere, cel mult 128 de caractere. Folosiți peste tot același nume pentru același lucru — un obiectiv compară exact numele.
Nu includeți date cu caracter personal în parametri. Aceștia sunt stocați și afișați ca orice alt eveniment.

5. Pași fără schimbarea adresei

Un proces de finalizare a comenzii sau un asistent care își schimbă ecranul, dar nu și adresa reprezintă o singură pagină pentru MousePlayer. step() transformă fiecare ecran într-o vizualizare de pagină separată — cu propria captură, propriul rând în harta termică și propriul pas de pâlnie.

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

Un nume conține între 1 și 40 de caractere din a-z, 0-9, _ și -; spațiile devin cratime, iar orice alt caracter este respins cu un avertisment în consolă. O navigare reală încheie pasul.

6. Contextul produsului

Pe o pagină de produs, spuneți-i MousePlayer ce este vizualizat. Sunt acceptate doar aceste chei; toate celelalte sunt eliminate, astfel încât datele clienților să nu fie incluse accidental.

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

Codul dvs. poate reacționa la ceea ce măsoară MousePlayer pe pagină. Înregistrați hookul prin coadă dacă nu trebuie să rateze primul 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);

Nume	Când	Câmpuri
`exit_risk`	modelul de ieșire a evaluat prima vizualizare de pagină (o dată pe vizită)	`risk, reasons, session`
`churn_risk`	un vizitator care revine este marcat ca având risc de pierdere	`risk, reasons, session`
`offer_shown`	oferta de ieșire este afișată	`art, risk, grund, session`
`offer_click`	butonul ei este apăsat	`art, risk, grund, session, fehler`
`offer_dismiss`	oferta este închisă	`art, risk, grund, session`
`survey_shown`	se deschide un sondaj	`survey, trigger, session`
`survey_answer`	vizitatorul răspunde	`survey, type, value, option, sentiment, session`
`survey_text`	este trimis textul suplimentar (deja filtrat)	`survey, text, session`
`survey_dismiss`	sondajul este închis fără răspuns	`survey, step, session`

Când puntea GTM este activată, aceleași evenimente ajung și în dataLayer (mp_exit_risk și așa mai departe). MousePlayer.exitRisk() returnează riscul de ieșire curent sau null înainte de a fi cunoscut.

8. Atribute HTML

<section data-mp-mask> ... </section>  <input name="voucher" data-mp-ignore>  <span class="amount" data-mp-role="price">89,90 EUR</span>

data-mp-mask (sau clasa mp-masked): textul și datele introduse în interiorul elementului sunt înlocuite înainte de a părăsi browserul — în captură, în modificări și în descrierile clicurilor.
data-mp-ignore (sau mp-ignore) pe un câmp de formular: valoarea sa nu este înregistrată deloc.
data-mp-role: una dintre valorile 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. Alte valori sunt ignorate.

9. Excluderea propriilor vizite

Deschideți site-ul o dată cu ?mp_exclude=1 și acest browser nu va mai fi înregistrat; ?mp_exclude=0 anulează excluderea. Pentru întreaga rețea a unui birou, introduceți în schimb adresele IP în setările proiectului.

https://www.your-shop.com/?mp_exclude=1  https://www.your-shop.com/?mp_exclude=0

10. Un link pentru politica de confidențialitate

Vizitatorii pot vedea și șterge ce s-a înregistrat despre ei. privacyUrl() returnează linkul gata de folosit cu ID-ul acestui browser — sau null dacă nu există unul, deoarece fără consimțământ nu s-a înregistrat nimic.

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

Cum vă putem ajuta?