API JavaScript

Tutto ciò che mp.js offre al suo codice: consenso, ID cliente, eventi personalizzati, passaggi senza cambio di indirizzo, hook e attributi HTML. Nulla è obbligatorio: lo snippet da solo registra.

1. Due modi per chiamarla

mp.js carica asincronicamente. Il codice eseguito prima del caricamento inserisce le chiamate nella coda window.mp_q; mp.js la elabora appena disponibile. Dopo, le stesse funzioni sono accessibili su 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);

Scriva sempre window.mp_q = window.mp_q || [], mai window.mp_q = []. mp.js continua ad ascoltare quell’array: uno nuovo assorbirebbe tutte le chiamate successive, inclusa la revoca del consenso.

Lo snippet di installazione definisce anche una funzione provvisoria mp(...) che accoda allo stesso modo. Entrambe le forme accettano gli stessi comandi: consent, set, event, step, get, on e off.

2. Consenso

Senza consenso non viene registrato nulla. Se lo strumento di consenso è riconosciuto da MousePlayer non serve altro; altrimenti trasmetta la decisione direttamente.

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'

La revoca si applica subito sulla pagina: i listener vengono rimossi, i dati nel buffer scartati e la connessione chiusa. Vedere MousePlayer e il consenso.

3. Il suo ID cliente

Con un ID proprio, tutti i dispositivi di una persona diventano un visitatore negli elenchi e può cercare un caso di assistenza con il numero noto. L’ID viene applicato anche alle visite precedenti dello stesso browser negli ultimi 30 giorni.

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

Usi un numero interno, non un’e-mail o un nome. MousePlayer mostra l’ID ovunque compaia il visitatore.

Recuperare gli 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. Eventi personalizzati

Gli eventi inviati appaiono nella timeline, possono essere obiettivi e passaggi di funnel e raggiungono webhook e strumenti collegati. I parametri sono valori brevi: numeri, stringhe fino a 255 caratteri e chiavi fino a 64 caratteri.

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' }]);
  • Nomi: minuscole e trattini bassi, massimo 128 caratteri. Usi lo stesso nome per la stessa cosa ovunque: un obiettivo cerca nomi esatti.
  • Non inserisca dati personali nei parametri. Vengono conservati e mostrati come qualsiasi altro evento.

5. Passaggi senza cambio di indirizzo

Un checkout o una procedura guidata che cambia schermata ma non indirizzo è una sola pagina per MousePlayer. step() rende ogni schermata una visualizzazione di pagina autonoma, con istantanea, riga nella mappa di calore e passaggio di funnel propri.

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

Il nome contiene da 1 a 40 caratteri tra a-z, 0-9, _ e -; gli spazi diventano trattini, gli altri caratteri sono rifiutati con un avviso in console. Una navigazione reale termina il passaggio.

6. Contesto del prodotto

Su una pagina prodotto, indichi cosa viene guardato. Sono accettate solo queste chiavi; tutto il resto è scartato per evitare dati cliente accidentali.

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

Il suo codice può reagire alle misure di MousePlayer sulla pagina. Registri tramite coda se l’hook non deve perdere il primo istante.

// 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);
NomeQuandoCampi
exit_riskil modello di uscita ha valutato la prima visualizzazione (una volta per visita)risk, reasons, session
churn_riskun visitatore di ritorno è indicato a rischio di abbandonorisk, reasons, session
offer_shownviene mostrata l’offerta di uscitaart, risk, grund, session
offer_clicksi fa clic sul suo pulsanteart, risk, grund, session, fehler
offer_dismissviene chiusaart, risk, grund, session
survey_shownsi apre un sondaggiosurvey, trigger, session
survey_answeril visitatore rispondesurvey, type, value, option, sentiment, session
survey_textviene inviato il testo successivo (già filtrato)survey, text, session
survey_dismissil sondaggio viene chiuso senza rispostasurvey, step, session

Con il connettore GTM attivo, gli stessi eventi vanno anche nel dataLayer (mp_exit_risk e così via). MousePlayer.exitRisk() restituisce il rischio di uscita attuale, oppure null finché non è noto.

8. Attributi 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 (o la classe mp-masked): testo e input nell’elemento vengono sostituiti prima di lasciare il browser, nell’istantanea, nelle modifiche e nelle descrizioni dei clic.
  • data-mp-ignore (oppure mp-ignore) su un campo di modulo: il valore non viene registrato affatto.
  • data-mp-role: uno tra 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. Gli altri valori vengono ignorati.

9. Escludere le proprie visite

Apra il sito una volta con ?mp_exclude=1 e quel browser non verrà più registrato; ?mp_exclude=0 annulla la scelta. Per tutta la rete dell’ufficio inserisca invece gli indirizzi IP nelle impostazioni del progetto.

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. Un link per l’informativa sulla privacy

I visitatori possono vedere ed eliminare ciò che è stato registrato su di loro. privacyUrl() restituisce il link pronto con l’ID del browser, oppure null se manca, perché senza consenso non è stato registrato nulla.

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