Android - Advanced

アカウントID設定

SDKインスタンスはランダムのUUIDでユーザーのゲストIDとして付与します。ゲストIDはユーザーがログインする前のユーザー識別IDとして使われます。ただし、事前に注意すべきのは、アカウントIDはユーザー再インストールすると変更されます。

1.1 ゲストID設定

::: Tips

一般的には、ゲストIDを手動設定することは不要で、ユーザー識別ルールを確認した上で、ゲストID設定を行なってください。

もしゲストIDを変更したい場合は、SDKを初期設定したあとですぐ呼び出すように設定してください。

:::

独自でゲストIDの管理体制がある場合は、identifyを呼び出して、ゲストIDを設定してください

// set distinct ID as Thinker
instance.identify("Thinker");

現在のゲストIDを取得したい場合は、getDistinctIdを呼び出して取得できます。

//Return distinct ID
String distinctId = instance.getDistinctId();

1.2 アカウントID設定

ユーザーログイン時に、Loginを呼び出してアカウントIDを設定できます。TEはアカウントIDをユーザー身分の識別IDとして使われています。一度設定されたアカウントIDはLogoutを呼び出す前に保存されます。Loginを多数呼び出した場合は、その前のアカウントIDを上書きされます。

// The login unique identifier of the user, corresponding to the #account_id in data tracking. #Account_id now is TE
instance.login("TE");

この方法ではログインイベントとして送信されません

1.3 アカウントIDをクリア

ユーザーがログアウトイベントを行う前に、Logoutを呼び出して、アカウントIDをクリアすることができます。もう一度Loginを呼び出す前にゲストIDはユーザー身分の識別IDとして使われます。

instance.logout();

ユーザーがアカウントを削除する際にLogoutを呼び出すよう設定してください。

ログアウトイベントとして送信されません。

イベント送信

SDKが初期化設定完了後、データプランに応じて、トラッキングコードを実装し、ユーザーの行動データを収集することができます。一般的には、通常イベント送信は十分収集可能で、実際業務シーンによって、初回・更新可能などの特殊イベント収集することも可能です。

2.1 通常イベント

track を呼び出して、データプランに応じてイベントのプロパティを設定の上、データ送信できます。

例：アイテム購入

try {
    JSONObject properties = new JSONObject();
    properties."product_name", "アイテム名");
    instance.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();
}
instance.track(new TDFirstEvent("device_activation", properties));

もしデバイス以外で初回判断したい場合は、first_check_idで初回イベントを定義してください。

//set the user ID as the first_check_id of the first event to track the first initialization event of the user.
TDFirstEvent firstEvent = new TDFirstEvent("account_activation", properties);
firstEvent.setFirstCheckId("TE");
instance.track(firstEvent);

注意：サーバ側で初回なのかを検証するため、初回イベントはデフォルトで1時間遅延して格納されます。

2.3 更新可能イベント

通常イベントはデータを格納されたら更新不可となりますが、データ更新を行いたい場合は、更新可能イベントを利用してください。更新可能イベントは識別イベントのIDが必要で、作成時はプロパティに入れてください。TEシステムはイベント名とイベントIDを識別対象として更新データを確定します。

 //The event property status is 3 after reporting, with the price being 100
JSONObject properties = new JSONObject();
try {
    properties.put("status", 3);
    properties.put("price", 100);
} catch (JSONException e) {
    e.printStackTrace();
}
mInstance.track(new TDUpdatableEvent("UPDATABLE_EVENT", properties, "test_event_id"));

//The event property status is 5 after reporting, with the price remaining the same
JSONObject properties_new = new JSONObject();
try {
    properties_new.put("status", 5);
} catch (JSONException e) {
    e.printStackTrace();
}
mInstance.track(new TDUpdatableEvent("UPDATABLE_EVENT", properties_new, "test_event_id"));

2.4 書き替えイベント

書き替えイベントは更新可能イベントと同じようで、書き替えイベントは過去データを最新のデータで上書きされるため、前のデータを削除し新しくデータを格納するように見られます。TEシステムはイベント名とイベントIDを識別対象として更新データを確定します。

