API JavaScript

Todo lo que mp.js ofrece a su código: consentimiento, ID de cliente, eventos personalizados, pasos sin cambio de dirección, hooks y atributos HTML. Nada de esto es obligatorio: el fragmento de código basta para grabar.

1. Dos formas de llamarla

mp.js carga de forma asíncrona. El código que se ejecuta antes pone sus llamadas en la cola window.mp_q; mp.js las procesa en cuanto está disponible. Después, las mismas funciones están disponibles en 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);

Escriba siempre window.mp_q = window.mp_q || [], nunca window.mp_q = []. mp.js sigue escuchando ese array: uno nuevo absorbería todas las llamadas posteriores, incluida la retirada del consentimiento.

El fragmento de instalación también define una función provisional mp(...) que usa la misma cola. Ambas formas aceptan los mismos comandos: consent, set, event, step, get, on y off.

2. Consentimiento

Sin consentimiento no se graba nada. Si MousePlayer reconoce su herramienta de consentimiento, no necesita nada de esto; de lo contrario, transmita la decisión por su cuenta.

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 retirada se aplica inmediatamente en la página: se eliminan los receptores de eventos, se descartan los datos del búfer y se cierra la conexión. Véase MousePlayer y el consentimiento.

3. Su ID de cliente

Con su propio ID, todos los dispositivos de una persona aparecen como un visitante en las listas y puede buscar un caso de soporte por el número conocido. El ID también se aplica a visitas anteriores del mismo navegador de los últimos 30 días.

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

Use un número interno, no un correo ni un nombre. MousePlayer muestra el ID donde aparezca el visitante.

Consultar los 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. Eventos personalizados

Los eventos enviados aparecen en la cronología de la reproducción, pueden ser objetivos y pasos de embudo y se envían a webhooks y herramientas conectadas. Los parámetros son valores cortos: números, cadenas de hasta 255 caracteres y claves de hasta 64 caracteres.

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' }]);
  • Nombres: minúsculas con guiones bajos, máximo 128 caracteres. Use siempre el mismo nombre para lo mismo: un objetivo compara nombres exactos.
  • No incluya datos personales en parámetros. Se almacenan y muestran como cualquier otro evento.

5. Pasos sin cambio de dirección

Un pago o asistente que cambia de pantalla sin cambiar de dirección es una sola página para MousePlayer. step() convierte cada pantalla en una vista de página independiente, con su propia captura, fila en el mapa de calor y paso de embudo.

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

El nombre tiene de 1 a 40 caracteres de a-z, 0-9, _ y -; los espacios se convierten en guiones y lo demás se rechaza con un aviso en la consola. Una navegación real termina el paso.

6. Contexto del producto

En una página de producto, indique a MousePlayer qué se está viendo. Solo se aceptan estas claves; lo demás se descarta para evitar datos de clientes accidentales.

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

Su código puede reaccionar a lo que mide MousePlayer en la página. Registre el hook mediante la cola si no debe perderse el primer instante.

// 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);
NombreCuándoCampos
exit_riskel modelo de salida evalúa la primera vista de página (una vez por visita)risk, reasons, session
churn_riskun visitante recurrente se marca con riesgo de fugarisk, reasons, session
offer_shownse muestra la oferta de salidaart, risk, grund, session
offer_clickse hace clic en su botónart, risk, grund, session, fehler
offer_dismissse cierraart, risk, grund, session
survey_shownse abre una encuestasurvey, trigger, session
survey_answerel visitante respondesurvey, type, value, option, sentiment, session
survey_textse envía el texto de seguimiento (ya filtrado)survey, text, session
survey_dismissla encuesta se cierra sin respuestasurvey, step, session

Con el puente GTM activo, los mismos eventos también se envían al dataLayer (mp_exit_risk y así sucesivamente). MousePlayer.exitRisk() devuelve el riesgo de salida actual o null si aún no se conoce.

8. Atributos 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 clase mp-masked): el texto y las entradas dentro del elemento se sustituyen antes de salir del navegador, en la captura, los cambios y las descripciones de clics.
  • data-mp-ignore (o mp-ignore) en un campo de formulario: su valor no se graba en absoluto.
  • data-mp-role: uno de 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. Los demás valores se ignoran.

9. Excluir sus propias visitas

Abra su sitio una vez con ?mp_exclude=1 y ese navegador dejará de grabarse; ?mp_exclude=0 lo deshace. Para toda una red de oficina, introduzca las direcciones IP en los ajustes del proyecto.

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 enlace para su política de privacidad

Los visitantes pueden ver y eliminar lo grabado sobre ellos. privacyUrl() devuelve el enlace listo con el ID de este navegador, o null si no tiene ninguno, porque sin consentimiento no se grabó nada.

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