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

応用ガイド

最終更新 2026/10/03

1. ユーザーIDの設定​

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

1.1 ゲストIDの設定​

ヒント

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

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

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

[TDAnalytics setDistinctId:@"Thinker"];

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

NSString *distinctId = [TDAnalytics getDistinctId];

1.2 アカウントIDの設定​

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

[TDAnalytics login:@"TD"];

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

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

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

[TDAnalytics logout];

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

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

2. イベントの送信​

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

2.1 通常イベント​

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

NSDictionary *eventProperties = @{@"product_name": @"book"};
[TDAnalytics track:@"product_buy" properties:eventProperties];

2.2 初回イベント​

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

TDFirstEventModel *firstModel = [[TDFirstEventModel alloc] initWithEventName:@"device_activation"];
firstModel.properties = @{@"key":@"value"};
[TDAnalytics trackWithEventModel:firstModel];

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

TDFirstEventModel *firstModel = [[TDFirstEventModel alloc] initWithEventName:@"device_activation" firstCheckID:@"TD"];
firstModel.properties = @{@"key":@"value"};
[TDAnalytics trackWithEventModel:firstModel];

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

2.3 更新可能イベント​

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

// 例：更新可能なイベントを送信します。イベント名はUPDATABLE_EVENTとします
// 送信後、イベントプロパティstatusは3、priceは100になります
TDUpdateEventModel *updateModel = [[TDUpdateEventModel alloc] initWithEventName:@"UPDATABLE_EVENT" eventID:@"test_event_id"];
updateModel.properties = @{@"status": @3, @"price": @100};
[TDAnalytics trackWithEventModel:updateModel];

// 送信後、イベントプロパティstatusは5に更新され、priceは変わりません
TDUpdateEventModel *updateModelNew = [[TDUpdateEventModel alloc] initWithEventName:@"UPDATABLE_EVENT" eventID:@"test_event_id"];
updateModelNew.properties = @{@"status": @5};
[TDAnalytics trackWithEventModel:updateModelNew];

2.4 上書き可能イベント​

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

// 例：上書き可能なイベントを送信します。イベント名はOVERWRITE_EVENTとします
// 送信後、イベントプロパティstatusは3、priceは100になります
TDOverwriteEventModel *overwriteModel = [[TDOverwriteEventModel alloc] initWithEventName:@"OVERWRITE_EVENT" eventID:@"test_event_id"];
overwriteModel.properties = @{@"status": @3, @"price": @100};
[TDAnalytics trackWithEventModel:overwriteModel];

// 送信後、イベントプロパティstatusは5になり、priceプロパティは削除されます
TDOverwriteEventModel *overwriteModel_new = [[TDOverwriteEventModel alloc] initWithEventName:@"OVERWRITE_EVENT" eventID:@"test_event_id"];
overwriteModel_new.properties = @{@"status": @5};
[TDAnalytics trackWithEventModel:overwriteModel_new];

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

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

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

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

[TDAnalytics setSuperProperties:@{@"vip_level": @(2)}];

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

// 特定の共通イベントプロパティをクリアします。以前に設定した"isTest"プロパティをクリア
[TDAnalytics unsetSuperProperty:@"isTest"];

// すべての共通イベントプロパティをクリア
[TDAnalytics clearSuperProperties];

//すべての共通イベントプロパティを取得
[TDAnalytics getSuperProperties];

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

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

// 動的共通プロパティを設定し、イベント送信時にイベントの発生時刻を動的に取得
[TDAnalytics setDynamicSuperProperties:^NSDictionary * _Nonnull{
    return @{@"now": [NSDate date]};
}];

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

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

// 以下の例では、ユーザーがある商品ページに滞在した時間を集計します
[TDAnalytics timeEvent:@"stay_shop"];
    /*
     do someting .......
     */
// ユーザーが商品ページを離れたら計測を終了。"stay_shop"イベントには、イベントの所要時間を表すプロパティ#durationが含まれます
[TDAnalytics track:@"stay_shop"];

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

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

3.1 userSet​

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

