目录
此内容是否有帮助?

# Unity SDK 利用ガイド

TIP

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

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

Unity SDKをサポートするシステム：iOS、Android、Unity Editor、Windows、Mac、WebGL、Switch

必要な最低システムバージョンは5.4.0で、サイズは約320KBです。

**最新バージョン：**v2.2.5

**更新時間：**2022-01-17

ダウンロード (opens new window)

Unity SDK v2.0.0は過去のバージョンと大きな変化があり、自動収集ポリシーを修正し、アップロード遅延ロジックを削除しました。現在は古いバージョンを使用している場合は過去バージョンのUnity SDK使用ガイドをご参照ください。

# 1、SDKの初期化

# 1.1 SDK統合

  1. Unity SDK (opens new window)をダウンロードし、プロジェクトにインポートします:Assets>Import Package>Custom Package。ダウンロードしたファイルを選択してください。
  2. プリセットThinkingAnalytics を追加し、SDKを設定します。

上図の設定：

設定

  • **Start Manually：**手動初期化を有効にするかどうか。有効にするには、StartThinkingAnalyticsを呼び出してSDKを手動で初期化する必要があります。有効にしない場合、ThinkingAnalyticsプリセットがロードされたときに自動的に初期化されます。手動TAインスタンス初期化をご参考ください。
  • **Enable Log：**ログをオンにするかどうか。オンにすると、デバッグできるようにレポートが印刷されます。Editorモードで、イベントが正しくアップロードされているかどうかを確認し、条件を満たさないプロパティはwarningログでコンソールに表示されます。
  • Network Type**：**データをサーバーにアップロードするネットワーク条件を設定します。デフォルトはDEFAULT。以下はすべてのオプションの説明です。
    • **DEFAULT：**2G、3G、4G、5GおよびWIFI環境でデータをアップロード
    • WIFI： WIFI環境でのみデータをアップロード
    • **ALL：**2G、3G、4G、5GおよびWIFI環境でデータをアップロード

Tokens

各Tokenは1つのインスタンスを識別します。複数のプロジェクトにデータをアップロードするには、右下の「+」をクリックしてプロジェクト設定を追加します。複数プロジェクトの注意事項は本節末の「複数プロジェクトサポート」を参照してください。異なるAPP IDを持つ複数のToken設定を追加することができます。

  • APP ID:設定が必要です。プロジェクトのAPP_IDは、プロジェクトを申請するときに表示されます。ここに入力してください。
  • SERVER URL:データ受信側のURLで設定が必要です。
    • クラウドサービスを使用している場合は、次のURLを入力してください。
      • https://ta-receiver.thinkingdata.io
    • オンプレミスを使用している場合は、次のURLを入力してください。
      • https://数据采集地址
  • MODE: SDKインスタンス実行モードで、生成環境は必ずNORMALモードを使用してください。詳細はSDKモードをご参照ください。
  • TimeZone: v1.4.3からサポートし、デフォルトの校正タイムゾーンです。校正タイムゾーンを指定した場合、データの時刻とプロパティのDateTimeタイプは指定したタイムゾーンに合わせて校正されます。

注:一部のデバイスはデフォルトで平文転送を禁止しているため、HTTPS形式の受信側アドレスを使用することをお勧めします。

# TAインスタンスの手動初期化

  • ThinkingAnalyticsプリセットの読み込み
// 手動初期化（プリセットThinkingAnalyticsは読み込み済）
ThinkingAnalyticsAPI.StartThinkingAnalytics();
  • ThinkingAnalyticsAPIスクリプトの動的マウント
// 手動初期化（動的マウント ThinkingAnalyticsAPI）
gameObject.AddComponent(typeof(ThinkingAnalyticsAPI));

// インスタンスパラメーターの設定
string appId = "YOUR_APP_ID";
string serverUrl = "YOUR_SERVER_ID";
ThinkingAnalyticsAPI.StartThinkingAnalytics(appId, serverUrl);

