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

応用ガイド

最終更新 2026/10/02

1. ユーザー識別子の設定​

SDKインスタンスは、デフォルトでランダムなUUIDを各ユーザーのデフォルトのゲストIDとして使用します。このIDは、ユーザーが未ログイン状態のときの識別IDとして使われます。なお、ゲストIDは、ユーザーがAppを再インストールしたり、デバイスを変更したりすると変わります。

1.1 ゲストIDの設定​

ヒント

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

ゲストIDを置き換える必要がある場合は、SDKの初期化が完了した直後に呼び出してください。不要なアカウントが生成されないよう、複数回呼び出さないでください

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

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

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

//ゲストIDを返す
String distinctId = 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として使われます。

TDAnalytics.logout();

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

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

2. イベントの送信​

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

2.1 通常イベント​

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

//ショップでの購入イベント
try {
    JSONObject properties = new JSONObject();
    properties.put("product_name","商品名");
    TDAnalytics.track("product_buy",properties);
} catch (JSONException e) {
    e.printStackTrace();
}

2.2 初回イベント​

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

JSONObject properties = new JSONObject();
try {
    properties.put("key", "value");
} catch (JSONException e) {
    e.printStackTrace();
}

TDAnalytics.track(new TDFirstEventModel("device_activation", properties));

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

// ユーザーIDを初回イベントのfirst_check_idに設定し、ユーザーの初回アクティベーションイベントを収集します
TDFirstEventModel model = new TDFirstEventModel("device_activation", properties);
model.setFirstCheckId("TA");
TDAnalytics.track(model);

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

2.3 更新可能イベント​

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

// 例：更新可能なイベントを送信します。イベント名はUPDATABLE_EVENTとします
// 送信後、イベントプロパティstatusは3、priceは100になります
JSONObject properties = new JSONObject();
try {
    properties.put("status", 3);
    properties.put("price", 100);
} catch (JSONException e) {
    e.printStackTrace();
}
TDAnalytics.track(new TDUpdatableEventModel("UPDATABLE_EVENT", properties, "test_event_id"));
// 送信後、イベントプロパティstatusは5に更新され、priceは変わりません
JSONObject properties_new = new JSONObject();
try {
    properties_new.put("status", 5);
} catch (JSONException e) {
    e.printStackTrace();
}
TDAnalytics.track(new TDUpdatableEventModel("UPDATABLE_EVENT", properties_new, "test_event_id"));

2.4 上書き可能イベント​

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

// 例：上書き可能なイベントを送信します。イベント名はOVERWRITE_EVENTとします
// 送信後、イベントプロパティstatusは3、priceは100になります
JSONObject properties = new JSONObject();
try {
    properties.put("status", 3);
    properties.put("price", 100);
} catch (JSONException e) {
    e.printStackTrace();
}
TDAnalytics.track(new TDOverWritableEventModel("OVERWRITE_EVENT", properties, "test_event_id"));
// 送信後、イベントプロパティstatusは5に更新され、priceプロパティは削除されます
JSONObject properties_new = new JSONObject();
try {
    properties_new.put("status", 5);
} catch (JSONException e) {
    e.printStackTrace();
}
TDAnalytics.track(new TDOverWritableEventModel("OVERWRITE_EVENT", properties_new, "test_event_id"));

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

共通イベントプロパティとは、すべてのイベントで送信されるプロパティのことです。プロパティの更新頻度に応じて、共通イベントプロパティは静的共通イベントプロパティと動的共通イベントプロパティに分けられます。具体的な業務シナリオの要件に応じて、異なる共通イベントプロパティの設定方法を選択できます。イベントを送信する前に、共通イベントプロパティを設定しておくことを推奨します。同じイベントで、共通イベントプロパティ、イベントのカスタムプロパティ、プリセットプロパティのKeyが同じ場合は、次の優先順位で値が設定されます：カスタムプロパティ>動的共通イベントプロパティ>静的共通イベントプロパティ>プリセットプロパティ。

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

静的共通イベントプロパティとは、変化の頻度が低く、すべてのイベントに含まれるプロパティのことです（ユーザーの会員レベルなど）。setSuperPropertiesで静的共通イベントプロパティを設定すると、SDKはイベントの収集時に、設定された共通イベントプロパティをイベントのプロパティとして取得します。

