目录
此内容是否有帮助?

# 履歴バージョンの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以降のバージョンしかサポートしていません。

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

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

← Cocos2d-x SDK利用ガイド →