メインコンテンツまでスキップ

応用ガイド

最終更新 2026/10/05

1. ユーザーIDの設定​

SDKインスタンスは、デフォルトで乱数を各ユーザーのデフォルトのゲストIDとして使用します。このIDは、ユーザーが未ログインの状態での識別IDとして使われます。なお、ゲストIDはユーザーがキャッシュを削除した場合やデバイスを変更した場合に変わります。

1.1 ゲストIDの設定​

ヒント

通常、ゲストIDをカスタマイズする必要はありません。ユーザー識別ルールを理解したうえで、ゲストIDを設定してください。

Appにユーザーごとの独自のゲストID管理体系がある場合は、setDistinctIdを呼び出してゲストIDを設定できます：

// ゲストIDをThinkerに設定
TDAnalytics.setDistinctId("Thinker");

現在のゲストIDを取得する必要がある場合は、getDistinctIdを呼び出して取得できます：

//ゲストIDを返す
TDAnalytics.getDistinctId();

設定する場合は、初期化の前にこのインターフェースを呼び出す必要があります

1.2 アカウントIDの設定​

ユーザーがログインする際にloginを呼び出して、ユーザーのアカウントIDを設定できます。AEプラットフォームはアカウントIDを識別IDとして使用し、設定したアカウントIDはlogoutを呼び出すまで保持されます。loginを複数回呼び出すと、以前のアカウントIDが上書きされます。

//ユーザーのログインの一意な識別子です。このデータは送信データの#account_idに対応し、この場合#account_idの値はTAになります
TDAnalytics.login("TA");

このメソッドはログインイベントを送信しません

1.3 アカウントIDのクリア​

ユーザーがログアウトした後にlogoutを呼び出して、アカウントIDをクリアできます。次にloginを呼び出すまでは、ゲストIDが識別IDとして使われます。

// 送信データから"#account_id"を削除し、以降のデータには"#account_id"が含まれなくなります
TDAnalytics.logout();

logoutは、明示的なログアウトイベントのときに呼び出すことを推奨します。たとえば、ユーザーがアカウントからログアウトする操作を行ったときにのみ呼び出し、Appを閉じるときに呼び出す必要はありません。

このメソッドはログアウトイベントを送信しません

2. イベントの送信​

SDKの初期化が完了したら、データのトラッキングを行い、ユーザーの行動情報を収集できます。通常は通常イベントで業務シナリオの要件を満たせますが、実際の業務シナリオに応じて、初回イベントや更新可能イベントなどを使用することもできます。

2.1 通常イベント​

trackを呼び出してイベントを送信できます。事前に整理したドキュメントに従って、イベントのプロパティとイベントの送信条件を設定することをお勧めします。ここでは、ユーザーが商品を購入する場合を例にします

TDAnalytics.track("product_buy", // イベント名
    {
        product_name: "商品名"
    } //イベントプロパティ
);

2.2 初回イベント​

初回イベントとは、デバイスまたはその他のディメンションのIDに対して、1回だけ記録されるイベントのことです。たとえば、あるデバイスでのアクティベーションイベントを記録したい場合は、初回イベントでデータを送信できます。

TDAnalytics.trackFirst("device_activation",{ key: "value" });

デバイス以外のディメンションで初回かどうかを判定したい場合は、初回イベントのfirst_check_idをカスタマイズできます：

// ユーザーIDを初回イベントのfirst_check_idに設定し、ユーザーの初回アクティベーションイベントを収集
TDAnalytics.trackFirst("account_activation",{ key: "value" },"TA");

注意：初回かどうかの検証はサーバー側で行われるため、初回イベントはデフォルトで1時間遅れて取り込まれます。

2.3 更新可能イベント​

更新可能イベントを使用すると、特定のシナリオでイベントデータを変更する必要がある場合に対応できます。更新可能イベントでは、そのイベントを識別するIDを指定し、更新可能イベントのオブジェクトを作成する際に渡す必要があります。AE管理画面は、イベント名とイベントIDに基づいて更新するデータを特定します。

// 例：更新可能なイベントを送信。イベント名はUPDATABLE_EVENTとします
// 送信後、イベントプロパティstatusは3、priceは100になります
TDAnalytics.trackUpdate("UPDATABLE_EVENT",{ status: 3, price: 100 },"test_event_id");

// 送信後、イベントプロパティstatusは5に更新され、priceは変わりません
TDAnalytics.trackUpdate("UPDATABLE_EVENT",{ status: 5 },"test_event_id");

2.4 上書き可能イベント​

上書き可能イベントは更新可能イベントと似ていますが、上書き可能イベントでは最新のデータで過去のデータを完全に上書きする点が異なります。効果としては、前のデータを削除して最新のデータを格納するのと同じです。AE管理画面は、イベント名とイベントIDに基づいて更新するデータを特定します。

// 例：上書き可能なイベントを送信。イベント名はOVERWRITE_EVENTとします
// 送信後、イベントプロパティstatusは3、priceは100になります
TDAnalytics.trackOverwrite("OVERWRITE_EVENT",{ status: 3, price: 100 },"test_event_id");