//共通イベントプロパティを設定
try {
    JSONObject superProperties = new JSONObject();
    superProperties.put("vip_level",2);
    TDAnalytics.setSuperProperties(superProperties);
} catch (JSONException e) {
    e.printStackTrace();
}

静的共通イベントプロパティはキャッシュに保存されるため、Appを起動するたびに呼び出す必要はありません。そのプロパティがすでに存在する場合は、再設定したプロパティで元のプロパティ値が上書きされます。そのプロパティが存在しない場合は、新しく作成されます。プロパティの設定以外にも、静的共通イベントプロパティを管理するためのAPIを提供しており、日常的な業務要件に対応できます。

//特定の共通イベントプロパティをクリア
TDAnalytics.unsetSuperProperty("Channel");
//すべての共通イベントプロパティをクリア
TDAnalytics.clearSuperProperties();
//すべての共通イベントプロパティを取得
TDAnalytics.getSuperProperties();

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

動的共通イベントプロパティとは、変化の頻度が高く、すべてのイベントに含まれるプロパティのことです（ユーザーのコイン数など）。setDynamicSuperPropertiesTrackerで動的共通プロパティのクラスを設定すると、SDKはイベントの収集時にgetDynamicSuperProperties内のプロパティを自動的に取得し、トリガーされたイベントに追加します。

int coin = 0;
TDAnalytics.setDynamicSuperProperties(new TDAnalytics.TDDynamicSuperPropertiesHandler() {
    @Override
    public JSONObject getDynamicSuperProperties() {
        JSONObject dynamicSuperProperties = new JSONObject();
        coin++;//コインの数は頻繁に更新されます
        try {
            dynamicSuperProperties.put("coin",coin);
        } catch (JSONException e) {
            e.printStackTrace();
        }
        return dynamicSuperProperties;
    }
});

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

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

//以下の例では、ユーザーがある商品ページに滞在した時間を集計します
try {
    //ユーザーが商品ページに入ったら計測を開始
    TDAnalytics.timeEvent("stay_shop");
    /**do someting
    .......
    **/
    //ユーザーが商品ページを離れたら計測を終了。"stay_shop"イベントには、イベントの所要時間を表すプロパティ#durationが含まれます
    TDAnalytics.track("stay_shop");
} catch (JSONException e) {
    e.printStackTrace();
}

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

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

3.1 userSet​

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

try {
    //この時点でusernameはTA
    JSONObject properties = new JSONObject();
    properties.put("username","TA");
    TDAnalytics.userSet(properties);
    //この時点でuserNameはAE
    JSONObject newProperties = new JSONObject();
    newProperties.put("username","TE");
    TDAnalytics.userSet(newProperties);
} catch (JSONException e) {
    e.printStackTrace();
}

3.2 userSetOnce​

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

try {
    //first_payment_timeは2018-01-01 01:23:45.678
    JSONObject properties = new JSONObject();
    properties.put("first_payment_time","2018-01-01 01:23:45.678");
    TDAnalytics.userSetOnce(properties);
    
    //first_payment_timeは引き続き2018-01-01 01:23:45.678
    JSONObject newProperties = new JSONObject();
    newProperties.put("first_payment_time","2018-12-31 01:23:45.678");
    TDAnalytics.userSetOnce(newProperties); 
       
} catch (JSONException e) {
    e.printStackTrace();
}

3.3 userAdd​

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

try {
    //この時点でtotal_revenueは30
    JSONObject properties = new JSONObject();
    properties.put("total_revenue",30);
    TDAnalytics.userAdd(properties);
    
    //この時点でtotal_revenueは678
    JSONObject newProperties = new JSONObject();
    newProperties.put("total_revenue",648);
    TDAnalytics.userAdd(newProperties);
} catch (JSONException e) {
    e.printStackTrace();
}

3.4 userUnset​

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

// 単一のユーザープロパティをリセット
TDAnalytics.userUnset("key1");
// 複数のユーザープロパティをリセット
TDAnalytics.userUnset("key1", "key2", "key3");

3.5 userDelete​

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

TDAnalytics.userDelete();

3.6 userAppend​

userAppendを呼び出して、配列型のユーザープロパティに要素を追加できます。

