目录
此内容是否有帮助?

# 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://receiver.ta.thinkingdata.cn
    • オンプレミスを使用している場合は、次の 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

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