// インスタンスパラメーターのカスタマイズ
string appId = "YOUR_APP_ID";
string serverUrl = "YOUR_SERVER_ID";
ThinkingAnalyticsAPI.TAMode mode = ThinkingAnalyticsAPI.TAMode.NORMAL;
ThinkingAnalyticsAPI.TATimeZone timeZone = ThinkingAnalyticsAPI.TATimeZone.Local;
ThinkingAnalyticsAPI.Token token = new ThinkingAnalyticsAPI.Token(appId, serverUrl, mode, timeZone);
ThinkingAnalyticsAPI.StartThinkingAnalytics(token);

// 複数プロジェクトのインスタンスの初期化
string appId_2 = "YOUR_APP_ID_2";
string serverUrl_2 = "YOUR_SERVER_ID_2";
ThinkingAnalyticsAPI.TAMode mode_2 = ThinkingAnalyticsAPI.TAMode.NORMAL;
ThinkingAnalyticsAPI.TATimeZone timeZone_2 = ThinkingAnalyticsAPI.TATimeZone.Local;
ThinkingAnalyticsAPI.Token token_2 = new ThinkingAnalyticsAPI.Token(appId_2, serverUrl_2, mode_2, timeZone_2);

ThinkingAnalyticsAPI.Token[] tokens = new ThinkingAnalyticsAPI.Token[2];
tokens[0] = token;
tokens[1] = token_2;
ThinkingAnalyticsAPI.StartThinkingAnalytics(tokens);

# 複数プロジェクトのサポート

SDKを設定する時、複数のAPP IDを追加すると、APIを呼び出されるときに、最後にパラメーターが追加されAPP IDが指定されます。インターフェースIdentify()を例にします：

// APP IDは“debug-appid” 的APP IDインスタンスにゲストIDを設定
ThinkingAnalyticsAPI.Identify("unity_debug_id", "debug-appid");

注:ゲストID、アカウントID、パブリックプロパティなどは複数のプロジェクトで共有されず、APP IDインスタンスごとに個別に設定する必要があります。

APP IDのパラメーターがない場合、デフォルトでリストの最初のAPPIDインスタンス(Token IDの後にdefault識別子があるインスタンス)が使用されます。リスト項目をドラッグすることで、デフォルトのAPP IDインスタンスを調整することができます。

setDefaultAppidを呼び出してデフォルトのAPP IDを変更することもできます。

// ほかのAPP IDをデフォルトプロジェクトIDとして設定
ThinkingAnalyticsAPI.setDefaultAppid("debug-appid-2");
// trackイベントを呼び出し，具体的なAPP IDが読み込まれない場合，デフォルトでイベントデータをプロジェクト<debug-appid-2>にアップロード
ThinkingAnalyticsAPI.track("test_event");

# 1.2 SDKの使用

SDKの設定が完了すると、SDKでイベントをアップロードイベントすることができます。以下のサンプルをご参照ください。

using ThinkingAnalytics;

// テストイベントをアップロード, unity_startはイベント名
ThinkingAnalyticsAPI.Track("unity_start");

# 2、ユーザーIDの設定

Unity SDKが使用されると、ランダムなUUIDをユーザーのデフォルトのゲストIDとして使用します。ゲストIDは、ユーザーが未ログイン状態でユーザーを識別するIDになります。しかし、アプリを再インストールしたり、デバイスを変更したりすると、ゲストIDが変更されます。

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

ゲームは各ユーザーに対して独自のゲストID管理システムがある場合、identifyでゲストIDを設定します:

ThinkingAnalyticsAPI.Identify("unity_id");

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

ThinkingAnalyticsAPI.GetDistinctId();

# 2.2 アカウントIDの設定と削除

ユーザーがログインする時、loginを呼び出してユーザーのアカウントIDを設定することができます。アカウントIDを設定した後、アカウントIDを識別IDとして設定し、設定したアカウントIDはlogoutが呼び出されるまで保持します。

// アカウントIDの設定
ThinkingAnalyticsAPI.Login("unity_user");

