目录
此内容是否有帮助?

# JavaScript SDK 利用ガイド

TIP

データをインポートする前に、インポート前の準備をご参照ください。

GitHub (opens new window)で iOS SDK ソースコードを取得することができます。

JavaScript SDK を実行するにはブラウザが必要で、IE 8 以下のバージョンはサポートしていません。

JavaScript SDK サイズは約 35KB です。

最新バージョン:：v1.4.3

**更新時間：**2021-11-19

ダウンロードアドレス (opens new window)

# 1. JavaScript SDK の導入

1.JavaScript SDK (opens new window)をダウンロード

圧縮パッケージには 2 つの仕様のスクリプトが用意されており、必要に応じて必要なスクリプトを選択します。以下に説明する非同期ロードはファイルthinkingdata.min.jsが必要です。同期ロードにはthinkingdata.umd.min.jsが必要です。

2.JavaScript SDK をロード

非同期ロードまたは同期ロードを選択して SDK を使用します。2 つの方法は大きな違いがないので、どちらかを選択することができます。

SDK を初期化するときにいくつかの配置パラメーターを渡す必要があります。

  • appId:プロジェクトの APP_ID を設定する必要があり、プロジェクトを申請するときに付与されます。ここに入力してください。
  • serverUrl:データアップロードの URL を設定する必要があります。

    クラウドサービスを使用している場合は、次の URL を入力してください。

https://ta-receiver.thinkingdata.io/sync_js

またはhttp://ta-receiver.thinkingdata.io/sync_js

オンプレミスを使用している場合は、次の URL を入力してください。

http://数据采集地址/sync_js

  • send_method:データアップロード方式で、デフォルトは'image'です。図でリクエスト方式を取得し、データをアップロードします。'ajax'に置き換えることができます。
  • useAppTrack: APP との連携をオンにするかどうかを表し、APP の中の H5 ページデータを収集する時に設定し、trueはオン、デフォルトはfalse：オフです。詳細はH5 と APP SDK の連携を参照してください。
  • showLog:アップロードされたデータを印刷するかどうかを表し、オンにするとブラウザコンソールでアップロードされたデータを印刷します。デフォルトはtrue：オンです。
  • persistence:ローカルキャッシュタイプで、デフォルトはlocalStorageです。cookieとして設定可能です。localStorage はサブドメイン間の共有をサポートしていません。同様の要件がある場合は、cookie タイプを選択してください。
  • mode:実行モードで、デフォルトは通常モードです。debugまたはdebug_onlyに設定可能です。詳細はDebug モードをご参照ください。

    注意:上記の配置パラメーターは非同期ロードと同期ロードの両方設定が可能で、一般的には appId と serverUrl のみを設定して済みます。

# 2、ユーザー ID の設定

JS SDK の初期化が完了すると、SDK はランダムなゲスト ID を自動的に生成します。ゲスト ID は、ユーザーが未ログイン状態でユーザーを識別する ID になります。ユーザーは既にアカウント ID を持っている場合、loginでユーザーのアカウント ID を設定してください。また、関連のインターフェイスを使用して、デフォルトのゲスト ID を変更することもできます。

# 2.1 ゲスト ID の設定（任意）

ユーザーが未ログインの状態で製品を使用したり、未ログイン状態でのゲスト ID を設定する必要がある場合は、identify:を呼び出して設定することができます。

ta.identify("123ABCabc");

ゲスト ID を取得するには、getDistinctIdを呼び出して取得することができます。

//ゲストIDに戻る.マルチインスタンスの場合はインスタンスを呼びだすゲストIDに戻る.
var distinctId = ta.getDistinctId();

# 2.2 アカウント ID の設定

ユーザーがログインするとき、login::を呼び出してユーザーのアカウント ID を設定します。TA プラットフォームはアカウント ID を身分を識別 ID として優先し、設定後のアカウント ID は保存されます。login:を複数回に呼び出すと以前のアカウント ID が上書きされます:

// ユーザーログインの唯一の識別子，このデータはアップロードデータの#account_idに対応し，"#account_id" の値は"ABC_123456"
ta.login("ABC_123456");

// loginを呼び出してアカウントIDを調整，"#account_id" の値は "XYZ_987654"
ta.login("XYZ_987654");

