SPAサイトへの導入手順

KARTE計測タグ設置サイトがSPAである場合、通常の計測タグ設置とは異なり、本ページで紹介する手順で設置する必要があります。

SPAサイトで特別な対応が必要な理由については、先にこちらの記事をご覧ください。

SPAサイトでの特別な計測タグ設置 | KARTEサポートサイト

手順の概要

  1. タグ設定画面で通常の計測タグを取得します
  2. 通常の計測タグに、SPA対応用のオプションを追加し、SPA対応済みの計測タグを作成します
  3. SPA対応が必要な全てのページの読み込み時に、SPA対応済みの計測タグが実行されるようにします
  4. 仮想的なページビューの発生時に、毎回tracker.view()が実行されるようにします

1. タグ設定画面で通常の計測タグを取得

KARTEのタグ設定画面で、通常の計測タグを取得します。

2. 計測タグをカスタマイズ(tracker.init)

取得した計測タグをカスタマイズし、SPA対応済みの計測タグを作成します。

通常の計測タグのtracker.init()

KARTEの通常の計測タグ内には、tracker.init()というメソッド呼び出しが含まれています。

tracker.init("API_KEY");

API_KEYの部分には、実際にはKARTEプロジェクトのAPIキーが入ります。

SPAサイト用にカスタマイズしたtracker.init()の例

tracker.init()の第二引数には、オブジェクトでオプションを追加できます。SPAサイトの場合、次のようにspa_modeプロパティにさらにSPAモードのオプションを指定します。

tracker.init("API_KEY", {
  spa_mode: {
    reset_past_actions: true,
    close_actions: true
  }
});

基本的には、上記の例と同じオプション設定を推奨しています。オプションの詳細は、tracker.initのリファレンスをご覧ください。

※その他のオプションと併用する場合、既存のオプション指定を削除しないよう注意してください。

3. ブラウザのページ読み込み時に計測タグを実行させる

通常サイトと同様に、KARTEの計測対象である全てのページの読み込み時に、作成した「SPA対応済みの計測タグ」を実行するように設定してください。

参考: 計測タグの設置方法 | KARTEサポートサイト

4. 仮想的なページ遷移時にtracker.view()を実行する

KARTEの計測タグには、ブラウザのページ読み込み時に自動で閲覧(view)イベントを発生させる機能があります。ただし、SPAサイトの場合は仮想的なページ遷移時に明示的にviewイベントを発生させる必要があります。

明示的にviewイベントを発生させるには、SPAサイトの仮想的なページ遷移時に毎回tracker.view()を引数無しで実行してください。

tracker.view();

具体的なコードの埋め込み箇所については、SPAの実装および使用しているフレームワーク(Vue.js, Angular, jQuery-mobileなど)に依存します。
多くの場合フレームワークのルータには、ルーティング完了時にコードを実行するためのイベント・ハンドラの設定があります。その中でtracker.view()を実行するようにして下さい。

※Googleタグマネージャーを導入しているサイトの場合は、トリガーに「履歴の変更」を指定してtracker.view()実行用のタグを配信することで、サイト側の実装を変更せずにSPA対応が完了する可能性があります。ただしSPAサイトの実装によっては、この方法では仮想的なページ遷移時にGTMのタグがトリガーされない場合もあります。検証の上、問題なければご利用ください。

SPAサイトへの導入時の注意点

tracker.view()の実行タイミング

tracker.view()の実行タイミングが早すぎる場合、次のようにKARTE側との連携が意図に反する結果になることがあります。

  • 仮想的なページ遷移が完全に完了する前にtracker.view()を実行した場合
    • 1ページ前のタイトルがviewイベントで連携されてしまうことがあります
  • widgetが完全に閉じる前にtracker.view()を実行した場合
    • アニメーションの間は、「排他なアクションが実行中」であるとみなされ、次のアクションが配信された場合も表示されないことがあります

ブラウザのURLやタイトルが変わらないケースへの対応

通常のSPAサイトでは、仮想的なページ遷移が行われると、ブラウザに表示されるURLやページタイトルも変更されます。

そのため、tracker.view()を実行した際、KARTE側に連携されるURLやページタイトルはその値を自動で取得しています。

万が一、サイト側のSPA実装の問題で仮想的なページ遷移時にブラウザに表示されるURLやページタイトルが変わらない場合であっても、KARTEのviewイベントに格納されるURLやページタイトルのフィールドを独自に上書きすることはできません。

ただし、次のようにviewイベントに独自のフィールドを追加することは可能です。

tracker.view({custom_title: 'カスタムタイトル', custom_url: 'https://example.com/custom_url'})

詳しくはtracker.view()のリファレンスをご覧ください。

イベントハンドラの削除

  • 配信する接客アクション内(widget)のJavaScriptでイベントハンドラの設定を行った場合、widget内のdestroyedイベント発生時のハンドラ内で、設定したイベントハンドラの削除をしてください
    • 削除しない場合はメモリリークする場合があります