API JavaScript

Tudo o que mp.js oferece ao seu código: consentimento, seu ID de cliente, eventos personalizados, etapas sem mudança de endereço, hooks e atributos HTML. Nada disso é obrigatório: o snippet sozinho já grava.

1. Duas formas de chamar

mp.js carrega de forma assíncrona. O código executado antes do carregamento coloca suas chamadas na fila window.mp_q; mp.js a processa assim que fica disponível. Depois, as mesmas funções ficam disponíveis em 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);

Sempre use window.mp_q = window.mp_q || [], nunca window.mp_q = []. mp.js continua monitorando esse array: substituí-lo por outro descartaria todas as chamadas posteriores, inclusive a retirada de consentimento.

O snippet de instalação também define uma função provisória mp(...) que usa a fila da mesma forma. Ambas as formas aceitam os mesmos comandos: consent, set, event, step, get, on e off.

2. Consentimento

Sem consentimento, nada é gravado. Se sua ferramenta de consentimento for reconhecida pelo MousePlayer, você não precisa fazer nada disso; caso contrário, transmita a decisão por conta própria.

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'

A retirada entra em vigor imediatamente na página: os listeners são removidos, os dados no buffer são descartados e a conexão é encerrada. Consulte MousePlayer e consentimento.

3. Seu ID de cliente

Com um ID próprio, todos os dispositivos de uma pessoa aparecem como um único visitante nas listas, e você pode pesquisar um caso de suporte pelo número que conhece. O ID também é aplicado às visitas anteriores do mesmo navegador nos últimos 30 dias.

// 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 um número interno, em vez de um endereço de e-mail ou nome. O MousePlayer exibe o ID onde quer que o visitante apareça.

Consultar IDs

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

Os eventos enviados aparecem na linha do tempo da reprodução, podem servir como metas e etapas de funil e são enviados aos seus webhooks e ferramentas conectadas. Os parâmetros são valores curtos: números, textos de até 255 caracteres e chaves de até 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' }]);
  • Nomes: letras minúsculas com sublinhados, no máximo 128 caracteres. Use o mesmo nome para a mesma ação em todos os lugares: uma meta exige correspondência exata do nome.
  • Não inclua dados pessoais nos parâmetros. Eles são armazenados e exibidos como qualquer outro evento.

5. Etapas sem mudança de endereço

Um checkout ou assistente que muda de tela, mas mantém o endereço, é uma única página para o MousePlayer. step() transforma cada tela em uma visualização de página separada, com sua própria captura, linha no mapa de calor e etapa de funil.

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

O nome deve ter de 1 a 40 caracteres entre a-z, 0-9, _ e -; espaços se tornam hifens, e qualquer outro caractere é rejeitado com um aviso no console. Uma navegação real encerra a etapa.

6. Contexto do produto

Em uma página de produto, informe ao MousePlayer o que está sendo visualizado. Somente estas chaves são aceitas; todo o restante é descartado para evitar a inclusão acidental de dados de clientes.

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

Seu código pode reagir ao que o MousePlayer mede na página. Registre pela fila se o hook precisar estar disponível desde o primeiro momento.

// 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);
NomeQuandoCampos
exit_risko modelo de saída pontua a primeira visualização de página (uma vez por visita)risk, reasons, session
churn_riskum visitante recorrente é identificado como propenso à perdarisk, reasons, session
offer_showna oferta de saída é exibidaart, risk, grund, session
offer_clicko botão da oferta é clicadoart, risk, grund, session, fehler
offer_dismissa oferta é fechadaart, risk, grund, session
survey_shownuma pesquisa é abertasurvey, trigger, session
survey_answero visitante respondesurvey, type, value, option, sentiment, session
survey_texto texto de acompanhamento é enviado (já filtrado)survey, text, session
survey_dismissa pesquisa é fechada sem respostasurvey, step, session

Quando a ponte GTM está ativa, os mesmos eventos também são enviados ao dataLayer (mp_exit_risk e assim por diante). MousePlayer.exitRisk() retorna o risco de saída atual ou null enquanto ele ainda não é conhecido.

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 (ou a classe mp-masked): o texto e os dados inseridos dentro do elemento são substituídos antes de saírem do navegador, tanto na captura quanto nas alterações e descrições de cliques.
  • data-mp-ignore (ou mp-ignore) em um campo de formulário: seu valor não é gravado de forma alguma.
  • data-mp-role: um dos valores 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. Outros valores são ignorados.

9. Excluir suas próprias visitas

Abra seu site uma vez com ?mp_exclude=1 e este navegador deixará de ser gravado; ?mp_exclude=0 desfaz essa opção. Para excluir uma rede inteira de escritório, informe os endereços IP nas configurações do projeto.

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. Um link para sua política de privacidade

Os visitantes podem ver e excluir o que foi gravado sobre eles. privacyUrl() retorna o link pronto com o ID deste navegador, ou null se não houver ID, pois sem consentimento nada foi gravado.

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