JavaScript-API

Alles, was mp.js Ihrem eigenen Code anbietet: Einwilligung, Ihre Kundenkennung, eigene Ereignisse, Schritte ohne Adresswechsel, Haken und HTML-Attribute. Nichts davon ist Pflicht – das Snippet allein zeichnet auf.

1. Zwei Wege, sie aufzurufen

mp.js lädt asynchron. Code, der vorher läuft, legt seine Aufrufe in die Warteschlange window.mp_q; mp.js arbeitet sie ab, sobald es da ist. Danach stehen dieselben Funktionen unter window.MousePlayer bereit.

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

Schreiben Sie immer window.mp_q = window.mp_q || [], nie window.mp_q = []. mp.js hört weiter auf dieses Array – ein neues würde jeden späteren Aufruf verschlucken, auch einen Widerruf der Einwilligung.

Das Installations-Snippet legt außerdem einen Platzhalter mp(...) an, der genauso puffert. Beide Formen kennen dieselben Befehle: consent, set, event, step, get, on und off.

2. Einwilligung

Ohne Einwilligung wird nichts aufgezeichnet. Erkennt MousePlayer Ihr Einwilligungswerkzeug, brauchen Sie nichts davon; sonst geben Sie die Entscheidung selbst weiter.

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'

Ein Widerruf wirkt auf der Seite sofort: Hörer werden entfernt, gepufferte Daten verworfen, die Verbindung geschlossen. Siehe MousePlayer und Einwilligung.

3. Ihre Kundenkennung

Mit einer eigenen Kennung werden alle Geräte eines Menschen in den Listen zu einem Besucher, und Sie finden einen Supportfall über die Nummer, die Sie kennen. Die Kennung gilt auch für frühere Besuche desselben Browsers aus den letzten 30 Tagen.

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

Nehmen Sie eine interne Nummer, keine E-Mail-Adresse und keinen Namen. MousePlayer zeigt die Kennung überall dort, wo der Besucher erscheint.

Kennungen zurücklesen

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. Eigene Ereignisse

Ereignisse, die Sie senden, stehen in der Zeitleiste der Wiedergabe, können Ziele und Trichterstufen sein und gehen an Ihre Webhooks und angebundenen Werkzeuge. Parameter sind kurze Werte: Zahlen, Zeichenketten bis 255 Zeichen, Schlüssel bis 64 Zeichen.

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' }]);
  • Namen: klein geschrieben mit Unterstrichen, höchstens 128 Zeichen. Nehmen Sie für dasselbe überall denselben Namen – ein Ziel vergleicht Namen genau.
  • Keine personenbezogenen Daten in Parameter. Sie werden gespeichert und angezeigt wie jedes andere Ereignis.

5. Schritte ohne Adresswechsel

Ein Bezahlvorgang oder Assistent, der seine Ansicht wechselt, aber nicht seine Adresse, ist für MousePlayer eine Seite. step() macht jede Ansicht zu einem eigenen Seitenaufruf – mit eigenem Abbild, eigener Heatmap-Zeile und eigener Trichterstufe.

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

Ein Name hat 1 bis 40 Zeichen aus a-z, 0-9, _ und -; Leerzeichen werden zu Bindestrichen, alles andere wird mit einer Warnung in der Konsole abgewiesen. Eine echte Navigation beendet den Schritt.

6. Produktkontext

Sagen Sie MousePlayer auf einer Produktseite, was angesehen wird. Nur diese Schlüssel werden angenommen; alles andere wird verworfen, damit keine Kundendaten versehentlich hineingeraten.

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

Ihr Code kann auf das reagieren, was MousePlayer auf der Seite misst. Registrieren Sie über die Warteschlange, wenn der Haken den ersten Augenblick nicht verpassen darf.

// 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);
NameWannFelder
exit_riskdas Absprungmodell hat den ersten Seitenaufruf bewertet (einmal je Besuch)risk, reasons, session
churn_riskein wiederkehrender Besucher gilt als abwanderungsgefährdetrisk, reasons, session
offer_showndas Exit-Angebot erscheintart, risk, grund, session
offer_clicksein Knopf wird geklicktart, risk, grund, session, fehler
offer_dismisses wird geschlossenart, risk, grund, session
survey_showneine Umfrage öffnet sichsurvey, trigger, session
survey_answerder Besucher antwortetsurvey, type, value, option, sentiment, session
survey_textder Nachfragetext wird gesendet (bereits gefiltert)survey, text, session
survey_dismissdie Umfrage wird ohne Antwort geschlossensurvey, step, session

Ist die GTM-Brücke an, gehen dieselben Ereignisse auch in den dataLayer (mp_exit_risk usw.). MousePlayer.exitRisk() liefert das aktuelle Absprungrisiko oder null, solange es noch nicht bekannt ist.

8. HTML-Attribute

<!-- 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 (oder die Klasse mp-masked): Text und Eingaben im Element werden ersetzt, bevor sie den Browser verlassen – im Abbild, in Änderungen und in Klickbeschreibungen.
  • data-mp-ignore (oder mp-ignore) an einem Formularfeld: sein Wert wird gar nicht aufgezeichnet.
  • data-mp-role: einer von 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. Andere Werte werden übergangen.

9. Eigene Besuche ausschließen

Öffnen Sie Ihre Seite einmal mit ?mp_exclude=1, und dieser Browser wird nicht mehr aufgezeichnet; ?mp_exclude=0 hebt das auf. Für ein ganzes Büronetz tragen Sie stattdessen die IP-Adressen in den Projekteinstellungen ein.

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. Ein Link für Ihre Datenschutzerklärung

Besucher können einsehen und löschen, was über sie aufgezeichnet wurde. privacyUrl() liefert den fertigen Link mit der Kennung dieses Browsers – oder null, wenn es keine gibt, denn ohne Einwilligung wurde nichts aufgezeichnet.

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