JavaScript API - MousePlayer

1. 二つの呼び出し方法

mp.js は非同期で読み込まれます。読み込み前に実行されるコードは、呼び出しを次のキューに入れます： window.mp_q。mp.js は読み込まれるとすぐに処理します。その後は、同じ関数を次でも利用できます： 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);

常に次のように記述し、 window.mp_q = window.mp_q || []次は使わないでください： window.mp_q = []。mp.js はその配列を監視し続けます。新しい配列にすると、同意撤回を含む、それ以降のすべての呼び出しが失われます。

インストール用スニペットは、同じようにキューへ追加するスタブの mp(...) も定義します。両形式で、同じコマンドを受け付けます： consent、 set、 event、 step、 get、 on と off。

2. 同意

同意なしでは何も記録しません。同意管理ツールが MousePlayer の認識するものであれば、ここでの処理は不要です。それ以外では、ご自身で判断結果を渡してください。

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'

撤回はページ上で直ちに適用されます。リスナーを削除し、バッファー内のデータを破棄し、接続を閉じます。詳しくは、 MousePlayer と同意をご覧ください。

3. お客様独自の顧客 ID

独自の ID を使うと、一人のすべてのデバイスが一覧内で一人の訪問者にまとまり、既知の番号でサポート対象を検索できます。同じブラウザーの過去30日間の訪問にも ID を適用します。

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

メールアドレスや氏名ではなく、内部の番号を使ってください。MousePlayer は訪問者が表示される場所すべてに、その ID を表示します。

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. カスタムイベント

送信したイベントは再生のタイムラインに表示され、目標やファネルのステップにでき、Webhook や連携ツールにも送られます。パラメーターは短い値です。数値、最大255文字の文字列、最大64文字のキーを指定できます。

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

名前は小文字とアンダースコアで、最大128文字です。同じものにはどこでも同じ名前を使ってください。目標は名前を完全一致で照合します。
パラメーターに個人データを入れないでください。他のイベントと同じように保存・表示されます。

5. アドレスが変わらないステップ

画面が変わってもアドレスが変わらないチェックアウトやウィザードは、MousePlayer にとって一つのページです。 step() を使うと、各画面が独立したページビューになり、それぞれのスナップショット、ヒートマップの行、ファネルのステップを持ちます。

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

名前は a-z、0-9、_、- からなる1～40文字です。空白はハイフンになり、それ以外はコンソールに警告を出して拒否します。実際のページ移動が起きると、ステップは終了します。

6. 商品のコンテキスト

商品ページでは、何を見ているかを MousePlayer に伝えます。受け付けるキーは次だけです。顧客データが誤って入り込まないよう、その他はすべて破棄します。

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. フック

ページ上で MousePlayer が測定した内容に、独自のコードで反応できます。最初の瞬間を逃してはいけないフックは、キューを通じて登録してください。

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

名前	タイミング	フィールド
`exit_risk`	離脱モデルが最初のページビューにスコアを付けたとき（訪問ごとに1回）	`risk, reasons, session`
`churn_risk`	リピーターに離反の可能性が高いと判定したとき	`risk, reasons, session`
`offer_shown`	離脱時オファーを表示したとき	`art, risk, grund, session`
`offer_click`	そのボタンがクリックされたとき	`art, risk, grund, session, fehler`
`offer_dismiss`	閉じられたとき	`art, risk, grund, session`
`survey_shown`	アンケートが開いたとき	`survey, trigger, session`
`survey_answer`	訪問者が回答したとき	`survey, type, value, option, sentiment, session`
`survey_text`	追加の自由記述を送信したとき（フィルタリング済み）	`survey, text, session`
`survey_dismiss`	回答せずにアンケートを閉じたとき	`survey, step, session`

GTM 連携ブリッジが有効な場合、同じイベントを dataLayer にも送ります（mp_exit_risk など）。 MousePlayer.exitRisk() は現在の離脱リスクを返し、不明な段階では null を返します。

8. 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 （またはクラス mp-masked）：要素内のテキストと入力を、ブラウザーから出る前に置き換えます。スナップショット、変更、クリックの説明が対象です。
data-mp-ignore （または mp-ignore）をフォーム入力欄に付けると、その値を一切記録しません。
data-mp-role：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 のいずれかです。他の値は無視します。

9. 自分自身の訪問を除外する

次を付けてサイトを一度開くと、 ?mp_exclude=1 そのブラウザーは以後記録されません。 ?mp_exclude=0 で元に戻せます。オフィスのネットワーク全体を対象にする場合は、代わりにプロジェクト設定に IP アドレスを入力してください。

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

10. プライバシーポリシー用のリンク

訪問者は、自分について記録された内容を確認・削除できます。 privacyUrl() は、このブラウザーの ID を含む、そのまま使えるリンクを返します。ID がなければ null を返します。同意なしでは何も記録されていないためです。

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

どのようなことでお困りですか？