// Instance: Assume the event name is OVERWRITE_EVENT when reporting an overwritable event
//The event property status is 3 after reporting, with the price being 100
JSONObject properties = new JSONObject();
try {
    properties.put("status", 3);
    properties.put("price", 100);
} catch (JSONException e) {
    e.printStackTrace();
}
mInstance.track(new TDOverWritableEvent("OVERWRITE_EVENT", properties, "test_event_id"));

//The event property status is 5 after reporting, with the price deleted
JSONObject properties_new = new JSONObject();
try {
    properties_new.put("status", 5);
} catch (JSONException e) {
    e.printStackTrace();
}
mInstance.track(new TDOverWritableEvent("OVERWRITE_EVENT", properties_new, "test_event_id"));

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

共通イベントプロパティは全てのイベント送信する際に付属されているプロパティとなります。プロパティの更新頻度により、共通イベントプロパティは静的共通イベントプロパティと動的共通イベントプロパティがあります。

実際業務ニーズに応じて、共通イベントプロパティの設定を行なってください；通常イベント送信する前に、共通イベントプロパティを設定してくのはオススメです。

同じイベントに、共通イベントプロパティ、イベントカスタムプロパティ、プリセットプロパティのKeyは同じの場合は、以下の優先順位で値付けされます。カスタムプロパティ＞動的共通イベントプロパティ＞静的共通イベントプロパティ＞プリセットプロパティ

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

静的共通イベントプロパティは低頻度変化かつ全てのイベントの属しているプロパティ：例えばVIPレベル。setSuperPropertiesを利用して、静的共通イベントプロパティを設定したら、SDKはイベント収集時に設定されている共通イベントプロパティを当イベントのプロパティとして利用されます。

//set super properties
try {
    JSONObject superProperties = new JSONObject();
    superProperties.put("vip_level",2);
    instance.setSuperProperties(superProperties);
} catch (JSONException e) {
    e.printStackTrace();
}

静的共通イベントプロパティはキャッシュに保存されるため、APPを起動するたびに呼び出す必要はありません。もしそのプロパティが存在されているのであれば、新たに設定するプロパティは元のプロパティ値を書き替えされます；もし以前そのプロパティが存在しない場合は、新規プロパティとして作成されます。プロパティ設定以外にはAPI利用で静的共通イベントプロパティを管理できます。

//clear a certain super property
instance.unsetSuperProperty("Channel");
//clear all certain super properties
instance.clearSuperProperties();
//obtain all certain super properties
instance.getSuperProperties();

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

動的共通イベントプロパティは高頻度変化かつ全てのイベントに属しているプロパティです。（例えばコインの数量）setDynamicSuperPropertiesTrackerを利用し動的共通イベントプロパティを設定した後で、SDKはイベント収集時に自動でgetDynamicSuperPropertiesのプロパティを取得し、イベント送信されます。

int coin = 0;
instance.setDynamicSuperPropertiesTracker(
    new ThinkingAnalyticsSDK.DynamicSuperPropertiesTracker() {
        @Override
        public JSONObject getDynamicSuperProperties() {
            Coin++;//frequency update of gold coin quantity 
            try {
                dynamicSuperProperties.put("coin",coni);
            } catch (JSONException e) {
                e.printStackTrace();
            }
            return dynamicSuperProperties;
        }
    });

2.6 イベント時間記録

イベントの経過時間を記録したい場合は、timeEventを呼び出して計算可能です。計算したいイベント名称を設定し、該当イベントが送信される際に、自動的にイベントプロパティに#durationのプロパティを追加され、経過時間を記録されます。単位は秒です。

注意：一つイベントに対しては一個の時間経過計算タスクのみつけることが可能です。

//The following instance has recorded the time the user spent on a certain product page
try {
    //The user enters the product page and starts the timing
    instance.timeEvent("stay_shop");
    /**do someting
    .......
    **/
    //the timing would end when the user leaves the product page. "stay_shop" event would carry#duration, a property representing event duration. 
    instance.track("stay_shop");
} catch (JSONException e) {
    e.printStackTrace();
}