// 送信後、イベントプロパティstatusは5に更新され、priceプロパティは削除されます
TDAnalytics.trackOverwrite("OVERWRITE_EVENT",{ status: 5 },"test_event_id");

2.5 共通イベントプロパティ​

ユーザーのデバイスID、流入チャネル、ユーザーステータスなどの重要なプロパティは、すべてのイベントに設定する必要があります。その場合、これらのプロパティを共通プロパティ、つまりすべてのイベントに含まれるプロパティとして設定できます。イベントを送信する前に、共通プロパティを設定しておくことを推奨します。

共通プロパティには、静的共通イベントプロパティと動的共通イベントプロパティの2種類があります。イベントの送信時に、共通プロパティはデータのpropertiesに挿入されます。このとき、共通プロパティとイベントで設定したカスタムプロパティに同じkeyがある場合は、次の優先順位に従ってどの値を採用するかが判断されます：カスタムプロパティ>動的共通イベントプロパティ>静的共通イベントプロパティ>プリセットプロパティ。

2.5.1 静的共通イベントプロパティ​

ユーザーのチャネル、ニックネーム、IDなどの重要なプロパティは、すべてのイベントに設定する必要があります。setSuperPropertiesを呼び出して静的共通イベントプロパティを設定でき、静的共通イベントプロパティはグローバルに適用されます。キャッシュが有効な場合（デフォルトで有効）、静的共通プロパティはキャッシュされ、次回の起動時にも引き続き有効です。

静的共通プロパティのパラメーターはJSONオブジェクトで、形式の要件はイベントプロパティと同じです。

// 共通イベントプロパティを設定すると、すべてのデータのイベントにこれらのプロパティが含まれます
TDAnalytics.setSuperProperties({
     channel: "チャネル名",
     user_name: "ユーザー名"
});

プロパティの設定以外にも、静的共通イベントプロパティを操作するためのAPIを提供しており、日常的な業務要件に対応できます。

// 静的共通イベントプロパティを取得
TDAnalytics.getSuperProperties();
// 静的共通イベントプロパティを1つクリアします。たとえば、以前に設定した'channel'プロパティをクリアすると、以降のデータにはこのプロパティが含まれなくなります
TDAnalytics.unsetSuperProperty("channel");
// すべての静的共通イベントプロパティをクリア
TDAnalytics.clearSuperProperties();

2.5.2 動的共通イベントプロパティ​

setDynamicSuperPropertiesで動的共通プロパティのコールバック関数を設定すると、SDKはイベントの送信時にコールバック関数をトリガーし、返されたJSONオブジェクトをイベントプロパティに追加します。setDynamicSuperPropertiesのパラメーターは関数で、関数はJSONオブジェクトを返す必要があります。

// 動的共通プロパティを設定。イベント送信時にコールバック関数がトリガーされ、返されたJSONオブジェクトがイベントプロパティに追加されます
TDAnalytics.setDynamicSuperProperties(function() {
    var d = new Date();
    d.setHours(10);
    return { date: d };
});

2.6 イベントの所要時間の記録​

あるイベントの継続時間を記録する必要がある場合は、timeEventを呼び出して計測を開始できます。計測したいイベント名を設定しておくと、そのイベントを送信する際に、記録した時間を表す#durationプロパティがイベントプロパティに自動的に追加されます。単位は秒です。なお、同じイベント名で計測中のタスクは1つしか持てません。

//以下の例では、ユーザーが特定の商品ページに滞在した時間を集計します
TDAnalytics.timeEvent("stay_shop");
/**do someting
    .......
**/
//ユーザーが商品ページを離れ、計測を終了。"stay_shop"イベントには、イベントの所要時間を表すプロパティ#durationが付与されます
TDAnalytics.track("stay_shop",{product_name:"商品名"});

3. ユーザープロパティ​

AEプラットフォームがサポートしているユーザープロパティ設定APIは次のとおりです：userSet、userSetOnce、userAdd、userUnset、userDelete、userAppend、userUniqAppend。

3.1 userSet​

一般的なユーザープロパティは、userSetを呼び出して設定できます。このインターフェースで送信したプロパティは、既存のプロパティ値を上書きします。そのユーザープロパティが以前に存在しない場合は新しく作成され、タイプは渡されたプロパティのタイプと同じになります。ここでは、ユーザー名の設定を例にします：

// usernameはTA
TDAnalytics.userSet({
    username: "TA" 
});
//usernameはAE
TDAnalytics.userSet({
    username: "AE" 
});

3.2 userSetOnce​

送信するユーザープロパティを一度だけ設定すればよい場合は、userSetOnceを呼び出して設定できます。そのプロパティにすでに値がある場合、この情報は無視されます。ここでは、初回課金時間の設定を例にします：

//first_payment_timeは2018-01-01 01:23:45.678
TDAnalytics.userSetOnce({
    first_payment_time: "2018-01-01 01:23:45.678" 
});
//first_payment_timeは引き続き2018-01-01 01:23:45.678
TDAnalytics.userSetOnce({
    first_payment_time: "2018-12-31 01:23:45.678" 
});

