タグv1からタグv2に移行する際の参考として、タグの記述方法の違いについてまとめます。

タグv2とは?

タグv2の詳細については、下記の記事をご覧ください。

タグv2とは? | KARTEサポートサイト

タグv1からタグv2への移行手順については、下記の記事をご覧ください。

タグv1からタグv2に移行する | KARTEサポートサイト

計測タグ

計測タグv1

  • オプションが設定されていない場合、タグv1の計測タグとは次のようなものです
    • API_KEYの部分にはKARTEプロジェクトのAPIキーが入ります
    • 一部、見やすく整形しています
    • 計測タグの発行時期に依っては、記述内容が一部異なることがあります
<!-- 一般的な計測タグv1の例 -->
<script type="text/javascript">
    (function(){var t,e,n,r,i;for(t=function(){var t;return t=[],function(){var e,n,r,i;for(n=["init","start","stop","user","track","action","event","goal","chat","buy","page","view","admin","group","alias","ready","link","form","click","submit","cmd","emit","on","send","css","js","style","option","get","set","collection"],e=function(e){return function(){return t.push([e].concat(Array.prototype.slice.call(arguments,0)))}},r=0,i=[];r<n.length;)t[n[r]]=e(n[r]),i.push(r++)}(),t.init=function(e,n){var r,i;return t.api_key=e,t.options=n||{},i=document.createElement("script"),i.type="text/javascript",i.async=!0,i.charset="utf-8",i.src=t.options.tracker_url||"https://static.karte.io/libs/tracker.js",r=document.getElementsByTagName("script")[0],r.parentNode.insertBefore(i,r)},t},r=window.karte_tracker_names||["tracker"],e=0,n=r.length;e<n;e++)i=r[e],window[i]||(window[i]=t());
        tracker.init("API_KEY")
    }).call(this);
</script>
  • 計測タグのオプションを有効にするために、tracker.init()の第2引数にオプション内容を示すオブジェクトが渡されるケースもあります
<!-- オプションを指定している計測タグv1の例 -->
<script type="text/javascript">
    (function(){var t,e,n,r,i;for(t=function(){var t;return t=[],function(){var e,n,r,i;for(n=["init","start","stop","user","track","action","event","goal","chat","buy","page","view","admin","group","alias","ready","link","form","click","submit","cmd","emit","on","send","css","js","style","option","get","set","collection"],e=function(e){return function(){return t.push([e].concat(Array.prototype.slice.call(arguments,0)))}},r=0,i=[];r<n.length;)t[n[r]]=e(n[r]),i.push(r++)}(),t.init=function(e,n){var r,i;return t.api_key=e,t.options=n||{},i=document.createElement("script"),i.type="text/javascript",i.async=!0,i.charset="utf-8",i.src=t.options.tracker_url||"https://static.karte.io/libs/tracker.js",r=document.getElementsByTagName("script")[0],r.parentNode.insertBefore(i,r)},t},r=window.karte_tracker_names||["tracker"],e=0,n=r.length;e<n;e++)i=r[e],window[i]||(window[i]=t());
        tracker.init("API_KEY", {
            ktid_check: true,
            spa_mode: { reset_past_actions: true, close_actions: true },
        })
    }).call(this);
</script>
  • 主なオプションは、次の通りです

    • ktid_check: マルチドメインオプション
    • spa_mode: SPAモード
    • webview_only: KARTEのApp SDKが導入されたネイティブアプリでWebViewとしてページが読み込まれた場合のみ計測するモード
  • また、KARTEのtrackerが格納されるグローバル変数の名前が変更されている場合、計測タグは次のように変更されます

    • 一番上に window.karte_tracker_names=["変更後のtracker名"]; といった記述が追加される
    • tracker.init()trackerがその変更後のtracker名になる