// アカウントIDの削除
ThinkingAnalyticsAPI.Logout();

注意:この方法はユーザーがログイン/ログアウトしたイベントがアップロードされません。

# 3、イベントの送信

ThinkingAnalyticsAPI. Track（）でイベントをアップロードすることができます。通常、数十から数百の異なるイベントをアップロードする必要があります。TAを初めて使用する場合は、いくつかの重要なイベントをアップロードすることをお勧めします。

ゲームの起動、終了、異常、インストールなどの自動収集イベントもサポートしています。ビジネスニーズに応じて、自動収集イベントをオンにするか否かを選択します。

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

前の内容をもとに、イベントのプロパティと情報送信の条件を設定することをお勧めします。イベント名はstring型で、アルファベットで始まり、数値、アルファベット、下線「_」を含むことができます。長さは最大50文字で大文字と小文字を区別しません。

Dictionary<string, object> properties = new Dictionary<string, object>()
    {
        {"KEY_DateTime", DateTime.Now.AddDays(1)},
        {"KEY_STRING", "B1"},
        {"KEY_BOOL", true},
        {"KEY_NUMBER", 50.65}
    };
ThinkingAnalyticsAPI.Track("TEST_EVENT", properties);
  • イベントプロパティはDictionary<string, object>型で、各要素は1つのプロパティを表します。
  • イベントプロパティKeyはプロパティ名で、string型で、アルファベットで始まり、数値、アルファベット、下線「_」を含むことができます。長さは最大50文字で大文字と小文字を区別しません。
  • プロパティ値は、文字列、数値、bool、DateTime、List``List<string>、Dictionary<string, object>、List<Dictionary<string, object>の5種類をサポートします。

注意: Listタイプはv1.4.0以降のバージョンからサポートされ、その要素はすべてstringに変換され、格納されます。