3.3 userAdd​

数値型のプロパティを送信する場合は、userAddを呼び出してそのプロパティを累積加算できます。そのプロパティがまだ設定されていない場合は、0を代入してから計算します。負の値を渡すと、減算と同じになります。

//この時点でtotal_revenueは30
TDAnalytics.userAdd({
    total_revenue: 30
});
//この時点でtotal_revenueは678
TDAnalytics.userAdd({
    total_revenue: 648
});

3.4 userUnset​

ユーザーのユーザープロパティ値をクリアする場合は、userUnsetを呼び出して、指定したプロパティをクリアできます。そのプロパティがまだクラスター内で作成されていない場合、userUnsetはそのプロパティを作成しません。

// このユーザーの、ユーザープロパティ名がuserPropertykeyのユーザープロパティ値をクリアします（NULLに設定）
TDAnalytics.userUnset("userPropertykey");

3.5 userDelete​

あるユーザーを削除する場合は、userDeleteを呼び出してそのユーザーを削除できます。削除後はそのユーザーのユーザープロパティを照会できなくなりますが、そのユーザーが発生させたイベントは引き続き照会できます。

TDAnalytics.userDelete();

3.6 userAppend​

userAppendを呼び出して、配列型のユーザーデータに要素を追加できます。

TDAnalytics.userAppend({
    user_list: ["apple", "ball"]
});

3.7 userUniqAppend​

userUniqAppendを呼び出して、Array (List)型のユーザーデータに一意の要素を追加できます。userUniqAppendインターフェースを呼び出すと、追加するユーザープロパティの重複が排除されます。userAppendインターフェースでは重複は排除されないため、ユーザープロパティに重複が存在する場合があります。

//この時点でuser_listのプロパティ値は["apple"，"ball"]
TDAnalytics.userAppend({
    user_list: ["apple", "ball"]
});
//この時点でuser_listのプロパティ値は["apple","apple","ball","cube"]
TDAnalytics.userAppend({
    user_list: ["apple", "cube"]
});
//この時点でuser_listのプロパティ値は["apple"，"ball","cube"]
TDAnalytics.userUniqAppend({
    user_list: ["apple", "cube"]
});

4. 暗号化機能​

SDKは暗号化機能に対応しています。クライアントはAES+RSAでデータを暗号化し、サーバー側でデータを復号します。暗号化・復号機能はクライアントとサーバーの連携が必要です。詳しくはカスタマーサクセス担当者にお問い合わせください。

enableEncryptプロパティをtrueに設定し、デフォルトのバージョン番号と公開鍵を設定します。

var config = {
  appId: "YOUR_APP_ID", // プロジェクトのAPP ID
  serverUrl: "YOUR_SERVER_URL", // 送信先URL
  enableEncrypt: true, // データ転送の暗号化を有効化
  secretKey: {
    publicKey:'YOUR_PUBLIC_KEY', // 暗号化用の公開鍵
    version:0 // 鍵のバージョン番号
   }
};
// 初期化
TDAnalytics.init(config);

5. その他の機能​

5.1 デバイスIDの取得​

getDeviceId()を呼び出してデバイスIDを取得できます。

TDAnalytics.getDeviceId();

デバイスIDはキャッシュに保存されるため、ユーザーがキャッシュを削除するとデバイスIDはリセットされます。

5.2 イベントのキャッシュ送信の設定​

初期化時にイベントのキャッシュ送信を有効にするよう設定できます。現時点ではuni-appのみ対応しています。Android、iOS、HarmonyOSプラットフォームではデフォルトでキャッシュによる一括送信が使用され、別途設定することはできません。

// AE SDKの設定オブジェクト
var config = {
  appId: "YOU-APP-ID", // プロジェクトのAPP ID
  serverUrl: "https://youserverurl.com", // データの送信先URL
  enableBatch: true, // イベントのキャッシュ一括送信を有効にするかどうか。true=有効、false=無効
  batchConfig: {
    size: 5, // イベントのキャッシュ送信件数
    interval: 5000 // イベントのキャッシュ送信間隔（ミリ秒）
  }
};
// 初期化
TDAnalytics.init(config);

5.3 デフォルトタイムゾーンの設定​

デフォルトでは、SDKはインターフェースを呼び出した時点の端末のローカル時間をイベント発生時間として送信します。v3.0.3以降では、初期化時にデフォルトタイムゾーンを設定することもでき、その場合、すべてのイベントのイベント時間は設定したタイムゾーンに合わせて揃えられます：

var config = {
  appId: "YOU-APP-ID", // プロジェクトのAPP ID
  serverUrl: "https://youserverurl.com", // データの送信先URL
  zoneOffset:8
};

注意：指定したタイムゾーンでイベント時間を合わせると、デバイスのローカルタイムゾーンの情報は失われます。デバイスのローカルタイムゾーンの情報を保持する必要がある場合は、現時点ではイベントに関連プロパティを自分で追加する必要があります。

このページは役に立ちましたか？
このページの内容