API JavaScript - MousePlayer

1. Deux façons de l’appeler

mp.js se charge de manière asynchrone. Le code exécuté avant son chargement place ses appels dans la file window.mp_q ; mp.js la traite dès qu’il est disponible. Ensuite, les mêmes fonctions sont accessibles sur 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);

Écrivez toujours window.mp_q = window.mp_q || [], jamais window.mp_q = []. mp.js continue d’écouter ce tableau : un nouveau tableau absorberait tous les appels ultérieurs, y compris un retrait de consentement.

L’extrait de code d’installation définit aussi une fonction provisoire mp(...) qui utilise la même mise en file. Les deux formes acceptent les mêmes commandes : consent, set, event, step, get, on et off.

2. Consentement

Sans consentement, rien n’est enregistré. Si votre outil de consentement est reconnu par MousePlayer, vous n’avez rien à faire ici ; sinon, transmettez vous-même la décision.

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'

Un retrait s’applique immédiatement sur la page : les écouteurs sont supprimés, les données en mémoire tampon sont effacées et la connexion est fermée. Voir MousePlayer et le consentement.

3. Votre identifiant client

Avec votre propre identifiant, tous les appareils d’une personne deviennent un seul visiteur dans les listes, et vous pouvez rechercher une demande d’assistance à partir du numéro que vous connaissez. L’identifiant est aussi appliqué aux visites précédentes du même navigateur sur les 30 derniers jours.

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

Utilisez un numéro interne, pas une adresse e-mail ni un nom. MousePlayer affiche l’identifiant partout où le visiteur apparaît.

Récupérer les identifiants

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. Événements personnalisés

Les événements que vous envoyez apparaissent dans la chronologie de la relecture, peuvent servir d’objectifs et d’étapes d’entonnoir et sont transmis à vos webhooks et outils connectés. Les paramètres sont des valeurs courtes : nombres, chaînes de 255 caractères au maximum et clés de 64 caractères au maximum.

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

Noms : minuscules et traits de soulignement, au plus 128 caractères. Utilisez partout le même nom pour une même action : un objectif exige une correspondance exacte.
Ne placez pas de données personnelles dans les paramètres. Ils sont stockés et affichés comme tout autre événement.

5. Étapes sans changement d’adresse

Un paiement ou un assistant qui change d’écran sans changer d’adresse représente une seule page pour MousePlayer. step() fait de chaque écran une page vue distincte, avec sa propre capture, sa ligne dans la carte de chaleur et son étape d’entonnoir.

// 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 nom comporte de 1 à 40 caractères parmi a-z, 0-9, _ et - ; les espaces deviennent des traits d’union, tout autre caractère est refusé avec un avertissement dans la console. Une véritable navigation termine l’étape.

6. Contexte produit

Sur une page produit, indiquez à MousePlayer ce qui est consulté. Seules ces clés sont acceptées ; le reste est ignoré pour éviter toute inclusion accidentelle de données clients.

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

Votre code peut réagir aux mesures de MousePlayer sur la page. Inscrivez le hook via la file s’il ne doit pas manquer le tout premier instant.

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

Nom	Quand	Champs
`exit_risk`	le modèle de sortie a évalué la première page vue (une fois par visite)	`risk, reasons, session`
`churn_risk`	un visiteur récurrent est considéré comme susceptible d’être perdu	`risk, reasons, session`
`offer_shown`	l’offre de sortie est affichée	`art, risk, grund, session`
`offer_click`	son bouton est cliqué	`art, risk, grund, session, fehler`
`offer_dismiss`	elle est fermée	`art, risk, grund, session`
`survey_shown`	un sondage s’ouvre	`survey, trigger, session`
`survey_answer`	le visiteur répond	`survey, type, value, option, sentiment, session`
`survey_text`	le texte de suivi est envoyé (déjà filtré)	`survey, text, session`
`survey_dismiss`	le sondage est fermé sans réponse	`survey, step, session`

Lorsque la passerelle GTM est activée, les mêmes événements sont aussi envoyés dans le dataLayer (mp_exit_risk et ainsi de suite). MousePlayer.exitRisk() renvoie le risque de sortie actuel, ou null avant qu’il ne soit connu.

8. Attributs 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 (ou la classe mp-masked) : le texte et les saisies dans l’élément sont remplacés avant de quitter le navigateur, dans la capture, les modifications et les descriptions de clics.
data-mp-ignore (ou mp-ignore) sur un champ de formulaire : sa valeur n’est pas enregistrée du tout.
data-mp-role : l’une des valeurs 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. Les autres valeurs sont ignorées.

9. Exclure vos propres visites

Ouvrez une fois votre site avec ?mp_exclude=1 pour que ce navigateur ne soit plus enregistré ; ?mp_exclude=0 annule ce réglage. Pour tout un réseau de bureau, saisissez plutôt les adresses IP dans les paramètres du projet.

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

10. Un lien pour votre politique de confidentialité

Les visiteurs peuvent consulter et supprimer ce qui a été enregistré à leur sujet. privacyUrl() renvoie le lien prêt à l’emploi avec l’identifiant de ce navigateur, ou null s’il n’en a pas, car sans consentement rien n’a été enregistré.

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

Comment pouvons-nous vous aider ?