この方法は、ユーザーがログインしたイベント**が**アップロードされません

# 2.3 アカウント ID の削除

ユーザーがログアウトした後、logout てアカウント ID を削除することができます。次のlogoutが呼び出されるまで、ゲスト ID を識別 ID として使用します。

// アップロードデータの#account_idを削除し，以降のデータには"#account_id"を含まない。
ta.logout();

この方法は、**ユーザー**のログアウト**イベント**が**アップロードされません**。

# 3、イベントの送信

# 3.1 イベントアップロード

trackを呼び出してカスタムイベントをアップロードすることができます。前の内容をもとに、イベントのプロパティと情報送信の条件を設定することをお勧めします。

ta.track(
  "Purchase", //イベントの名称を追跡
  {
    Item: "商品A",
    ItemNum: 1,
    Cost: 100,
    Elements: ["apple", "ball", "cat"]
  } //アップロードしたいイベントプロパティ
);
  • trackインターフェイスには 2 つのパラメーターがあり、最初のパラメーターはイベントの名前、2 つ目のパラメーターはイベントのプロパティです。
  • イベントの名前は文字列で、アルファベットで始まり、数字、アルファベット、下線「_」を含むことができ、長さは最大 50 文字で、アルファベットの大文字と小文字を区別しません。
  • イベントのプロパティは JSON 形式のオブジェクトで、要素はKey: Valueの形式で、各要素は 1 つのプロパティを表します。
  • Key の値はプロパティの名前であり、String型で、アルファベットで始まり、数値、アルファベット、下線「_」を含むことができます。長さは最大 50 文字で大文字と小文字を区別しません。
  • Value はプロパティの値であり、String、Number、Boolean、Date、Arrayをサポートします。

    注: Array タイプは v1.3.0 からサポートされており、TA プラットフォーム v2.5 以降と併用する必要があります。

# 3.2 HTML 要素クリックイベントの監視

ページ上の要素のクリックイベントを追跡したい場合は、trackLinkを使用して HTML 要素を一括監視することができます。

ta.trackLink(
  {
    tag: ["a", "button"], //HTMLタグ
    class: ["class1", "class2"], //カスタムClass名称
    id: ["id1", "id2"] //カスタムID名
  }, //要素ルールの監視
  "click", //イベント名称の追跡
  {
    production: "产品名",
    name: "元素标识名"
  } //イベントの属性
);
  • 最初のパラメータは、監視する要素のルールです。JSON オブジェクトタイプで、HTML タグタイプ、Class、および id に基づいて監視するページ要素を追跡し、少なくとも 1 つのルートを選択し DOM 要素の取得をサポートします。ルールを満たす要素については、イベント監視器で要素のクリックイベントを監視し、要素がクリックされるとイベントがアップロードされ、イベント名とイベントプロパティは最後の 2 つのパラメーターの値を取得します。
  • 2 つ目のパラメーターはイベントの名前で、string型で、ルールはtrackインターフェイスのイベント名と一致します。記入は必須です。
  • 3 つ目のパラメーターはイベントのプロパティで、JSON オブジェクトタイプで、アップロードするプロパティがない場合は空の JSON をアップロードすることができます。
  • このインタフェースはイベントプロパティ'name'を要素の識別子として、3 つめのパラメーターにイベントプロパティ'name'を設定していない場合、このインタフェースは以下のロジックに従って、監視される要素の特定のプロパティ値を要素識別子として取得します。値は要素のカスタムプロパティ'td-name'、要素のinnerHTML、要素の value いずれも取得できない場合、'未取得``識別子``'をアップロードします。

    このインターフェイスは、呼び出されたときにルールに準拠した要素にのみイベント監視器を設定するため、インターフェイスが呼び出された後に要素の識別子が変更されたり、ルールに準拠した要素が新たに作成されたりしても、監視したアップロードイベントが変更されません。新しい生成要素を監視するには、ajax で要素が生成された後にインターフェイスを呼び出します。

# 3.3 パブリックイベントプロパティの設定

