JavaScript API

Wszystko, co mp.js oferuje Twojemu kodowi: zgoda, Twój identyfikator klienta, własne zdarzenia, kroki bez zmiany adresu, haki i atrybuty HTML. Nic z tego nie jest wymagane – sam fragment kodu już nagrywa.

1. Dwa sposoby wywołania

mp.js ładuje się asynchronicznie. Kod, który działa wcześniej, wkłada wywołania do kolejki window.mp_q; mp.js przetwarza ją, gdy tylko się załaduje. Potem te same funkcje są dostępne w 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);

Zawsze pisz window.mp_q = window.mp_q || [], nigdy window.mp_q = []. mp.js dalej nasłuchuje na tej tablicy – nowa połknęłaby każde późniejsze wywołanie, także wycofanie zgody.

Fragment instalacyjny tworzy też zaślepkę mp(...), która buforuje w ten sam sposób. Obie formy znają te same polecenia: consent, set, event, step, get, on i off.

2. Zgoda

Bez zgody nic nie jest nagrywane. Jeśli MousePlayer rozpoznaje Twoje narzędzie do zgód, nie potrzebujesz niczego z tej sekcji; w przeciwnym razie przekaż decyzję samodzielnie.

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'

Wycofanie działa na stronie natychmiast: nasłuchiwacze są usuwane, zbuforowane dane odrzucane, połączenie zamykane. Zobacz MousePlayer a zgody.

3. Twój identyfikator klienta

Z własnym identyfikatorem wszystkie urządzenia jednej osoby stają się na listach jednym odwiedzającym, a zgłoszenie do supportu znajdziesz po numerze, który znasz. Identyfikator obejmuje też wcześniejsze wizyty tej samej przeglądarki z ostatnich 30 dni.

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

Używaj wewnętrznego numeru, a nie adresu e-mail ani nazwiska. MousePlayer pokazuje identyfikator wszędzie tam, gdzie pojawia się odwiedzający.

Odczytywanie identyfikatorów

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. Własne zdarzenia

Wysłane zdarzenia pojawiają się na osi czasu odtwarzania, mogą być celami i krokami lejka oraz trafiają do Twoich webhooków i podłączonych narzędzi. Parametry to krótkie wartości: liczby, ciągi do 255 znaków, klucze do 64 znaków.

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' }]);
  • Nazwy: małymi literami z podkreśleniami, najwyżej 128 znaków. Dla tej samej rzeczy używaj wszędzie tej samej nazwy – cel porównuje nazwy dokładnie.
  • Nie umieszczaj danych osobowych w parametrach. Są zapisywane i pokazywane jak każde inne zdarzenie.

5. Kroki bez zmiany adresu

Proces płatności lub kreator, który zmienia widok, ale nie adres, jest dla MousePlayera jedną stroną. step() robi z każdego widoku osobną odsłonę – z własnym zrzutem, wierszem mapy cieplnej i krokiem lejka.

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

Nazwa ma od 1 do 40 znaków spośród a-z, 0-9, _ i -; spacje stają się myślnikami, wszystko inne jest odrzucane z ostrzeżeniem w konsoli. Prawdziwa nawigacja kończy krok.

6. Kontekst produktu

Na stronie produktu powiedz MousePlayerowi, co jest oglądane. Przyjmowane są tylko te klucze; wszystko inne jest odrzucane, żeby żadne dane klientów nie trafiły tam przypadkiem.

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

Twój kod może reagować na to, co MousePlayer mierzy na stronie. Rejestruj przez kolejkę, jeśli hak nie może przegapić pierwszej chwili.

// 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);
NazwaKiedyPola
exit_riskmodel porzuceń ocenił pierwszą odsłonę (raz na wizytę)risk, reasons, session
churn_riskpowracający odwiedzający jest oznaczony jako zagrożony odejściemrisk, reasons, session
offer_shownpojawia się oferta wyjściaart, risk, grund, session
offer_clickkliknięto jej przyciskart, risk, grund, session, fehler
offer_dismisszostaje zamkniętaart, risk, grund, session
survey_shownotwiera się ankietasurvey, trigger, session
survey_answerodwiedzający odpowiadasurvey, type, value, option, sentiment, session
survey_textwysłano tekst uzupełniający (już przefiltrowany)survey, text, session
survey_dismissankietę zamknięto bez odpowiedzisurvey, step, session

Gdy most GTM jest włączony, te same zdarzenia trafiają też do dataLayer (mp_exit_risk itd.). MousePlayer.exitRisk() zwraca aktualne ryzyko porzucenia albo null, dopóki nie jest znane.

8. Atrybuty 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 (lub klasa mp-masked): tekst i dane wpisane w elemencie są zastępowane, zanim opuszczą przeglądarkę – w zrzucie, w zmianach i w opisach kliknięć.
  • data-mp-ignore (lub mp-ignore) na polu formularza: jego wartość w ogóle nie jest nagrywana.
  • data-mp-role: jedna z wartości 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. Inne wartości są pomijane.

9. Wykluczanie własnych wizyt

Otwórz swoją stronę raz z ?mp_exclude=1, a ta przeglądarka nie będzie już nagrywana; ?mp_exclude=0 to cofa. Dla całej sieci biurowej wpisz zamiast tego adresy IP w ustawieniach projektu.

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. Link do Twojej polityki prywatności

Odwiedzający mogą zobaczyć i usunąć to, co o nich nagrano. privacyUrl() zwraca gotowy link z identyfikatorem tej przeglądarki – albo null, jeśli go nie ma, bo bez zgody nic nie nagrano.

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