Track()を呼び出す時、SDKはシステムの現在時間をイベントの発生時間として取得し、イベント時間を指定したい場合、DateTime型のパラメーターを渡してイベント時間トリガーを設定します。バージョン1.3.0以降、SDKはDataTimeKindでイベントのタイムゾーンオフセットのアップロードを(プリセットプロパティ#zone_offsetに対応)をサポートしますが、受信したDateTimeのKindプロパティはDataTimeKind.Unspecifiedの場合、タイムゾーンオフセットはアップロードされません：

DateTime dateTime = DateTime.Now.AddDays(-1);
ThinkingAnalyticsAPI.Track("TEST_EVENT", properties, dateTime);

v1.4.3以降、SDKインスタンスのデフォルトのタイムゾーンを構成することができます。Local以外のタイムゾーンを設定すると、すべてのイベント時間がそのタイムゾーンに揃い、受信したDateTimeのKindプロパティは無視されます。

v2.0.0以降、SDKは時間校正インターフェイスを提供し、サーバー時間を用いてSDK時間を校正します。詳細は時間校正を参照してください。

注意:イベントは時間トリガーを設定することができますが、受信側は次のように制限し、システム時間の10日前から3日後までのデータしか受信しません。期間を超えたデータは異常データとみなされ、データ全体は格納されません。

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

ユーザーの会員ランク、加入ルートなどの重要なプロパティは、イベントごとに設定する必要があり、パブリックイベントのプロパティとして設定することができます。パブリックイベントプロパティは各イベントに含まれるプロパティのことです。setSuperPropertiesを呼び出してパブリックイベントプロパティを設定することができます。イベントを送信する前に、パブリックイベントプロパティを設定することをお勧めします。

Dictionary<string, object> superProperties = new Dictionary<string, object>()
    {
        {"SERVER", 0},
        {"CHANNEL", "A3"}
    };
ThinkingAnalyticsAPI.SetSuperProperties(superProperties);

パブリックイベントプロパティはキャッシュに保存され、アプリを起動するたびに呼び出す必要はありません。SetSuperPropertiesを呼び出して設定済みのパブリックイベントプロパティをアップロードすると、プロパティが上書きされます。パブリックイベントプロパティはTrack()でアップロードされたプロパティのKeyと重複している場合、そのイベントのプロパティがパブリックイベントプロパティを上書きします。

パブリックイベントプロパティを削除するには、UnsetSuperProperty()を呼び出して、パブリックイベントプロパティを削除します。すべてのパブリックイベントプロパティを削除するには、clearSuperProperties``()を呼び出します。すべてのパブリックイベントプロパティを取得するには、getSuperPropertiesを呼び出します。

// パブリックイベントCHANNELを削除
ThinkingAnalyticsAPI.UnsetSuperProperty("CHANNEL");

//すべてのパブリックイベントプロパティを削除
ThinkingAnalyticsAPI.ClearSuperProperties();

//すべてのパブリックイベントプロパティを取得
ThinkingAnalyticsAPI.GetSuperProperties();

# 3.3 動的パブリックプロパティの設定

パブリックプロパティの値は定数でない場合、動的パブリックプロパティを設定することで実現することができます。動的パブリックプロパティもすべてのイベントに追加され、イベントアップロード時に実際の値が動的に取得されます。

動的パブリックプロパティを設定するには、まず動的パブリックプロパティクラスの新規作成、IDynamicSuperPropertiesインターフェイスの実装、publicDictionary<string, object>GetDynamicSuperProperties()メソッドの上書きが必要です。このメソッドの戻り値は、設定する動的パブリックプロパティです。次にSetDynamicSuperPropertiesを呼び出して動的パブリックプロパティを取り込みます。

using ThinkingAnalytics;

// 動的パブリックプロパティの定義，この例はUTC時間の動的パブリックプロパティの設定
public class DynamicProp : IDynamicSuperProperties
{
    public Dictionary<string, object> GetDynamicSuperProperties()
    {
        return new Dictionary<string, object>() {
            {"KEY_UTCTime", DateTime.UtcNow}
        };
    }
}

ThinkingAnalyticsAPI.SetDynamicSuperProperties(new DynamicProp());

注意:イベントプロパティに名前が重複される場合、動的パブリックプロパティの優先度がパブリックプロパティより高いが、Trackで設定されたイベントプロパティよりも低いです。

# 3.4 イベント時間の記録

あるイベントの継続時間を記録するにはTimeEvent()を呼び出して記録し、イベント名を設定します。このイベントをアップロードする際に、自動的にイベントプロパティに#durationプロパティを追加し、記録時間を秒単位で表します。

// TimeEventを呼び出し、イベントTIME_EVENTの時間記録を開始
ThinkingAnalyticsAPI.TimeEvent("TIME_EVENT");

// do some thing...

// TrackでイベントTIME_EVENTをアップロードし，プロパティ#durationを追加
ThinkingAnalyticsAPI.Track("TIME_EVENT");

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

TAプラットフォームが現在サポートしているユーザープロパティ設定インターフェイスはUserSet、UserSetOnce、UserAdd、UserUnset、UserDelete、UserAppendです。

# 4.1 UserSet

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

ThinkingAnalyticsAPI.UserSet(new Dictionary<string, object>()
    {
        {"USER_PROP_NUM", 0},
        {"USER_PROP_STRING", "A3"}
    });

イベントプロパティと同様:

  • ユーザープロパティはDictionary<string, object>型で、各要素は1つのプロパティを表します。
  • イベントプロパティKeyはプロパティ名で、string型で、アルファベットで始まり、数値、アルファベット、下線「_」を含むことができます。長さは最大50文字で大文字と小文字を区別しません。
  • プロパティ値は、文字列、数値、bool、DateTime、Listとの4種類をサポートします。

注意: Listはv1.4.0以降のバージョンでサポートされ、その要素はすべてstringに変換され入庫されます。

# 4.2 UserSetOnce

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

ThinkingAnalyticsAPI.UserSetOnce(new Dictionary<string, object>()
    {
        {"USER_PROP_NUM", -50},
        {"USER_PROP_STRING", "A3"}
    });

注意: UserSetOnce設定のユーザープロパティタイプと制限条件はUserSetと一致します。

# 4.3 UserAdd

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

ThinkingAnalyticsAPI.UserAdd(new Dictionary<string, object>()
    {
        {"USER_PROP_NUM", -100.9},
        {"USER_PROP_NUM2", 10.0}
    });

注意: 設定したユーザープロパティ型およびKey値の制限はUserSetと一致するが、Valueは数値型のみが許可されます。

# 4.4 UserUnset

ユーザーのユーザープロパティ値を削除したい場合、user``U``nsetを呼び出して指定したプロパティを空にすることができます。このインターフェースは文字型かリスト型のパラメーターをサポートします：

// 単一のユーザープロパティを削除
ThinkingAnalyticsAPI.UserUnset("userPropertyName");

// 複数のユーザープロパティを削除
List<string> listProps = new List<string>();
listProps.Add("aaa");
listProps.Add("bbb");
listProps.Add("ccc");

ThinkingAnalyticsAPI.UserUnset(listProps);

# 4.5 ユーザー削除

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

ThinkingAnalyticsAPI.UserDelete();

# 4.6 UserAppend

v1.4.0からUserAppendを呼び出してListタイプのユーザープロパティに要素を追加することができます:

List<string> stringList = new List<string>();
stringList.Add("apple");
stringList.Add("ball");
stringList.Add("cat");

// プロパティ名がUSER_LISTのユーザープロパティに3つの要素を追加
ThinkingAnalyticsAPI.UserAppend(new Dictionary<string, object>
    {
        {"USER_LIST", stringList }
    });

# 5、イベントの自動収集

# 5.1 自動収集イベントの開始

v2.0.0以降から、EnableAutoTrackを呼び出してAUTO_TRACK_EVENTSを読み込むことで指定したイベントの自動収集を開始することができます。

// 自動収集イベントタイプ
[Flags]
public enum AUTO_TRACK_EVENTS
{
    NONE = 0,
    APP_START = 1 << 0,
    APP_END = 1 << 1,
    APP_CRASH = 1 << 4,
    APP_INSTALL = 1 << 5,
    ALL = APP_START | APP_END | APP_INSTALL | APP_CRASH
}

自動収集イベントの説明は次のとおりです。

  • APP_START:ゲームがフロントに入るとta_app_startがトリガーされ、プリセットプロパティ#resume_from_backgroundは再起動するかどうかを示します。
  • APP_END:ゲームがバックグラウンドに入ると、ta_app_endがトリガーされ、プリセットプロパティ#durationのフィールドはゲームの継続時間を秒単位で示します。
  • APP_CRASH:捕獲されていない異常が発生するとta_app_crashがトリガーされ、現在はAndroidプラットフォームで仮想マシンの未捕獲異常を処理します。iOSプラットフォームはUnixシグナル異常とNSException異常を処理します。
  • APP_INSTALL:アプリが最初にインストールされた後に開いたときはta_app_installがトリガーされます。再インストールするかどうかは区別しません。この時間はインストール後に一度のみアップロードし、その後の更新はアップロードしません。

AUTO_TRACK_EVENTS. ALLを取り込むことで、現在サポートされているすべての自動収集イベントを開きます。また、プロジェクトのニーズに応じて一部の自動収集イベントを開くこともできます。

// すべての自動収集イベントを開く
ThinkingAnalyticsAPI.EnableAutoTrack(AUTO_TRACK_EVENTS.ALL);

// イベント自動収集の開始/終了を有効化
ThinkingAnalyticsAPI.EnableAutoTrack(AUTO_TRACK_EVENTS.APP_START | AUTO_TRACK_EVENTS.APP_END);

注:カスタムゲストIDまたはパブリックイベントプロパティを設定するには、自動収集イベントを開く前に完了する必要があります。自動収集イベントは動的パブリックプロパティをサポートしていません。

# 5.2 自動収集イベントのカスタムプロパティ

v2.2.4以降から、EnableAutoTrackを呼び出して自動収集を開始する同時に、収集するカスタムプロパティを渡すことができます。

// 自動収集イベントを開く，カスタムプロパティを設定
ThinkingAnalyticsAPI.EnableAutoTrack(AUTO_TRACK_EVENTS.ALL, new Dictionary<string, object>() {
    {"custom_key", "custom_value"}
});

SetAutoTrackPropertiesを呼び出して、特定の自動収集イベントのカスタムプロパティを指定します。

注意:SetAutoTrackPropertiesは自動収集イベントの収集を有効化しません。EnableAutoTrackと併用する必要があります。

// 単独の自動収集イベントのカスタムプロパティの設定
ThinkingAnalyticsAPI.SetAutoTrackProperties(AUTO_TRACK_EVENTS.APP_START, new Dictionary<string, object>() 
{
    {"start_key", "start_value"}
});

// 複数の自動収集イベントのカスタムプロパティの設定
ThinkingAnalyticsAPI.SetAutoTrackProperties(AUTO_TRACK_EVENTS.APP_INSTALL | AUTO_TRACK_EVENTS.APP_CRASH, new Dictionary<string, object>() 
{
    {"install_crash_key", "install_crash_value"}
});

// すべての自動収集イベントを開く
ThinkingAnalyticsAPI.EnableAutoTrack(AUTO_TRACK_EVENTS.ALL);

# 6、その他の設定オプション

# 6.1 デバイスIDの取得

SDKは初期化が完了すると、デバイスIDが自動的に生成され、ローカルキャッシュに記録されます。同じアプリケーション/ゲームに対して、デバイスのデバイスIDは変更されず、GetDeviceId()を呼び出してデバイスIDを取得することができます。

ThinkingAnalyticsAPI.GetDeviceId();

// デバイスIDをゲストIDとする
// ThinkingAnalyticsAPI.Identify(ThinkingAnalyticsAPI.GetDeviceId());

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

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

  1. SDKアップロードの一時停止(EnableTracking)

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

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

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

// アップロード一時停止.キャッシュされたデータと設定済の情報は削除されない.
ThinkingAnalyticsAPI.EnableTracking(false);

// アップロードを再開
ThinkingAnalyticsAPI.EnableTracking(true);
  1. SDKアップロードの停止(OptOutTracking)

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

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

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

SDK機能をオフにしている間にTAクラスタ内のユーザーデータを削除したい場合、optOutTrackingAndDeleteUserを呼び出すと、SDKインスタンス機能を停止する前にUserDeleteデータをアップロードしてユーザーデータを削除することができます。

// アップロードを中止し，user_delを送信
ThinkingAnalyticsAPI.OptOutTrackingAndDeleteUser();

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

// アップロードを再開
ThinkingAnalyticsAPI.OptInTracking();

# 6.3 ライトインスタンスの作成

ライトインスタンスを通して、同じAPP IDに複数のインスタンスを作成することができます。

// ライトインスタンスを作成し，ライトインスタンスtokenに戻る （APP IDに類似）
string lightToken = ThinkingAnalyticsAPI.CreateLightInstance();

// ライトインスタンスにアカウントIDを設定
ThinkingAnalyticsAPI.Login("anotherAccount", lightToken);

// ライトインスタンスでイベントをアップロード
ThinkingAnalyticsAPI.Track("TEST_EVENT", lightToken);

注意:サブライトインスタンスは親インスタンスのAPP ID、アップロードアドレス、および一部の設定と一致しますが、その他の情報は共有されません。

# 6.4 SDKの運用モード

v1.4.0以降、SDKは3つのモードで運用することができます。

  • NORMAL:通常モードはデータがキャッシュに保存され、一定のキャッシュポリシーに従ってアップロードされます。
  • DEBUG: Debugモードはデータが1つずつアップロードされます。問題が発生すると、ログと警告でユーザーを通知します。
  • DEBUG_ONLY: Debug Onlyモードはデータのみをチェックし、格納しません。

注: DEBUGモードは統合フェーズのデータチェックのみに使用され、本番モードでは使用しないでください。

Debugモードが本番環境でオンラインにならないように、指定されたデバイスのみがDebugモードをオンにすることができます。クライアントのDebugモードが有効で、且つデバイスIDがTAプラットフォームの「埋め込みポイント管理」ページの「Debugデータ」に構成されているデバイスでのみDebugモードを有効にすることができます。

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

  • TAプラットフォームのイベントデータの#device_idプロパティ
  • クライアントログ：SDKの初期化が完了すると、デバイスDeviceIdが印刷される
  • インスタンスインターフェイスを介する呼び出し：デバイスIDの取得

# 6.5 キャリブレーション時間

SDKはデフォルトでシステム時間をイベント発生時刻として使用し、ユーザーが手動でシステム時間を変更すると業務分析に影響を与える可能性があります。v2.0.0以降、サーバー側から取得した現在のタイムスタンプでSDK時間を校正することができます。それ以降、時間が指定されていない呼び出し(イベントデータやユーザープロパティ設定の操作を含む)はすべて校正後の時間をイベント発生時間とします。

// 1585633785954 は現在の unix タイムスタンプ，単位はミリ秒，北京時間 2020-03-31 13:49:45に相当
ThinkingAnalyticsAPI.calibrateTime(1585633785954);

NTPから時間を取得しSDKを校正する機能も提供しています。ユーザーがアクセスできるNTPサーバーアドレスを入力する必要があり、SDKは受信したNTPサーバーアドレスから現在の時間を取得し、SDK時間を校正します。ただし、デフォルトのタイムアウト時間(3秒)以内に正しい結果が得られない場合、システム時間を使用してデータをアップロードします。

// Appleの NTP サービスで時間校正を行う
ThinkingAnalyticsAPI.calibrateTimeWithNtp("time.apple.com");

注意:

  • ネットワークが良好の状態で、ユーザーのデバイスがスムーズにサーバーの到着時間を取得できるように、NTPサーバーアドレスを慎重に選択する必要があります。
  • NTPサービスを用いる時間校正は不確実性があるので、タイムスタンプによる時間校正を優先的にご検討ください。

上記の時間校正インターフェイスに加えて、v2.0.0は、すべてのユーザープロパティインターフェイスの時間関数オーバーロードを提供しています。ユーザープロパティ関連のインターフェイスを呼び出すときに、DateTimeオブジェクトを取り込むと、受信したDateTimeオブジェクトを使用してデータの#timeフィールドを設定します。

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

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

v2.2.0以降では、 ThinkingAnalyticsAPI.GetPresetProperties()メソッドを呼び出すことでプリセットプロパティを取得することができます。

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

//プロパティオブジェクトを取得
TDPresetProperties presetProperties = ThinkingAnalyticsAPI.GetPresetProperties();

//イベントプリセットプロパティを生成
Dictionary<string, object> eventPresetProperties = presetProperties.ToEventPresetProperties();
/*
   {
	"#carrier": "中国电信",
	"#os": "iOS",
	"#device_id": "A8B1C00B-A6AC-4856-8538-0FBC642C1BAD",
	"#screen_height": 2264,
	"#bundle_id": "com.sw.thinkingdatademo",
 	"#app_version": "0.1",
	"#manufacturer": "Apple",
	"#device_model": "iPhone7",
	"#screen_width": 1080,
	"#system_language": "zh",
	"#os_version": "10",
	"#network_type": "WIFI",
	"#zone_offset": 8
    }
*/


//プリセットプロパティの取得
string bundleId = presetProperties.BundleId;//パッケージ名
string appVersion = presetProperties.AppVersion;//Appバージョン
string os = presetProperties.OS;//os種類，例：Android、iOS
string systemLanguage = presetProperties.SystemLanguage;//デバイスシステム言語
int screenWidth = presetProperties.ScreenWidth;//画面の幅
int screenHeight = presetProperties.ScreenHeight;//画面の高さ
string deviceModel = presetProperties.DeviceModel;//デバイスモデル
string deviceId = presetProperties.DeviceId;//デバイスID
string carrier = presetProperties.Carrier;//ネットワークキャリア，2つのSIMがある場合，メインSIMの情報を取得
string manufacture = presetProperties.Manufacturer;// デバイスメーカー　例：HuaWei、Apple
string networkType = presetProperties.NetworkType;//ネットワーク種類
string osVersion = presetProperties.OSVersion;//システムバージョン
double zoneOffset = presetProperties.ZoneOffset;//タイムゾーンオフセット

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

# 8、高度な機能

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

# 8.1 初期イベント

初期イベントとは、あるデバイスや他のディメンションのIDに対して、一度しか記録されないイベントです。たとえば、デバイスで最初に発生したイベントを記録したい場合は、初期イベントを用いてデータをアップロードすることができます。

// 例：初期イベントをアップロード. イベント名は DEVICE_FIRST.
Dictionary<string, object> properties = new Dictionary<string, object>()
{
    {"KEY_STRING", "B1"},
    {"KEY_BOOL", true},
    {"KEY_NUMBER", 50.65},
};

ThinkingAnalyticsAPI.Track(new TDFirstEvent("DEVICE_FIRST", properties));

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

// 例：ユーザーアカウントの初期イベント. イベント名はUSER_FIRSTに仮定
TDFirstEvent firstEvent = new TDFirstEvent("USER_FIRST", properties);
firstEvent.SetFirstCheckId("YOUR_ACCOUNT_ID");

ThinkingAnalyticsAPI.Track(firstEvent);

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

# 8.2 更新可能なイベント

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

// 例： 更新可能なイベントをアップロード，イベント名は UPDATABLE_EVENTに仮定
TDUpdatableEvent updatableEvent = new TDUpdatableEvent("UPDATABLE_EVENT", new Dictionary<string, object>{
    {"status", 3},
    {"price", 100}
}, "test_event_id");

// イベントプロパティアップロード後に status は 3, price は 100
ThinkingAnalyticsAPI.Track(updatableEvent);


TDUpdatableEvent updatableEvent_new = new TDUpdatableEvent("UPDATABLE_EVENT", new Dictionary<string, object>{
    {"status", 5}
}, "test_event_id");

// イベントプロパティアップロード後に status は 5に更新され, price は変わらない
ThinkingAnalyticsAPI.Track(updatableEvent_new);

更新可能なイベントはデフォルトで、システム時間を使用して過去データのイベント時間を更新します。イベント時間を指定したい場合は、更新可能なイベントをアップロードするときにイベント時間を指定します。

TDUpdatableEvent updatableEvent = new TDUpdatableEvent("UPDATABLE_EVENT", properties_new, "test_event_id");

// 更新可能なイベントのイベント時間
updatableEvent.EventTime = DateTime.Now;

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

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

// 例： 書き換え可能なイベントをアップロードし，イベント名は OVERWRITE_EVENTに仮定
TDOverWritableEvent overWritableEvent = new TDOverWritableEvent("OVERWRITABLE_EVENT", new Dictionary<string, object>{
    {"status", 3},
    {"price", 100}
}, "test_event_id");

// イベントプロパティアップロード後に status は 3, price は 100
ThinkingAnalyticsAPI.Track(overWritableEvent);

TDOverWritableEvent overWritableEvent_new = new TDOverWritableEvent("OVERWRITABLE_EVENT", new Dictionary<string, object>{
    {"status", 5}
}, "test_event_id");

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

書き換え可能なイベントは、システム時間を使用して過去データのイベント時間を更新します。イベント時間を指定したい場合は、更新可能なイベントをアップロードするときにイベント時間を指定します。

TDOverWritableEvent overWritableEvent = new TDOverWritableEvent("OVERWRITABLE_EVENT", new Dictionary<string, object>{
    {"status", 3},
    {"price", 100}
}, "test_event_id");

// 書き換え可能なイベントのイベント時間
overWritableEvent.EventTime = DateTime.Now;

# Release Note

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