ユーザープロパティ

TEでユーザープロパティを設定するAPIはuser_set、user_setOnce、user_add、user_unset、user_delete、user_append、user_uniqAppend。

3.1 user_set

一般的にユーザープロパティ設定はuser_setを用いて設定できます。この呼び出しを利用して元のプロパティ値を書き替えされます。元のプロパティ値がない場合は、新規作成になります。データタイプは格納されたデータタイプと一致します。以下は例：

try {
    //the username now is TA
    JSONObject properties = new JSONObject();
    properties.put("username","TA");
    instance.user_set(properties);
    //the userName now is TE
    JSONObject newProperties = new JSONObject();
    newProperties.put("username","TE");
    instance.user_set(newProperties);
} catch (JSONException e) {
    e.printStackTrace();
}

3.2 user_setOnce

もしユーザープロパティは一回設定の上で変更がない場合は、user_setOnceを用いて設定できます。この呼び出しは値のある際に書き替えを行いません。例：初回課金時間設定

try {
    //first_payment_time is 2018-01-01 01:23:45.678
    JSONObject properties = new JSONObject();
    properties.put("first_payment_time","2018-01-01 01:23:45.678");
    instance.user_setOnce(properties);
    
    //first_payment_time is still 2018-01-01 01:23:45.678
    JSONObject newProperties = new JSONObject();
    newProperties.put("first_payment_time","2018-12-31 01:23:45.678");
    instance.user_setOnce(newProperties); 
       
} catch (JSONException e) {
    e.printStackTrace();
}

3.3 user_add

もし数値型のプロパティで累積計算を行いたい場合は、user_addを用いて設定できます。この呼び出しは値のない際に自動で0を付与した上で計算されます。“-”値で計算することも可能で、例：累積課金金額

try {
    //in this case, the total_revenue is 30
    JSONObject properties = new JSONObject();additive operation
    properties.put("total_revenue",30);
    instance.user_add(properties);
    
    //in this case, the total_revenue is 678
    JSONObject newProperties = new JSONObject();
    newProperties.put("total_revenue",648);
    instance.user_add(newProperties);
} catch (JSONException e) {
    e.printStackTrace();
}

3.4 user_unset

ユーザープロパティをリセットしたい場合は、user_unsetを用いて設定できます。もしそのプロパティはクラスターで作成されていない場合は、user_unsetはそのプロパティを作成されません。

// reset properties of a single user
instance.user_unset("key1");
// reset properties of several users
instance.user_unset("key1", "key2", "key3");

3.5 user_delete

ユーザーを削除したい場合はuser_deleteを用いて設定できます。削除したら当ユーザーのユーザープロパティはクエリできなくなりますが、当ユーザーが生成したイベントデータはクエリできます。

instance.user_delete();

3.6 user_append

user_appendを用いて、List型のユーザープロパティを追加できます。

try {
    // list is the value of user property user_list, JSONArray type
    JSONArray list = new JSONArray("[\"apple\", \"ball\"]");
    JSONObject properties = new JSONObject();
    properties.put("user_list", list);
    // call user_append to add elements for user property user_list. In this case, mon-existing elements would be newly created
    mInstance.user_append(properties);
} catch (JSONException e) {
    e.printStackTrace();
}

3.7 user_uniqAppend

v2.8.0 以降のバージョンは、user_uniqAppendを用いてArray型のユーザープロパティを追加できます。

user_uniqAppendは重複排除でユーザープロパティを追加されますが、user_appendは重複排除しません。