<!-- tracker名称を変更している計測タグv1の例 -->
<script type="text/javascript">
    window.karte_tracker_names=["kartetracker"];
    (function(){var t,e,n,r,i;for(t=function(){var t;return t=[],function(){var e,n,r,i;for(n=["init","start","stop","user","track","action","event","goal","chat","buy","page","view","admin","group","alias","ready","link","form","click","submit","cmd","emit","on","send","css","js","style","option","get","set","collection"],e=function(e){return function(){return t.push([e].concat(Array.prototype.slice.call(arguments,0)))}},r=0,i=[];r<n.length;)t[n[r]]=e(n[r]),i.push(r++)}(),t.init=function(e,n){var r,i;return t.api_key=e,t.options=n||{},i=document.createElement("script"),i.type="text/javascript",i.async=!0,i.charset="utf-8",i.src=t.options.tracker_url||"https://static.karte.io/libs/tracker.js",r=document.getElementsByTagName("script")[0],r.parentNode.insertBefore(i,r)},t},r=window.karte_tracker_names||["tracker"],e=0,n=r.length;e<n;e++)i=r[e],window[i]||(window[i]=t());
        kartetracker.init("API_KEY")
    }).call(this);
</script>

※trackerのグローバル変数名を変更しているサイトの場合、この記事に後述する様々なタグ(v1)に記載の tracker という名称は、変更後の名称に置き換えられています。(参考: 計測タグのtracker名を変更する | KARTEサポートサイト

計測タグv2

  • タグv2の計測タグとは次のようなものです
    • API_KEYの部分にはKARTEプロジェクトのAPIキーが入ります
    • 計測タグの発行時期に依っては、記述内容が一部異なることがあります
<!-- Start KARTE Tag -->
<script>!function(n){var a=window[n]=function(){var n=[].slice.call(arguments);return a.x?a.x.apply(0,n):a.q.push(n)};a.q=[],a.i=Date.now()}("krt")</script>
<script async src="https://cdn-edge.karte.io/API_KEY/edge.js"></script>
<!-- End KARTE Tag -->
  • 「互換タグ付き計測タグv2」を発行した場合は、次のようにタグ中に「互換タグ」(Compatible Tag)が追加されています
    • 「互換タグ」についてはこちらをご覧ください
<!-- Start KARTE Tag -->
<script>!function(n){var a=window[n]=function(){var n=[].slice.call(arguments);return a.x?a.x.apply(0,n):a.q.push(n)};a.q=[],a.i=Date.now()}("krt")</script>
<!-- Start KARTE Compatible Tag -->
<script>!function(t,e,n){var r=this&&this.__spreadArray||function(t,e,n){if(n||2===arguments.length)for(var r,o=0,a=e.length;o<a;o++)!r&&o in e||(r||(r=Array.prototype.slice.call(e,0,o)),r[o]=e[o]);return t.concat(r||Array.prototype.slice.call(e))};n[e]&&(n[e].stop(),console.warn("[krt:compat] detect old tracker and remove it"),delete n[e]);var o=n[e]||(n[e]=[]),a=function(){for(var t=[],e=0;e<arguments.length;e++)t[e]=arguments[e];return n.krt.apply(n,t)};["start","stop","action","event","goal","chat","admin","group","alias","ready","form","click","submit","cmd","emit","on","send","css","js","style","option","get","set","collection"].map((function(t){o[t]=function(){for(var e=[],n=0;n<arguments.length;n++)e[n]=arguments[n];return console.error.apply(console,r(["[krt:compat] not implmeneted",t],e,!1))}})),o.track=function(){for(var t=[],e=0;e<arguments.length;e++)t[e]=arguments[e];return a.apply(void 0,r(["send"],t,!1))},o.user=function(){for(var t=[],e=0;e<arguments.length;e++)t[e]=arguments[e];return a.apply(void 0,r(["send","identify"],t,!1))},["buy","view","page"].map((function(t){return o[t]=function(){for(var e=[],n=0;n<arguments.length;n++)e[n]=arguments[n];return a.apply(void 0,r(["send",t],e,!1))}})),o.link=function(t,e){var n=document.querySelector(t);n&&n.addEventListener("click",(function(){return a()("send","link",e)}),!0)},o.api_key="API_KEY"}(0,"tracker",window)</script>
<!-- End KARTE Compatible Tag -->
<script async src="https://cdn-edge.karte.io/API_KEY/edge.js"></script>
<!-- End KARTE Tag -->
  • なお計測タグv2ではv1と異なり、次のようなオプション設定のON/OFFによって計測タグの記述が変わるということはなくなりました
    • マルチドメインオプション
    • SPAモード
    • KARTEのApp SDKが導入されたネイティブアプリでWebViewとしてページが読み込まれた場合のみ計測するモード

カスタムイベントタグ

カスタムイベントタグv1(tracker.track())

  • タグv1の記法で記述されたカスタムイベントタグは次のような形式です
    • 第1引数には、発生させるイベント名を指定します
      • EVENT_NAMEの部分には、view_itemcartなどのイベント名が入ります
    • 第2引数には、イベントのフィールド値をオブジェクト形式で指定します
<script type="text/javascript">
// サンプル
tracker.track('EVENT_NAME', {
    foo: 'xxx123',
    bar: 42
});
</script>

カスタムイベントタグv2

  • 上記をタグv2の記法で書き換えると、次のようになります
    • 変更すべき点
      • グローバル変数名がtrackerからkrtに変更になります
      • .trackなどのメソッド名の指定が不要になり、krtをそのまま関数として実行できます
        • 代わりに第1引数に'send'を指定します
      • イベント名を第2引数に、フィールド値を第3引数に指定します
<script type="text/javascript">
// サンプル
krt('send', 'EVENT_NAME', {
    foo: 'xxx123',
    bar: 42
});
</script>

tracker.track()のエイリアスを利用したタグ(ユーザータグ、viewイベントタグ、buyイベントタグ)

イベントを発生させるタグの中にも、tracker.track()ではなくそのエイリアスを使っているものがあります。
タグv2記法への変更内容については、tracker.track()の場合と同様です。

ユーザータグ

  • タグv1の記法で記述されたユーザータグは次のようなものです
    • 下記はサンプルであり、実際の記述内容はタグに依って異なります
    • 第1引数のオブジェクトにイベントのフィールド値が指定されます
    • 内部的には、identifyというイベントが発生します
<script type="text/javascript">
// サンプル
tracker.user({
    user_id: "xxx123",
    email: 'sample@sample.com',
    subscription: true
});
</script>
  • このタグは、タグv1の下記のタグと同じ意味です
<script type="text/javascript">
// サンプル
tracker.track('identify', {
    user_id: "xxx123",
    email: 'sample@sample.com',
    subscription: true
});
</script>
  • 上記をタグv2の記法に書き換えると、次のような形になります
<script type="text/javascript">
// サンプル
krt('send', 'identify', {
    user_id: "xxx123",
    email: 'sample@sample.com',
    subscription: true
});
</script>

buyイベントタグ

  • タグv1の記法で記述されたbuyイベントタグは次のようなものです
    • 下記はサンプルであり、実際の記述内容はタグに依って異なります
    • 第1引数のオブジェクトにイベントのフィールド値が指定されます
    • 内部的には、buyというイベントが発生します
<script type="text/javascript">
// サンプル
tracker.buy({
    transaction_id: "00001",
    revenue: 2000
});
</script>
  • このタグは、タグv1の下記のタグと同じ意味です
<script type="text/javascript">
// サンプル
tracker.track('buy', {
    transaction_id: "00001",
    revenue: 2000
});
</script>
  • 上記をタグv2の記法に書き換えると、次のような形になります
<script type="text/javascript">
// サンプル
krt('send', 'buy', {
    transaction_id: "00001",
    revenue: 2000
});
</script>

viewイベントタグ

  • タグv1の記法で記述されたviewイベントタグは次のようなものです
    • 内部的には、viewというイベントが発生します
<script type="text/javascript">
// サンプル
tracker.view();
</script>
  • このタグは、タグv1の下記のタグと同じ意味です
<script type="text/javascript">
// サンプル
tracker.track('view');
</script>
  • 上記をタグv2の記法に書き換えると、次のような形になります
<script type="text/javascript">
// サンプル
krt('send', 'view');
</script>

カスタムイベントタグ中のエラー処理に関する記述

カスタムイベントタグの中には、タグ中のJavaScriptプログラムの実行時にエラーが発生した場合のエラー処理に関する記述が含まれることがあります。
その記述についても、一般的には書き換えが必要です。

エラー処理の記述例(タグv1)

<script type="text/javascript">
try {
    // ここにカスタムイベントタグ本来の記述が入ります
} catch (e) {
    if ("tracker" in window) {
        tracker.track("_error", { message: e.message });
    } else {
        console.warn("tracker was not loaded");
    }
}
</script>

エラー処理の記述例(タグv2)

<script type="text/javascript">
try {
    // ここにカスタムイベントタグ本来の記述が入ります
} catch (e) {
    if ("krt" in window) {
        krt("send", "_error", { message: e.message });
    } else {
        console.warn("tracker was not loaded");
    }
}
</script>

タグv2で追加された機能

送信待ちイベントデータのキューイング

  • タグv1では、tracker.track()などのメソッドでイベントを送信する際に、イベント送信完了までの間にページ遷移をしてしまうとイベントが欠損してしまうことがありました
  • タグv2ではイベントの欠損を減らすために、ブラウザのlocalStorage内に「送信待ちイベントデータ」がキューイングされるようになりました
    • 処理の流れ(buyイベントを送信する場合の例)
      1. ページ上で krt('send', 'buy', { revenue: 1000 }) といったタグが実行される
      2. イベント名(buy)やフィールド情報({revenue: 1000})がlocalStorageに一時保存される
      3. 同一PV内で送信処理まで完了する場合
        • 同一PV内で、localStorageに保存されたbuyイベントがKARTEに送信され、localStorageに一時保存されたデータが削除される
      4. 同一PV内で送信処理まで完了しなかった場合
        • 次PVで、localStorageに保存されたbuyイベントがKARTEに送信され、localStorageに一時保存されたデータが削除される
  • 一般に、「localStorageへの書き込み処理」の方が「イベント送信処理」よりも速いため、タグv1と比べてタグv2によるイベント送信の方が「ページ遷移に伴うイベントの欠損率」は下がる見込みです
    • ただし、タグ実行とほぼ同時にページ遷移処理が走った場合に、イベントが100%欠損しないことを保証するものではありません

タグv2で廃止された機能

一部の特殊なメソッド

callback関数の呼び出し

  • タグv1のtracker.track()では、第3引数にcallback関数を渡すことができました
    • それにより、イベントトラッキングの完了を待ってから任意の処理を実行することができました
<script type="text/javascript">
// サンプル
tracker.track('foo_event', {
    foo: 42
}, function() {
    console.log('the event has sent.');
    location.href = 'https://example.com/';
});
</script>
  • このcallback関数は、主に「イベントの欠損を避けるために、イベント送信処理が完了したらページ遷移させる」という用途で使われていました
  • タグv2では前述した「送信待ちイベントデータのキューイング」機能により、イベント送信処理の完了を待たずにページ遷移した場合であっても、イベントデータがキューに積まれていれば、次に計測タグ設置ページを閲覧したタイミングでイベントが再送されます
  • そのため、タグv2の krt() 関数はcallback関数を受け取ることができない仕様となっています

計測対象ブラウザの判定方法の違い

計測タグv1

  • 計測タグv1の開発当初は、世の中で利用されるWebブラウザの種類が多様かつKARTEの動作保証ができない古いブラウザも多く利用されていました
  • そのため、次のような方式で計測対象ブラウザを制限していました
    • UserAgentを利用してユーザーのOSやブラウザの種類及びバージョン番号を判定
    • KARTE側で規定されたホワイトリストに合致しないOSやブラウザについてはイベント計測を行わないように制御

計測タグv2

  • 近年では、世の中で利用されるWebブラウザの種類が限定的になり機能差分も小さくなってきました
  • また、Webブラウザの仕様に関する議論の中ではUserAgentの利用を制限する動きもあり、UserAgentではなくブラウザ自体の機能有無によってサポート対象のブラウザかどうかを判定するのが一般的になってきました
  • そこで、計測タグv1で利用していた「UserAgentを用いたホワイトリスト形式の計測制限」を計測タグv2では廃止しました
  • そのため計測タグv1とは異なり、計測タグv2を利用する場合、「サポート対象ブラウザ」以外のブラウザについてもKARTEの計測対象になる場合があります