データを収集する過程で、いくつかのフィールドは複数のイベントに共用されます。例えば、同じページで発生したすべてのイベントは、このページのページ属性を持ち、ユーザーのアカウント情報はすべてのデータに持つべきです。trackでイベントをアップロードするとき、これらのプロパティは毎回設定する必要があります。このようなプロパティに対して、パブリックプロパティでインタフェースを設定し、統一することができます。

# 3.3.1 パブリックプロパティの種類

パブリックプロパティの設定方法を説明する前に、3 種類のパブリックプロパティの特性を理解し、実際のニーズに応じて適切なタイプを選択する必要があります

  • ページパブリックプロパティ:現在のページに有効で優先度が高い。SDK を再初期化すると、ページパブリックプロパティは空になります。固定値のみ設定可能です。
  • 動的パブリックプロパティ:現在のページにのみ有効で、優先度はページパブリックプロパティの次です。SDK を再初期化した後、動的パブリックプロパティを再設定する必要があり、動的変数を設定することができます。
  • 静的パブリックプロパティ:すべてのページに有効で、優先度が最も低く、キャッシュをオンにした場合、localStorage または cookie に保存されます。固定値のみ設定可能です。

# 3.3.2 ページパブリックプロパティの設定

ページの名前やアドレスなど、一部のページの静的プロパティに対して、このページでトリガーされるすべてのイベントにこのプロパティを追加することができます。このようなページ内のすべてのイベントに適用する静的プロパティはsetPagePropertyを使用して設定することができます。setPagePropertyを使用して設定したパブリックプロパティは現在のページにのみ有効です。

// ページIDをページパブリックプロパティに設定.このページでトリガーしたすべてのイベントは以下のプロパティを持つ.
ta.setPageProperty({ page_id: "page10001" });

現在のページのページパブリックプロパティを取得するには、getPagePropertyを呼び出して取得することができます。

// 現在のページのページパブリックプロパティを取得
var pageProperty = ta.getPageProperty();

# 3.3.3 ページ動的パブリックプロパティの設定

v1.1.0 では、ページ動的パブリックプロパティの特性が新たに追加されました。 setDynamicSuperPropertiesを動的パブリックプロパティのコールバック関数を設定し、SDK はイベントアップロード時にコールバック関数をトリガーし、返した JSON オブジェクトをイベントプロパティに追加します。

setDynamicSuperPropertiesのパラメーターは関数であり、JSON オブジェクトを返す必要があります。書式はイベントプロパティと一致する必要があります。

// 動的パブリックプロパティを設定.イベントアップロード時にコールバック関数をトリガーし，返したJSONオブジェクトをイベントプロパティに追加
ta.setDynamicSuperProperties(function() {
  var d = new Date();
  d.setHours(10);
  return { date: d };
});

/*
ta.setDynamicSuperProperties(
    ()=>{
        var d = new Date();
        d.setHours(10);
        return {'date': d}
    });
*/

# 3.3.4 静的パブリックプロパティの設定

ユーザーの加入ルート、ニックネーム、ID など重要なプロパティは、イベントごとに設定する必要があります。setSuperPropertiesを呼び出して、静的パブリックイベントプロパティを設定することができます。キャッシュをオンにすると(デフォルトはオン)、静的パブリックプロパティはlocalStorageまたはcookieに保存されます。

静的パブリックプロパティのパラメーターは JSON オブジェクトであり、書式はイベントプロパティと一致する必要があります。

// パブリックイベントプロパティを設定，すべてのデータイベントにこれらのプロパティを持つ.
ta.setSuperProperties({ channel: "渠道名", user_name: "用户名" });

すべての設定済の静的パブリックプロパティを取得するにはgetSuperProperties、静的パブリックプロパティを削除するにはunsetSuperPropert``y、静的パブリックプロパティをすべて削除するにはclearSuperProperties、すべてのパブリックプロパティを取得するにはgetSuperPropertiesを呼び出すことができます。

// 静的パブリックイベントプロパティを取得
var superProperties = ta.getSuperProperties();

// 1個の静的パブリックイベントプロパティを削除，例えば以前設定したプロパティ'channel'を削除，それ以降のデータはこのプロパティを含まない.
ta.unsetSuperProperty("channel");

// 静的パブリックイベントプロパティを削除
ta.clearSuperProperties();

# 3.4 イベント時間の記録