try {
    // list is the value of user property user_list, JSONArray type
    //in this case, the property value of user_list is ["apple"，"ball"]
    JSONArray list = new JSONArray("[\"apple\", \"ball\"]");
    JSONObject properties = new JSONObject();
    properties.put("user_list", list);
    mInstance.user_append(properties);
    
    
    //in this case, the property value of user_list is ["apple","apple","ball","cube"]
    JSONArray list1 = new JSONArray("[\"apple\", \"cube\"]");
    JSONObject properties1 = new JSONObject();
    properties1.put("user_list", list1);
    mInstance.user_append(properties1);
    
    //in this case, the property value of user_list is ["apple"，"ball","cube"]
    mInstance.user_uniqAppend(properties1);
    
} catch (JSONException e) {
    e.printStackTrace();
}

暗号化機能

v2.8.0 以降のバージョンは、SDKデータ送信にAES+RSA暗号化を対応できるようになりました。データの暗号化処理はクライアントとサーバと合わせて処理となります、詳しくは弊社担当スタッフまでご連絡ください。

TDConfig config = TDConfig.getInstance(mContext,TA_APP_ID,TA_SERVER_URL);
//Enable the encryption function
config.enableEncrypt(true);
TDSecreteKey secreteKey = new TDSecreteKey();
secreteKey.publicKey = "publicKey";
secreteKey.version = 1;
secreteKey.symmetricEncryption = "AES";
secreteKey.asymmetricEncryption = "RSA";
//set public key information
config.setSecretKey(secreteKey);

H5ページとの連携

H5ページデータのJavaScript SDK との連携をしたい場合は、初期化WebView 設定時に以下の呼び出しを有効にしてください。詳しくは H5とAPP SDKの連携

// connect with H5 
instance.setJsBridge(webView);

その他機能

6.1 デバイスIDを取得

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

 String deviceID = instance.getDeviceId();//the value of device ID is Android ID

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

デフォルトでSDKは本デバイスの表示時間をイベント発生時間として送信されます。デフォルトタイムゾーンを指定することも可能です。

// get TDConfig instance
TDConfig config = TDConfig.getInstance(this, TE_APP_ID, TE_SERVER_URL);
// set UTC as the default timezone
config.setDefaultTimeZone(TimeZone.getTimeZone("UTC"));
// initialize SDK
instance = ThinkingAnalyticsSDK.sharedInstance(config);

タイムゾーン指定したら、本デバイスのタイムゾーンのデータが破棄されます。もし本デバイスのタイムゾーンを保留したい場合は、別途イベントにカスタムプロパティを追加してください。

6.3 時間校正

SDK デフォルトで本デバイス時間をイベント発生時間として利用されますが、ユーザーが手動でデバイスの時間を修正したりするとそのまま修正後の時間として送信されますため、分析に支障が出てしまいます。時間校正を利用して、イベント発生時間の正確性を保つことができます。TEシステムはtimestampと NTPの二つの時間校正方法を対応しております。

• サーバ側から同期された現在のtimestampを使ってSDKの時間を校正できます。その後、全て時間未指定の呼び出し（イベントデータとユーザープロパティ設定）は校正後の時間を発生時間として使われます。

// 1585633785954 is the current unix time stamp, with the unit tokyo millisecond; the corresponding tokyo time is 2020-03-31 13:49:45
ThinkingAnalyticsSDK.calibrateTime(1585633785954);

• NTPサーバアドレス設定でSDKはNTPサービスの当地時間を取得し利用されます。デフォルトで時間オーバー（3秒）して取得できなかった場合は、ローカル時間として送信されます。

//use the NTP service of Apple Inc for time calibration 
ThinkingAnalyticsSDK.calibrateTimeWithNtp("time.apple.com");

1、NTPサービスで時間校正を行うには不安定性があり、timestampを推奨しております。

2、NTPサービスを利用する場合は、ネット環境が良好で、ユーザーデバイスは素早くサーバ時間を取得可能できるのを保つ必要があります。

6.4 即時データ送信

一般的には一定の時間間隔で、または一定のデータ量を貯めてからデータ送信となりますが、特定のイベントデータを即時にデータ送信したい場合はflushを用いて設定できます。

ta.flush();

6.5 国/地域コード取得

国/地域コード取得したい場合はgetLocalRegionを用いて取れます。

ThinkingAnalyticsSDK.getLocalRegion()