タグ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){if(!window[n]){var o=window[n]=function(){var n=[].slice.call(arguments);return o.x?o.x.apply(0,n):o.q.push(n)};o.q=[],o.i=Date.now(),o.allow=function(){o.o="allow"},o.deny=function(){o.o="deny"}}}("krt")</script>
<!-- Start KARTE Compatible Tag -->
<script>!function(e,t,n){var r=this&&this.__spreadArray||function(e,t,n){if(n||2===arguments.length)for(var r,a=0,o=t.length;a<o;a++)!r&&a in t||(r||(r=Array.prototype.slice.call(t,0,a)),r[a]=t[a]);return e.concat(r||Array.prototype.slice.call(t))};n[t]&&(n[t].stop(),console.warn("[krt:compat] detect old tracker and remove it"),delete n[t]);var a=n[t]||(n[t]=[]),o=function(){for(var t=[],r=0;r<arguments.length;r++)t[r]=arguments[r];return n[e].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(e){a[e]=function(){for(var t=[],n=0;n<arguments.length;n++)t[n]=arguments[n];return console.error.apply(console,r(["[krt:compat] not implmeneted",e],t,!1))}})),a.track=function(){for(var e=[],t=0;t<arguments.length;t++)e[t]=arguments[t];if(0!==e.length)return e[1]||(e[1]={}),e[1]._system||(e[1]._system={}),e[1]._system.compatible_tag=!0,o.apply(void 0,r(["send"],e,!1))},a.user=function(){for(var e=[],t=0;t<arguments.length;t++)e[t]=arguments[t];return e[0]||(e[0]={}),e[0]._system||(e[0]._system={}),e[0]._system.compatible_tag=!0,o.apply(void 0,r(["send","identify"],e,!1))},["buy","view","page"].map((function(e){return a[e]=function(){for(var t=[],n=0;n<arguments.length;n++)t[n]=arguments[n];return t[0]||(t[0]={}),t[0]._system||(t[0]._system={}),t[0]._system.compatible_tag=!0,o.apply(void 0,r(["send",e],t,!1))}})),a.link=function(t,r){var a=document.querySelector(t);a&&(r||(r={}),r._system||(r._system={}),r._system.compatible_tag=!0,r.href=a.getAttribute("href"),r.event_name||(r.event_name="link"),a.addEventListener("click",(function(){return n[e]("send",r.event_name,r)}),!0))},a.api_key="6465f321e6731e9eaf7b2aba542a5877"}("krt","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と異なり、「タグv2設定」画面にある「オプション設定」の各種オプションのON/OFFを切り替えても計測タグの記述は変わりません
  • 「タグのカスタマイズ」の設定については、「オプション設定」とは異なり変更時に計測タグの記述が変わります

カスタムイベントタグの記述方法

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

• タグv1の記法で記述されたカスタムイベントタグは次のような形式です
  • 第1引数には、発生させるイベント名を指定します
    • EVENT_NAMEの部分には、view_itemやcartなどのイベント名が入ります
  • 第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内に「送信待ちイベントデータ」がキューイングされるようになりました

詳細は次のページをご覧ください。

• 送信待ちイベントデータのキューイング | スタートガイド / タグ設置・イベント計測 / カスタムイベントタグ | KARTEサポートサイト

SPAサイトにおいて意図しないページで接客サービスが表示されないようにする機能

SPAサイトにおいて、接客サービスがトリガーされてすぐにSPAのページ遷移が発生した場合、意図しないページで接客サービスが表示されてしまうリスクがありました。

そのため、計測タグv2では次のような仕様が追加されました。

• 「接客サービスがトリガーされた時点」と「実際に接客サービスが表示される時点」の間でSPAの仮想的なページ遷移を示すviewイベントが発生した場合、その接客サービスが表示されないように表示抑制される

なお、そのような表示抑制がされた場合は「接客サービスの表示抑制(_message_suppressed)イベント」が発生します。そのとき、reasonフィールドの値は"action is expired due to page change"になります。

タグv2で廃止された機能

一部の特殊なメソッド

• 下記のメソッドは、タグv2では利用できなくなります。タグv1で利用していた場合、別の方法で同様のトラッキングを実現する必要があります
  • tracker.link()
    • 代わりの実装方法: ページ上のリンククリックを計測する | KARTEサポートサイト
    • 以下に記載されたtracker.link()を置き換えるタグの実装サンプルを参考にいただいても、問題ありません
  • tracker.form()
    • 代わりの実装方法: formの入力情報を計測する | KARTEサポートサイト

tracker.link()を置き換えるタグの実装サンプル

• tracker.link()については、簡単なタグ実装によってほぼ同様の挙動を実現できます
• 下記にタグv2を使ってtracker.link()を置き換えるタグの実装サンプルを示します
  • 既存のタグの内容に合わせて、内容を書き換えてからタグ設置してください
  • tracker.link()と全く同じ動作をサポートするものではありません

<!--移行前（例）-->
<script type="text/javascript">
tracker.link('#linkbtn', {
    event_name: 'foo_button_click',
    foo_field: 42
});
</script>

<!--移行後（サンプル実装）-->
<script type="text/javascript">
(function(){
    trackLink('#linkbtn', {
        event_name: 'foo_button_click',
        foo_field: 42
    });

    function trackLink(selector, values) {
        if (!values) values = {};
        var t = document.querySelector(selector);
        if (!t) return console.log('[krt trackLink] target element not found.');
        var event_name = 'link';
        if (values.event_name) {
            event_name = values.event_name;
        }
        values.href = t.getAttribute('href');
        t.addEventListener('click', function() {
            return krt('send', event_name, values);
        });
    }
})();
</script>

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の計測対象になる場合があります

その他、仕様の違い

visitor_idの生成仕様の違い

• 計測タグv2では、計測タグv1と比べてvisitor_idの文字数が少なくなるような発番ルールを採用しています
• なお、すでに計測タグv1からvisitor_idが付与済みのブラウザについては、計測タグv2移行後にも従来のvisitor_idがそのまま利用されます

visitor間のマージ仕様の違い

• 下記の2つの機能において、計測タグv1ではブラウザに付与されたvisitor_id自体が書き換えられるような仕様になっていました
  • マルチドメインモード
    • タグ設置先ドメインのCookieに保存されるvisitor_idが、karte.ioドメインのcookieに保存されたvisitor_idで上書きされる
  • Native App SDKを用いたWebViewユーザーとNative Appユーザーの紐付け処理
    • WebViewユーザーのvisitor_idが、Native Appユーザーのvisitor_idで上書きされる
• 一方で、計測タグv2ではそれぞれの環境で別々のvisitor_idが保持され続けるようになり、代わりにビジター同士のマージ処理が内部的に行われるようになります
  • マルチドメインモード
    • タグ設置先ドメインのCookieに保存されるvisitor_idはそのままになる
    • そのビジターは、karte.ioドメインのcookieに保存されたvisitor_idを持つビジターにマージされる
  • Native App SDKを用いたWebViewユーザーとNative Appユーザーの紐付け処理
    • WebViewユーザーのvisitor_idとNative Appユーザーのvisitor_idは別々になる
    • WebViewユーザーとしてのビジターは、Native Appユーザーとしてのビジターにマージされる