timeEventを呼び出して時間を記録し、記録したいイベントの名称を設定します。イベントをアップロードすると時間記録が終了し、SDK は自動的にイベントのイベントプロパティに#durationプロパティを追加して時間の長さを表します。単位は秒でtimeEventはページを跨いだ時間記録をサポートしています。

// 時間記録開始，記録するイベントは'Purchase'
ta.timeEvent("Purchase");

// その他のコード

// イベントアップロード，時間記録終了，イベント'Purchase'には時間の長さのプロパティを表すプロパティ"#duration"を持つ
ta.track("Purchase", { Item: "商品A", ItemNum: 1, Cost: 100 });

# 3.5 自動収集ページビューイベント

TA は自動的にページビューイベントを収集するインターフェースを提供しています。次のコードを使用することで、JS SDK は自動的にユーザーのページビューイベントをアップロードします。

ta.quick("autoTrack");

# 4、ユーザープロパティ

# 4.1 ユーザープロパティの設定（userSet）

通常のユーザープロパティは、usersetを呼び出して設定することができます。このインターフェイスを使用してアップロードしたプロパティは、元のプロパティ値を上書きします。過去にこのユーザープロパティが存在しなかった場合は、新しいユーザープロパティが作成され、アップロードしたプロパティ型と同様です。

// ユーザープロパティを設定.会員レベルを設定.
ta.userSet({ vip_level: "钻石会员" });

# 4.2 ユーザープロパティの初期化（userSetOnce）

アップロードするユーザープロパティが 1 回しか設定しない場合、usersetOnceを呼び出して設定することができます。このプロパティは既に値がある場合、この情報が無視されます。

// ユーザー名が設定済の場合，設定を無視.存在しない場合，受信値を設定
ta.userSetOnce({ UserName: "TA" });

# 4.3 ユーザープロパティの累積（userAdd）

数値型プロパティをアップロードするには、user``A``ddを呼び出して、そのプロパティに対して累積操作を行います。そのプロパティが設定されていない場合は、0 を割り当ててから計算します。負の値が渡される場合、減算に相当します。

// 支払いを例として、ユーザーが支払いするたびにこのインターフェースを呼び出し，フィールド'total_revenue'は毎回支払金額の累積処理を行う
しta.userAdd({ total_revenue: 50 });

# 4.4 ユーザープロパティのリセット（userUnset）

ユーザーのユーザープロパティ値を削除したい場合、user``U``nsetを呼び出して指定したプロパティを空にすることができます。そのプロパティはクラスターで作成されていない場合、user``U``nsetがそのプロパティを作成しません。

// ユーザープロパティ名userPropertykeyのユーザープロパティ値を削除，NULLに設定
ta.userUnset("userPropertykey");

# 4.5 ユーザーの削除（userDel）

あるユーザーを削除したい場合、user``Delを呼び出してユーザーを削除することができます。それ以降、このユーザーのユーザープロパティを参照することができなくなるが、発生したイベントを参照することができます。

ta.userDel();

# 4.6 Array 型のデータへの要素追加(userAppend)

v1.3.0 以降、userAppendを呼び出して Array(List)タイプのユーザーデータに要素を追加することができます。

ta.userAppend({ Elements: [("a": 1), ("b": 2)] });

注:この機能は、TA プラットフォーム 2.5 以降と併用する必要があります。

# 5、その他の機能

# 5.1 マルチインスタンス

v1.1.0 では、マルチインスタンスの機能が追加され、initInstanceメソッドを呼び出すことで、サブインスタンスオブジェクトを作成することができます。パラメーターはサブインスタンス名です。この名称でサブインスタンスのインターフェイスを呼び出すことができます。

// インスタンスnewInstanceを作成
ta.initInstance("newInstance");

// サブインスタンスにdistinct_idを設定し、イベントtest_eventを送信
ta.newInstance.identify("new_distinct_id");
ta.newInstance.track("test_event");

デフォルトでは、サブインスタンスはメインインスタンスと同じ設定(appId、serverUrlなど)を採用します。また、デフォルトでサブインスタンスはローカルキャッシュをオンにしません。

サブインスタンスで単独でパラメーターを設定するには、初期化時に構成情報を渡し、構成情報に異なるappId値を渡すことで、異なるプロジェクトにデータをアップロードすることができます。