try {
    // listはユーザープロパティuser_listの値で、JSONArray型です
    JSONArray list = new JSONArray("[\"apple\", \"ball\"]");
    JSONObject properties = new JSONObject();
    properties.put("user_list", list);
    // user_appendを呼び出して、ユーザープロパティuser_listに要素を追加します。存在しない場合は、その要素が新しく作成されます
    TDAnalytics.userAppend(properties);
} catch (JSONException e) {
    e.printStackTrace();
}

3.7 userUniqAppend​

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

try {
    // listはユーザープロパティuser_listの値で、JSONArray型です
    //この時点でuser_listのプロパティ値は["apple"，"ball"]
    JSONArray list = new JSONArray("[\"apple\", \"ball\"]");
    JSONObject properties = new JSONObject();
    properties.put("user_list", list);
    TDAnalytics.userAppend(properties);
    
    
    //この時点でuser_listのプロパティ値は["apple","apple","ball","cube"]
    JSONArray list1 = new JSONArray("[\"apple\", \"cube\"]");
    JSONObject properties1 = new JSONObject();
    properties1.put("user_list", list1);
    TDAnalytics.userAppend(properties1);
    
    //この時点でuser_listのプロパティ値は["apple"，"ball","cube"]
    TDAnalytics.userUniqAppend(properties1);
    
} catch (JSONException e) {
    e.printStackTrace();
}

4. 暗号化機能​

v2.8.0以降、SDKはAES+RSAによるデータの暗号化に対応しています。データ暗号化機能はクライアントとサーバーの連携が必要です。具体的な使用方法については、カスタマーサクセス担当者にお問い合わせください。

TDConfig config = TDConfig.getInstance(mContext,TA_APP_ID,TA_SERVER_URL);
//暗号化機能を有効にし、公開鍵情報を設定
config.enableEncrypt(1,"publicKey")

5. H5ページとの連携を有効化​

H5ページのデータを収集するJavaScript SDKと連携する必要がある場合は、WebViewの初期化時に次のインターフェースを呼び出します。詳細はH5とAPP SDKの連携の節を参照してください

// H5ページのデータを連携
TDAnalytics.setJsBridge(webView);

6. その他の機能​

6.1 デバイスIDの取得​

getDeviceIdを呼び出して、デバイスIDを取得できます：

String deviceID = TDAnalytics.getDeviceId();//デバイスIDにはAndroid IDを使用

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

デフォルトでは、SDKは端末のローカル時間をイベント発生時間として使用します。デフォルトタイムゾーンを設定するインターフェースでタイムゾーンを指定することもでき、その場合、すべてのイベントのイベント時間は設定したタイムゾーンに合わせて揃えられます：

// TDConfigインスタンスを取得
TDConfig config = TDConfig.getInstance(this, TA_APP_ID, TA_SERVER_URL);
// デフォルトタイムゾーンをUTCに設定
config.setDefaultTimeZone(TimeZone.getTimeZone("UTC"));
// SDKを初期化
TDAnalytics.init(config);

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

6.3 時間の補正​

SDKはデフォルトで端末のローカル時間をイベント発生時間として使用します。ユーザーがデバイスの時間を手動で変更すると業務分析に影響が出るため、その場合は時間の補正を行うことで、イベント発生時間の正確性を確保できます。时间戳、NTP（タイムスタンプ、NTP）の2種類の時間補正方法を提供しています。

  • サーバーから取得した現在のタイムスタンプを使用して、SDKの時間を補正できます。以降、時間を指定していないすべての呼び出し（イベントデータやユーザープロパティの設定操作を含む）では、補正後の時間が発生時間として使用されます。
// 1585633785954は現在のunixタイムスタンプ（単位はミリ秒）で、北京時間の2020-03-31 13:49:45に相当します
TDAnalytics.calibrateTime(1585633785954);
  • NTPサーバーのアドレスを設定することもできます。設定後、SDKは渡されたNTPサービスのアドレスから現在時刻を取得し、SDKの時間を補正しようとします。デフォルトのタイムアウト時間（3秒）以内に正しい結果が返されなかった場合、以降はローカル時間でデータを送信します。
// Apple社のNTPサービスを使用して時間を補正
TDAnalytics.calibrateTimeWithNtp("time.apple.com");

1. NTPサービスによる時間補正には一定の不確実性があるため、タイムスタンプによる補正方法を優先的に検討することを推奨します