//この時点で"username"は"ThinkingData"
[TDAnalytics userSet:@{@"username": @"ThinkingData"}];
//この時点で"username"は"TA"
[TDAnalytics userSet:@{@"username": @"TA"}];

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はそのプロパティを作成しません

// このユーザーの累積課金額プロパティの値をクリア
[TDAnalytics userUnset:@"total_revenue"];

3.5 userDelete​

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

[TDAnalytics userDelete];

3.6 userAppend​

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

// userAppend を呼び出して、ユーザープロパティ product_buy に要素を追加します。存在しない場合は、その要素が新しく作成されます
[TDAnalytics userAppend:@{@"product_buy": @[@"apple", @"ball"]}];

3.7 userUniqAppend​

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

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. 暗号化機能​

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

TDConfig *sdkConfig = [[TDConfig alloc] initWithAppId:appid serverUrl:url];
NSString *publicKey = @"MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCzA......QIDAQAB";
// バージョン番号や公開鍵などの鍵情報を設定
[sdkConfig enableEncryptWithVersion:1 publicKey:publicKey];
[TDAnalytics startAnalyticsWithConfig:sdkConfig];

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

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

WKWebViewConfiguration *config = [[WKWebViewConfiguration alloc] init];
config.applicationNameForUserAgent = [NSString stringWithFormat:@"%@ %@", config.applicationNameForUserAgent ?: @"", @"/td-sdk-ios"];

6. その他の機能​

6.1 デバイスIDの取得​

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

[TDAnalytics getDeviceId];

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

デフォルトでは、SDKはインターフェースを呼び出した時点の端末のローカル時間をイベント発生時間として送信します。デフォルトタイムゾーンを設定するインターフェースで既定のタイムゾーンを指定することもできます。これにより、すべてのイベントのイベント時間が設定したタイムゾーンに合わせられます：

TDConfig *config = [[TDConfig alloc] init];
// デフォルトタイムゾーンをUTCに設定
config.defaultTimeZone = [NSTimeZone timeZoneWithName:@"UTC"];
[TDAnalytics startAnalyticsWithConfig:config];

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

6.3 時間の補正​

SDKはデフォルトで端末のローカル時間をイベント発生時間として送信します。ユーザーがデバイスの時間を手動で変更すると業務分析に影響が出るため、その場合は時間の補正を行うことで、イベント発生時間の正確性を確保できます。タイムスタンプ、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"];
  • NTPサービスによる時間補正には一定の不確実性があるため、タイムスタンプによる補正方法を優先的に検討することを推奨します
  • ネットワーク状況が良好な場合にユーザーのデバイスがすばやくサーバー時間を取得できるよう、NTPサーバーのアドレスは慎重に選択してください

6.4 データの即時送信​

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

[TDAnalytics flush];

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

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

[TDAnalytics getLocalRegion];

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

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

NSString *appId = @"appId";
NSString *serverUrl = @"serverUrl";
TDConfig *config = [[TDConfig alloc] initWithAppId:appId serverUrl:serverUrl];

[config enableDNSServcie:@[TDDNSServiceCloudALi, TDDNSServiceCloudGoogle, TDDNSServiceCloudFlare]];
    
[TDAnalytics startAnalyticsWithConfig:config];

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

注記

SDKバージョン>=3.3.0が必要です

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

[TDAnalytics registerErrorCallback:^(NSInteger code, NSString * _Nullable errorMsg, NSString * _Nullable ext) {
   
}];

codeのエラーコード

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

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

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

#import <ThinkingSDK/ThinkingSDK.h>

NSString *appid = @"APPID";
NSString *url = @"SERVER_URL";

TDConfig *config = [[TDConfig alloc] init];
config.appid = appid;
config.serverUrl = url;
config.disableRConfig = true;
[TDAnalytics startAnalyticsWithConfig:config];

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

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

#import <ThinkingSDK/ThinkingSDK.h>

NSString *appid = @"APPID";
NSString *url = @"SERVER_URL";

TDConfig *config = [[TDConfig alloc] init];
config.appid = appid;
config.serverUrl = url;
config.backupUrlList = @[@"serverUrl1", @"serverUrl2"];
[TDAnalytics startAnalyticsWithConfig:config];
このページは役に立ちましたか？
このページの内容