目录
此内容是否有帮助?

# 過去バージョンの Unity SDK 使用ガイド

Unity SDK は v2.0.0 にアップグレードされました。この記事は過去バージョンの使用ガイドです。新しくインポートする場合は、最新のUnity SDK 使用ガイドをご参照ください。

このガイドは、Unity SDK を使用してデータをプロジェクトにインポートする方法を説明します。インポートする前に、データルールをご参照ください。GitHub (opens new window)で Unity SDK ソースコードを取得することができます。

最新バージョン**：** v1.4.4

更新時間**：**2020-04-17

ダウンロード (opens new window)

# 1、SDK の初期化

# 1.1 SDK 統合

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

    注意: Android プラグインは Gradle 統合を使用しているため、現在は Unity 5.4 以降のバージョンしかサポートしていません。

  2. ThinkingAnalytics GameObject を追加し、SDK を設定します。

上図の設定:

設定

  • Enable Log：ログをオンにするかどうか。オンにすると、デバッグできるようにレポートが印刷されます。Editor モードで、イベントが正しくアップロードされているかどうかを確認し、条件を満たさないプロパティはwarningログでコンソールに表示されます。
  • Network Type：データをサーバーにアップロードするネットワーク条件を設定します。デフォルトはDEFAULT。以下はすべてのオプションの説明です。
    • DEFAULT：3G、4G、5G および WIFI 環境でデータをアップロード
    • WIFI： WIFI 環境でのみデータをアップロード
    • ALL：2G、3G、4G、5G および WIFI 環境でデータをアップロード
  • PostponeTrack：遅延アップロードの有無を設定します。このオプションをオンにすると、データはStartTrack()を呼び出した後にアップロードされ、呼び出し前のデータはStartTrack()が呼び出されるまでキャッシュされます。**ゲスト ID またはパブリックプロパティを設定するには、このオプションを有効にしてください。**詳細は遅延報告をご確認ください。

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 モードをご参照ください。
  • Auto Track:自動収集イベントを有効にするかどうかを示します。チェックすると SDK はゲームの開始と終了を自動的に記録します。詳細は自動収集イベントをご参照ください。
  • TimeZone: v1.4.3 からサポートし、デフォルトの校正タイムゾーンです。この設定はイベント時間とユーザープロパティで設定した時間にのみ有効し、プロパティの DateTime タイプは有効ではありません。

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

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

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 インスタンスを調整することができます。

# 1.2 SDK の使用

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

using ThinkingAnalytics;

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プロパティは無視されます。

注意:イベントは時間トリガーを設定することができますが、受信側は次のように制限し、システム時間の 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()を呼び出します。

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

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

# 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、イベントの自動収集

SDK 設定時に Auto Track オプションをチェックした場合、SDK は自動的に記録します：

  • ta_app_startはゲーム開始イベントです。ユーザーが焦点を獲得するたびに(ゲーム内)トリガーされます。
  • ta_app_endはゲーム終了イベントです。ゲームがPause状態になったときにトリガーされ、#durationプロパティが追加され、ゲームの持続時間(単位は秒)を記録します。

バージョン 1.1.0 以降では、インターフェイスの呼び出しによってインストールイベントを収集することができます。

// 采集 APP 安装事件
ThinkingAnalyticsAPI.TrackAppInstall();
  • ta_app_installはゲームのインストールイベントです。インストールイベントは、ユーザーがインストールした後、初めて APP を開いたときにのみ発生し、APP のアップグレードはトリガーされません。しかし、ユーザーが APP を削除し、再インストールする場合もトリガーされます。

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

# 6.1 デバイス ID の取得

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

ThinkingAnalyticsAPI.GetDeviceId();

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

# 6.2 遅延報告

PostponeTrack オプションにチェックを入れると、次のメソッドを呼び出すまで、アップロードされたすべての要求(ユーザープロパティ設定とイベントトレースを含む)がキャッシュに保存されます。

ThinkingAnalyticsAPI.StartTrack();

このインタフェースが呼び出されると、データが報告されます。このインタフェースが呼び出される前に**生成した**データは**アップロード**されると、ユーザー ID**が**再設定され**、パブリックプロパティに加入します**。StartTrack()を呼び出す前にユーザー ID とパブリックプロパティを設定すると、すべてのデータに有効にすることができます。ゲスト ID、**パブリックプロパティ設定が必要の**場面に適しています。

//ゲストIDを設定
ThinkingAnalyticsAPI.Identify(ThinkingAnalyticsAPI.GetDeviceId());

//パブリックプロパティを設定
Dictionary<string, object> superProperties = new Dictionary<string, object>()
    {
        {"SERVER", 0},
        {"CHANNEL", "A3"}
    };
ThinkingAnalyticsAPI.SetSuperProperties(superProperties);

//アップロードインターフェースを呼び出す
ThinkingAnalyticsAPI.StartTrack();

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

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.4 ライトインスタンスの作成

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

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

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

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

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

# 6.5 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 を取得

# Release Note

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