// サブインスタンスの設定パラメーター
var param = {
  appId: "debug-appid",
  serverUrl: "ANOTHER_SERVER_URL",
  persistenceEnabled: true, // 开启子实例的本地缓存，子实例本地缓存根据子实例名称 name 区分
  send_method: "image",
  showLog: true
};

// サブインスタンスを初期化
ta.initInstance("anotherInstance", param);

//メインインスタンスプロジェクトにデータをアップロード
ta.track("Event");

//サブインスタンスプロジェクトにデータをアップロード
ta.anotherInstance.track("Event");

メインインスタンスとサブインスタンスの ID 体系は共通しておらず、インスタンスごとにユーザー ID を設定することができます。以下のケースはこの特性を通じて、友人を招待するイベントの招待者と被招待者に、それぞれ招待成功と被招待イベントをアップロードしました。

//メインインスタンスは招待された新しいユーザー，サブインスタンスは招待者
ta.login("invitee");
ta.anotherInstance.login("inviter");

//新しいユーザーは招待イベントを起こす.
ta.track("be_invited");

//招待者は新しいユーザーを招待するイベントを起こす.
ta.anotherInstance.track("invite_new_user");

# 5.2 デバイス ID の取得

v1.1.0 では、デバイス ID(プリセットプロパティ#device_id)のインターフェースを追加し、getDeviceIdを呼び出すことでデバイス ID を取得することができます：

var deviceId = ta.getDeviceId();

// デバイスIDをゲストIDに設定する場合、以下のように呼び出す.
// ta.identify(ta.getDeviceId());

# 5.3 デバッグモード

v1.4.0 以降では、初期設定で mode パラメーターを設定することで、Debug モードを有効にすることができます。Debug モードは開発段階のデータ形式検証にのみ使用され、オンライン環境で Debug モードをオンにしないでください。

現在の SDK インスタンスは、2 つのデバッグモードをサポートしています。

  • "debug": Debug インタフェースを介したデータのアップロードと検証
  • "debug_only":検証データのみ、格納しない

Debug はクラスターのパフォーマンスとデータ収集の安定性に影響するため、指定されたデバイスのみ Debug モードをオンにすることができます。Web の Debug が有効で、且つ SDK がランダムに生成したデバイス ID は TA バックグラウンドの埋め込みポイント管理関連ページで設定したデバイスのみ Debug モードを有効にすることができます。

デバイス ID は、次の方法で取得することができます。

  • TA プラットフォームのイベントデータの#device_id プロパティ
  • コンソールログでアップロードされたイベントデータの#device_id フィールド

# 5.4 データアップロードの一時停止/停止

v1.4.2 では、SDK インスタンスのデータアップロードを停止する機能が追加されました。2 つの SDK インスタンスのデータアップロードを停止するインターフェースがあります。

# 5.4.1 SDK アップロードの一時停止（enableTracking）

ユーザーがテスト環境にいる、またはテストアカウントでログインしているなどの場合、データの収集やアップロードを一時的に停止したいことがあります。その場合、次のインターフェイスを呼び出して SDK インスタンスのアップロードを一時的に停止することができます。

特定のインスタンス(メインインスタンスとライトインスタンスを含む)を通してenableTrackingを呼び出し、falseに取り込むことで、SDK インスタンスのアップロードを一時停止することができます。そのインスタンスに設定済の#distinct_id、#account_id、パブリックプロパティなどが保持されます。そのインスタンスが収集したがアップロード未完了のデータは引き続きアップロードされます。そのインスタンスはそれ以降新しいデータを収集したりアップロードしたりすることはできません。ゲスト ID、アカウント ID、パブリックプロパティなどを設定することはできませんが、設定済のパブリックプロパティ、デバイス ID、ゲスト ID、アカウント ID などの情報を読み取ることはできます。

インスタンスの停止状態はenableTrackingが呼び出されるまでローカルのキャッシュに保存されます。enableTrackingを呼び出して、trueに取り込むと、SDK インスタンスはデータ収集とアップロードを再開します。ライトインスタンスはキャッシュに保存されないため、アプリを開くたびにライトインスタンスの一時停止状態は保持されず、アップロードが再開されます。

// アップロードを一時停止
instance.enableTracking(false);

// アップロードを再開
instance.enableTracking(true);

# 5.4.2 SDK アップロードの中止（optOutTracking）

GDPR が適用される地域でユーザーがデータ収集権限を提供しないなどの特殊の場合、次のインターフェイスを呼び出して SDK インスタンスの機能を完全に停止することができます。

optOutTrackingはメインインスタンスからしか呼び出すことができません。enableTrackingとの最大の違いは、インスタンスのローカルキャッシュ(ゲスト ID、アカウント ID、パブリックプロパティ、およびアップロードしていないデータキューを含む)が削除されます。その後、インスタンスの収集とアップロード機能をオフにします。

// アップロードを中止し，ローカルキャッシュをリセット
instance.optOutTracking();

インスタンスの停止状態もoptInTrackingが呼び出されるまでローカルキャッシュに保存されます。それ以降はアップロードを続けることができますが、新しいインスタンスとなります。

// アップロードを再開
instance.optInTracking();

# 7、関連のプリセットプロパティ

次のプリセットプロパティは、JavaScript SDK のすべてのイベント(自動収集イベントを含む)に含まれるプリセットプロパティです。

プロパティ名
 日本語
 説明
#ip
 IPアドレス
 ユーザーのIPアドレス。TAはユーザーの位置情報を取得。
#country
 国
 ユーザーの国。IPアドレスに基づいて生成。
#
country_code
 国コード
 ユーザーがいる国の国コード(ISO 3166-1 alpha-2、2大文字のアルファベット)。IPアドレスに基づいて生成。
#province
 省
 ユーザーがいる省。IPアドレスに基づいて生成。
#city
 都市
 ユーザーがいる都市。IPアドレスに基づいて生成。
#device_id
 デバイスID
 ユーザーのデバイスID
#screen_height
 画面の高さ
 ユーザーのデバイスの画面高さ。例：1920
#screen_width
 画面の幅
 ユーザーのデバイスの画面の幅。例：1080
#lib
 SDKタイプ
 SDKのタイプ。
JavaScript
など。
#lib_version
 SDKバージョン
 SDKのバージョン。
#os
 オペレーティングシステム
 Android、iOSなど
#browser
 ブラウザの種類
 ユーザーが使用するブラウザの種類。
Chrome、Firefoxなど
#browser_version
 ブラウザバージョン
 ユーザーが使用するブラウザのバージョン。Chrome 61.0、Firefox 57.0など
#url
 ページアドレス
 現ページのアドレス。
#url_path
 ページルート
 現ページへのルート
#referrer
 前ページアドレス
 前ページのアドレスに戻る。
#referrer_host
 前ページルート
 前ページのルートに戻る。
#title
 ページタイトル
 現ページのタイトル。
#zone_offset
 タイムゾーンオフセット
 UTC時間に対するデータ時間のオフセット時間数

# 6.1 プリセットプロパティの取得

サーバー側の埋め込みポイントにアプリ側のプリセットプロパティが必要な場合、この方法でアプリ側のプリセットプロパティを取得してサービス側に渡します。

   //プロパティオブジェクトを取得
   var presetProperties = ta.getPresetProperties();

　　//イベントプリセットプロパティの生成
   var properties = presetProperties.toEventPresetProperties();
   /*
    {
      "#os":"Mac OS X",
      "#screen_width":1920,
      "#screen_height":1080,
      "#browser":"chrome",
      "#browser_version":"91.0.4472.114",
      "#device_id":"17a3858fafd9b4-0693d07132e2d1-34657600-2073600-17a3858fafea9b",
      "#zone_offset":8
    }
   */

    //プリセットプロパティの取得
    var os =  presetProperties.os;//os種類，例：Android
    var screenWidth = presetProperties.screenWidth;//画面の幅
    var screenHeight = presetProperties.screenHeight;//画面の高さ
    var browser = presetProperties.browser;//ブラウザの種類
    var browserVersion =  presetProperties.browserVersion;//ブラウザバージョン
    var deviceId = presetProperties.deviceId;//デバイスID
    var zoneOffset = presetProperties.zoneOffset;//タイムゾーンオフセット

IP、国の都市情報はサーバー側で解析して生成されるので、クライアント側はこれらのプロパティを取得するインタフェースを提供しません。

# 7、高度な機能

v1.4.0 以降、SDK は、初期イベント、更新可能なイベント、書き換え可能なイベントとの 3 つの特殊イベントのアップロードをサポートしています。この 3 つのイベントは、TA システム 2.8 以降のバージョンと併用する必要があります。特殊イベントは特定の場面でしか適用されないので、TA のクライアントとアナリストのもとに、特殊イベントのアップロードを行うようにしましょう。

# 7.1 初期イベント

初期イベントとは、あるデバイスや他のディメンションの ID に対して、一度しか記録されないイベントです。たとえば、特定のブラウザで最初に発生したイベントを記録したい場合があります(TA SDK でランダムで生成された#device_id によって一意性を判断)。初期イベントとしてアップロードすることができます。

// 例：初期イベントをアップロード. イベント名は DEVICE_FIRSTに仮定.
ta.trackFirstEvent({
  eventName: "DEVICE_FIRST",
  properties: { INT_PROPERTY: 0 }
});

デバイス以外のディメンションで初回かどうかを判断するには、初期イベントに FIRST_CHECK_ID を設定します。たとえば、あるアカウントの初期イベントを記録する必要がある場合、アカウント ID を初期イベントの FIRST_CHECK_ID に設定します。

// 例：初期イベントをアップロード. イベント名は USER_FIRSTに仮定.
// ユーザーIDを初期イベントのFIRST_CHECK_IDとして設定
ta.trackFirstEvent({
  eventName: "USER_FIRST",
  firstCheckId: "YOUR_ACCOUNT_ID",
  properties: { INT_PROPERTY: 0 }
});

注意:サーバー側で初回かどうかをチェックするため、初期イベントはデフォルトで 1 時間遅れて格納します。

# 7.2 更新可能なイベント

更新可能なイベントを通して、特定の場面でのイベントデータの変更要件を満たすことができます。更新可能なイベントは、イベントを識別する ID を指定し、更新可能なイベントオブジェクトの作成時に読み込むする必要があります。TA プラットフォームは、イベント名とイベント ID に基づいて更新するデータを決定します。

// 例： 更新可能なイベントをアップロード，イベント名は UPDATABLE_EVENTに仮定
ta.trackUpdate({
  eventName: "UPDATABLE_EVENT",
  properties: { status: 3, price: 100 },
  eventId: "test_event_id"
});
// イベントプロパティアップロード後に status は 3, price は 100

ta.trackUpdate({
  eventName: "UPDATABLE_EVENT",
  properties: { status: 5 },
  eventId: "test_event_id"
});
// イベントプロパティアップロード後に status は 5に更新され, price は変わらない

# 7.3 書き換え可能なイベント

書き換え可能なイベントは更新可能なイベントと似ており、違いとしては書き換え可能なイベントは最新のデータで過去データを完全に上書きするので、過去データを削除し、最新のデータを格納することに相当します。TA プラットフォームは、イベント名とイベント ID に基づいて更新するデータを決定します。

// 例： 書き換え可能なイベントをアップロードし，イベント名は OVERWRITE_EVENTに仮定
ta.trackOverwrite({
  eventName: "OVERWRITE_EVENT",
  properties: { status: 3, price: 100 },
  eventId: "test_event_id"
});

// イベントプロパティアップロード後に status は 3, price は 100
ta.trackOverwrite({
  eventName: "OVERWRITE_EVENT",
  properties: { status: 5 },
  eventId: "test_event_id"
});

// イベントプロパティアップロード後に status は 5に更新され, price は削除される

注意:更新可能なイベントと書き換え可能なイベントは、デフォルトでデバイスの現在時間を使用して履歴データのイベント時間を更新します。イベント時間を指定したい場合は、更新可能なイベントを報告するときにイベント時間を指定します。

// trackUpdateを例とし，Date型のeventTimeを取り込み、イベント時間を指定
ta.trackUpdate({
  eventName: "UPDATABLE_EVENT",
  properties: { status: 5 },
  eventId: "test_event_id",
  eventTime: realEventTime
});

# ChangeLog

省略します。詳細は中国語版をご参照ください。