2. ネットワーク状況が良好な場合にユーザーのデバイスがすばやくサーバー時間を取得できるよう、NTPサーバーのアドレスは慎重に選択してください

6.4 データの即時送信​

業務シナリオによっては、データをすぐにAEサーバーに送信したい場合があります。その場合はflushインターフェースを呼び出します

TDAnalytics.flush();

6.5 国/地域コードの取得​

業務シナリオによっては、ユーザーのデバイスの国/地域コードを知る必要がある場合があります。その場合はgetLocalRegionで取得できます

TDAnalytics.getLocalRegion();

6.6 AndroidIDの取得を禁止​

プロジェクト内にAndroid IDを収集するコードを含めたくない場合は、プラグインを使用して機密プロパティ（AndroidIDなど）のコードを分離できます。

Android分析SDKのバージョンプラグインのバージョン
[oldest - 3.0.0)1.2.0
[3.0.0 - 3.1.0]2.1.0
(3.1.0 - latest]2.2.0
  buildscript {
     repositories {
         google()
         jcenter()
     }
     dependencies {
         classpath 'cn.thinkingdata.android:android-gradle-plugin2:2.2.0'
      }
}
// Configure disableAndroidID to true in the project build.gradle file
apply plugin: 'cn.thinkingdata.android'
android {}
ThinkingAnalytics {
    debug = true
    sdk{
        disableAndroidID = true
     }
}

パラメーターの詳細：

  • debug：コンパイルログを出力するかどうか。trueでコンパイルログを出力します。デフォルトはfalseです。
  • exclude：特定のパスにあるクラスをスキャン対象から除外します。exclude = ['cn.thinkingdata.android','android.support']のように設定できます。
  • useInclude、include：特定のパスにあるクラスのみをスキャンしたい場合は、useInclude = true、include= ['cn.thinkingdata.android','android.support']のように設定できます。
  • disableAndroidID：システムAPIを呼び出してAndroidIDを取得することを無効にするかどうか。プラグインV2.1.0以降、disableAndroidID = trueを設定することで構成できます。

6.7 IPによるデータ送信のサポート​

DNSハイジャックによってクライアントのデータがサーバーに正常に送信できなくなる問題を予防・解決するため、SDKはServerUrlを解析してIPを取得し、IPを使って直接サーバーにデータを送信します。有効化の例は次のとおりです：

TDConfig config = TDConfig.getInstance(this, APPID, TE_SERVER_URL);
List<TDConfig.TDDNSService> list = new ArrayList<>();
list.add(TDConfig.TDDNSService.CLOUD_ALI);
list.add(TDConfig.TDDNSService.CLOUD_FLARE);
list.add(TDConfig.TDDNSService.CLOUD_GOOGLE);
config.enableDNSService(list);

6.8 sdkエラーコールバックのサポート​

注記

Android SDKのバージョン>=3.2.0が必要です

場合によっては、ネットワークリクエストが失敗したときにカスタム処理を行いたいことがあります。その場合はerrorCallbackを登録できます。有効化の例は次のとおりです：

TDAnalytics.registerErrorCallback(new TDAnalytics.TDSendDataErrorCallback() {
    @Override
    public void onSDKErrorCallback(int code, String errorMsg, String ext) {
        // todo
    }
});

codeのエラーコード

エラーコード説明
1001ネットワークリクエストの失敗

6.9 初期化時の設定情報の取得を無効化​

3.4.0以降、SDKの初期化時に設定情報を取得する必要がない場合は、disableRConfigで無効にできます。具体的なコードは次のとおりです：

TDConfig config = TDConfig.getInstance(this, APPID, TE_SERVER_URL);
config.disableRConfig = true;
TDAnalytics.init(config);

6.10 バックアップ用データ受信URLの設定​

3.4.0以降、複数のデータ受信URLを設定する必要がある場合は、backupUrlListで設定できます。サンプルコードは次のとおりです：

TDConfig config = TDConfig.getInstance(this, APPID, TE_SERVER_URL);
List<String>  backupUrlList = new ArrayList<>();
backupUrlList.add("serverurl1");
backupUrlList.add("serverurl2");
backupUrlList.add("serverurl3");
config.backupUrlList = backupUrlList;
TDAnalytics.init(config);
このページは役に立ちましたか？
このページの内容