Unity SDK

Amplitude Analytics Unity SDKは、Amplitude iOSおよびAndroid SDKをUnityプロジェクトに簡単に連携できるプラグインです。この SDK は Unity 2019.3.11 以降で動作します。

SDKをインストールする

Amplitude Analytics Unity SDKは、プラットフォームに応じてさまざまなインストール方法をサポートしています。

オプション1：Unity パッケージマネージャー

1. Git がインストールされていることを確認してください。
2. Unity で Window > Package Manager をクリックします。
3. プラス**+**記号をクリックし、「Git URLからパッケージを追加」を選択します。
4. https://github.com/amplitude/unity-plugin.git?path=/Assetsと入力し、追加をクリックします。
5. UnityエディタはGitからパッケージをインポートします。

オプション2：手動ダウンロード

1. GitHubリリースから最新のamplitude-unity.unitypackageをダウンロードしてください。
2. amplitude-unity.unitypackageをダブルクリックして、パッケージをUnityプロジェクトにインポートします。

Android

難読化例外を追加する

ProGuardルールファイルにこの行を追加してください: proguard.pro。

-keep class com.amplitude.unity.plugins.AmplitudePlugin { *; }

依存関係の管理

Amplitudeのcom.amplitude.android-sdkは推移的なライブラリであり、それ自体には他の依存関係は含まれていません。Amplitude は com.amplitude.android-sdk のその他の依存関係を Assets/Plugins/Android に格納します。AmplitudeはOkHTTPを使用しており、表示されているその他の依存関係はOkHTTPが依存しているものです（OkioやJetbrainsなど）。

プロジェクトでOkHTTPを使用している場合は、OkHTTPとその関連する依存関係のチェックを外すことで、含めないようにすることができます。

unity-jar-resolver を使用する

一部のユーザーは自分たちでunity-jar-resolverを利用しています。依存関係を強制的に解決するとき、unity-jar-resolver はAmplitude関連のjarファイルをクリーンアップします。 この場合、これらの依存関係を*Dependencies.xmlファイルで宣言してください。

androidPackageタグの下にAmplitudeのネイティブ依存関係を追加します。

<androidPackage spec="com.amplitude:android-sdk:2.+">
    <repositories>
    <repository>https://maven.google.com</repository>
    </repositories>
</androidPackage>
<androidPackage spec="com.squareup.okhttp3:okhttp:4.2.2">
    <repositories>
    <repository>https://maven.google.com</repository>
    </repositories>
</androidPackage>

APIの互換性

Amplitude Analytics Unity SDKはOkHTTPライブラリに依存しています。OkHTTP v3.13には、Android 5.0以上のAndroidバージョンであるAndroid Lollipop（API 21）が必要です。詳細については、「OkHttp 3.13 には Android 5 以降が必要です」を参照してください。

Amplitudeは、使用するOkHTTPバージョンを制限しません。API 19、20（Android KitKat）を動作させるには、OkHTTPバージョンを3.13より低いバージョンにダウングレードしてください。

1. OkHTTPのバージョンを3.13より低いバージョンに変更してください。
2. Unityでは、.jarファイルをコピーしてライブラリをインポートします。OkHTTPライブラリを3.13より前のバージョンに置き換えることで、ダウングレードできます。Googleの依存関係リゾルバーを使用している場合は、*Dependency.xmlファイル内のOkHTTPの依存関係バージョンを更新してください。

iOS XCodeのトラブルシューティング

Xcodeでシミュレーターやデバイスを使用できない場合、これはデバイスSDK（物理デバイス）またはシミュレーターSDK（エミュレーター）のいずれかを使用するようにUnityプロジェクトを構成する必要があるためです。

ビルドの設定を変更するには、_Unity > 編集 > プロジェクト設定... を選択してください。 > Player > iOSタブ_で、Other設定ドロップダウンメニューを開き、Configurationまでスクロールして、Target SDKフィールドに必要な値のいずれかを選択します。

SDKの初期化

計装を行う前に、SDKを初期化してください。Amplitudeプロジェクト用のAPIキーが必要です。

Amplitude amplitude = Amplitude.getInstance();
amplitude.setServerUrl("https://api2.amplitude.com");
amplitude.logging = true;
amplitude.trackSessionEvents(true);
amplitude.init(AMPLITUDE_API_KEY);

オプションで、文字列 instanceName を getInstance() に送信できます。この文字列は、1つのAmplitudeオブジェクトのすべての設定に関連付けられます。

Amplitude amplitude1 = Amplitude.getInstance("client_1");
Amplitude amplitude2 = Amplitude.getInstance("client_2");
//Settings changes in amplitude1 will not be reflected in amplitude2
Amplitude.getInstance("client_1") //this is the same reference as amplitude1

SDK を設定する

Amplitude Unity SDKは、Amplitude Android Maintenance SDKおよびAmplitude iOS Maintenance SDKの上で動作します。 以下は、C#で指定可能な構成オプションです。

その他のデフォルト設定の場合：

• Androidの場合、Android設定を参照してください。
• iOS側については、iOS設定を参照してください。

バッチ処理の動作を設定する

高パフォーマンス環境をサポートするために、SDK はイベントをバッチで送信します。 SDK は、logEvent メソッドによって記録されたすべてのイベントをメモリ内でキューイングします。SDKはバックグラウンドで、イベントをバッチ単位でフラッシュします。setEventUploadPeriodSecondsを使用してバッチ動作をカスタマイズできます。 デフォルトでは、serverUrl は https://api2.amplitude.com/ です。 この SDK は、バッチ API エンドポイント経由でのバッチモードをサポートしていません。

// Events queue flushes every certain seconds based on setting
// Default value is 30 seconds
amplitude.setEventUploadPeriodSeconds(50);

EU域内のデータレジデンシー

バージョン2.4.0以降では、クライアントを初期化した後にサーバーゾーンを設定してAmplitudeのEUサーバーにデータを送信できるようになりました。 SDK は、サーバーゾーンが設定されている場合、サーバーゾーンに基づいてデータを切り替えおよび送信します。 サーバーゾーン設定は、動的設定もサポートしています。

以前のバージョンでは、クライアントを初期化した後にserverURLプロパティを設定する必要があります。

// For versions starting from 2.4.0
// No need to call setServerUrl for sending data to Amplitude's EU servers
amplitude.setServerZone(AmplitudeServerZone.EU);
// For earlier versions
amplitude.setServerUrl("https://api.eu.amplitude.com");

基本イベントを送信する

イベントは、ユーザーがアプリケーションとどのように対話するかを表します。 たとえば、「ボタンがクリックされました」というアクションは、メモしておくべきアクションかもしれません。

amplitude.logEvent("Button Clicked");

Unity でこの機能を実行する際は、プラットフォームの下のビルド設定で iOS または Android が選択されていることを確認してください。

プロパティ付きのイベントを送信

イベントにはプロパティも含めることができます。 プロパティは発生したイベントに関するコンテキストを提供します。 たとえば、「ホバー時間」は「ボタンのクリック」に関連するイベントプロパティである可能性があります。

Dictionary<string, object> eventProps = new Dictionary<string, object>();
eventProps.Add("Hover Time", 10);
amplitude.logEvent("Button Clicked", eventProps);

ユーザープロパティを設定する

Identify

Identifyは、イベントを送信することなく、特定のユーザーのユーザープロパティを設定するためのものです。Unity SDK は、個々のユーザープロパティに対する操作 setUserProperty、setOnce、add、および append をサポートしています。

指定された Identify インターフェイスを使用して操作を宣言します。 複数の操作を単一のIdentifyオブジェクトにまとめます。IdentifyオブジェクトをAmplitudeクライアントに渡してサーバーに送信します。

ユーザーIDの管理

identify メソッドを使用してユーザーの ID を処理できます。 これらの方法を適切に使用すると、デバイス、ブラウザ、その他のプラットフォーム間でイベントが移動する際に、イベントを適切なユーザーに結び付けることができます。

これらのユーザープロパティ操作を含むIdentifyコールをAmplitudeに送信して、ユーザーのイベントを特定のユーザープロパティと結び付けます。

setUserProperty

setUserProperty は、ユーザー プロパティの値を設定します。 また、複数のidentifyコールを連結することもできます。

amplitude.setUserProperty("saw_page_a", true);

一度だけ設定

setOnce は、ユーザープロパティの値を 1 回だけ設定します。 SDKはsetOnceを使用した後続の呼び出しを無視します。

amplitude.setOnceUserProperty("page_views", 50);

追加する

add は、ユーザープロパティを何らかの数値で増分します。 ユーザー プロパティに値がまだ設定されていない場合、SDK はその値を 0 に初期化します。

amplitude.addUserProperty("oranges", 5);
Dictionary<string, object> values = new Dictionary<string, object>();
values.Add("Key A", "Value A");
amplitude.addUserPropertyDict("user_facts", values);

複数のユーザープロパティを設定する

logEvent()メソッドを使用すると、イベントログと同時にユーザープロパティを設定できます。複数のユーザープロパティを一度に設定するための短縮形として、setUserPropertiesを使用できます。このメソッドは Identify.set のラッパーです。

Dictionary<string, object> values = new Dictionary<string, object>();
values.Add("user_time", 100.5);
values.Add("engagement", true);
amplitude.setUserProperties(values);

ユーザープロパティ内の配列

配列をユーザープロパティとして使用できます。配列を直接設定することも、append を使用して配列を生成することもできます。

int[] arr = new int[] { 1, 2, 4, 8 };
amplitude.setUserProperty("user_running_times", arr);

追加する

append は、ユーザー プロパティ配列に 1 つまたは複数の値を追加します。 ユーザープロパティに値がまだ設定されていない場合、SDK は新しい値を追加する前にそのプロパティを空のリストに初期化します。 ユーザープロパティに既存の値があり、それがリストではない場合、SDK は既存の値をリストに変換し、新しい値を追加します。

amplitude.setUserProperty("stringArray", new string[]{"replace", "existing", "strings"});
amplitude.appendUserProperty("stringArray", new string[]{ "append", "more", "strings" });

ユーザープロパティの消去

clearUserProperties メソッドは、すべてのユーザープロパティを一度に消去するためのものです。

amplitude.clearUserProperties();

unset

unset ユーザープロパティの設定を解除および削除します。

amplitude.unsetUserProperty("property_name_to_unset");

ユーザーグループを設定する

Amplitudeでは、ユーザーをグループに割り当てたり、それらのグループに対して「ユニーク数による集計」などのクエリを実行したりすることができます。 グループの少なくとも1人のメンバーが特定のイベントを実行した場合、そのグループはカウントに含まれます。

たとえば、「orgId」を使用して、ユーザーが所属する組織に基づいてユーザーをグループ化したい場合などです。 Joeは'orgId' '10'に属し、Sueは'orgId' '15'に属しています。SueとJoeはどちらも特定のイベントを実行します。 イベントセグメンテーションチャートでその組織をクエリできます。

グループを設定する際には、groupTypeとgroupNameを定義してください。 前の例では、「orgId」はgroupTypeで、「10」と「15」はgroupNameの値です。 groupTypeのもう1つの例としては、「tennis」や「baseball」などのgroupName値を持つ「sport」があります。

グループを設定すると、groupType:groupNameもユーザープロパティとして設定され、そのユーザーのgroupTypeに設定されている既存のgroupNameの値と対応するユーザープロパティ値が上書きされます。groupTypeは文字列であり、groupNameはユーザーが複数のグループに属していることを示す文字列または文字列の配列のいずれかを指定できます。

Amplitude.getInstance().setGroup("orgId", "15");
Amplitude.getInstance().setGroup("sport", new JSONArray().put("tennis").put("soccer"));  // list values

また、logEventWithGroups を使用してイベントレベルのグループを設定することもできます。 グループ指定はログに記録する特定のイベントにのみ適用され、setGroupで明示的に設定しない限り、ユーザーには保持されません：

JSONObjecteventProperties=newJSONObject().put("key", "value");
JSONObjectgroups=newJSONObject().put("orgId", 10);
Amplitude.getInstance().logEvent("initialize_game", eventProperties, groups);

収益の追跡

Amplitudeはユーザーが生み出した収益を追跡できます。 Amplitudeは、AmplitudeのイベントセグメンテーションとレベニューLTVチャートで使用される特別なフィールドを持つ個別の収益オブジェクトを通じて収益を追跡します。Amplitudeはプラットフォーム内の収益に関連するデータを自動的に表示します。 収益オブジェクトは、以下の特別なプロパティとeventPropertiesフィールドを通じて、ユーザー定義のプロパティをサポートしています。

logRevenue を呼び出すと、プラットフォーム内で最大 2 種類のイベントが生成されます。

• 「[Amplitude] Revenue」：Amplitudeは検証が有効になっているかどうかに関係なく、すべての収益イベントについてこのイベントを記録します。
• '[Amplitude] Revenue (Verified/Unverified)': これらの収益イベントには実際の '$revenue' プロパティが含まれています。

生データでこれらのクライアント側の収益イベントに付与されているデフォルトの名前を変更することはできませんが、表示名を変更することはできます。 収益の追跡に関する詳細については、「収益の追跡」ドキュメントを参照してください。

収益を検証する

UnityはAndroidとiOSの両方のストアをサポートしているため、収益確認については適切なドキュメントを参照してください。 AndroidおよびiOS/tvOS/macOSのドキュメントと、ストア（Android AIDL/Google Play課金、Amazonストア、またはiOSアプリストア）に関する特別な手順を参照してください。

amplitude.logRevenue(0.03);
amplitude.logRevenue("sku", 1, 1.99);
amplitude.logRevenue("sku", 1, 1.99, "cmVjZWlwdA==", null);
Dictionary<string, object> revenueProperties = new Dictionary<string, object>()
{
  {"car", "blue"},
  {"price", 12.99}
};
if (Application.platform == RuntimePlatform.IPhonePlayer) {
  amplitude.logRevenue("sku", 1, 1.99, "cmVjZWlwdA==", null, "purchase", revenueProperties);
} else if (Application.platform == RuntimePlatform.Android) {
  amplitude.logRevenue("sku", 1, 1.99, "receipt", "receiptSignature", "purchase", revenueProperties);
}

ユーザーセッション

Android でのセッションとは、ユーザーがアプリをフォアグラウンドに置いている期間のことです。

Amplitudeはイベントをセッションごとにグループ化します。 同じセッション内で記録されたイベントは、同じsession_idを共有します。 Amplitudeはセッションを自動的に処理するため、startSession()またはendSession()などのAPIを手動で呼び出す必要はありません。

Amplitudeがセッションを延長する時間枠を調整できます。

client.setMinTimeBetweenSessionsMillis(10000); //10 seconds

デフォルトでは、SDK は「[Amplitude] Start Session」イベントと「[Amplitude] End Session」イベントを送信しません。SDK はこれらのイベントを送信しませんが、それでも Amplitude は session_id を使用してセッションを追跡します。これらのセッションイベントを再度有効にするには、SDK を初期化する前にこの行を追加してください。

Amplitude amplitude = Amplitude.Instance;
amplitude.trackSessionEvents(true);
amplitude.init(AMPLITUDE_API_KEY);

イベントをセッション外として記録することもできます。 内部的には（Amplitudeダッシュボード内）、セッション外イベントは session_id が -1 であり、現在のセッションの一部ではありません。つまり、現在のセッションを延長しません。これは、たとえばプッシュ通知によってトリガーされたイベントをログに記録する場合に役立ちます。 logEvent()を呼び出す際に、入力パラメータoutOfSessionをtrueに設定することで、イベントをセッション外として記録できます。

Dictionary<string, object> eventProps = new Dictionary<string, object>();
bool outOfSession = true;
client.logEvent("event out of session", eventProps, outOfSession);

広告ID

広告主 ID（IDFA とも呼ばれます）は、iOS および Google Play ストアによって提供される固有の識別子です。 IDFAはデバイスだけでなく、人それぞれに固有のものであるため、モバイルアトリビューションに役立ちます。 モバイルアトリビューションとは、モバイルアプリのインストールが元のソース（広告キャンペーン、アプリストアの検索など）に帰属することです。

モバイルアプリはIDFAを要求するには権限を必要とし、子供をターゲットにしたアプリはまったく追跡できません。IDFAが利用できない場合は、代替手段としてIDFV、デバイスID、またはメールログインシステムを検討してください。

iOSの設定

セットアップ手順については、「Unity iOS IDFAとGPSのセットアップ」を参照してください。

Androidのセットアップ

セットアップ手順については、Android SDKを参照してください。

位置情報追跡

ロケーショントラッキングの場合、AmplitudeはデフォルトでユーザーイベントのIPをロケーションに変換します（GeoIP検索）。 アプリ独自の追跡ソリューションまたはユーザーデータがこの情報を上書きする場合があります。

AmplitudeはAndroidロケーションサービスにアクセスして（可能な場合）、SDKがイベントを記録する特定の座標（経度と緯度）を追加できます。

カスタムユーザーIDを設定する

アプリに独自のログインシステムがあり、ユーザーを追跡したい場合は、いつでもsetUserIdを呼び出してください。

Amplitude.Instance.setUserId("USER_ID");

ユーザーIDを引数としてinit呼び出しに追加することもできます。

Amplitude.Instance.init(AMPLITUDE_API_KEY, "USER_ID");

Amplitudeは各固有のユーザーIDを固有のユーザーとして解釈するため、変更可能なユーザーIDをユーザーに割り当てないでください。 詳細については、「Amplitudeでユニークユーザーを追跡する」を参照してください。

高度なトピック

COPPA制御

IDFA、IDFV、都市、IPアドレス、位置情報の追跡に関するCOPPA (児童オンラインプライバシー保護法) の制限をすべて一度に有効または無効にできます。 13 歳未満の子供から情報を求めるアプリは、COPPA に準拠する必要があります。

client.enableCoppaControl();

追跡のオプトアウト

ユーザーは、位置情報の追跡を完全にオプトアウトしたい場合があります。つまり、イベントが発生せず、ブラウジング履歴の記録もありません。 このAPIは、特定のユーザーのプライバシーに対する要求を満たす方法を提供します。

client.setOptOut(true); //No events are tracked for this user

動的な設定

Unity SDKを使用すると、ユーザーは動的設定を使用するようにアプリを設定できます。この機能は、ユーザーの所在地に基づいて最適なAmplitudeサーバーURLを自動的に検出します。

• 独自のプロキシサーバーを持ち、setServerUrl API を使用している場合は、動的設定を使用しないでください。
• 中国本土にユーザーがいる場合、Amplitudeでは動的設定を使用することを推奨します。
• デフォルトでは、この機能はオフになっています。 使用するには、明示的に有効にする必要があります。
• デフォルトでは、この機能はAmplitudeの米国サーバーのサーバーURLを返します。 AmplitudeのEUサーバーにデータを送信する必要がある場合は、setServerZoneを使用してEUゾーンに設定してください。

amplitude.setUseDynamicConfig(true);

iOS IDFAとGPSの設定

このセクションでは、Unity SDKユーザーがログイベント内のIDFA（広告主ID）とGPS座標データにアクセスできるようにするためのプロセスについて説明します。

考慮事項

• この機能はUnity SDKに含まれていません。これは、Apple App StoreがIDFAコードを使用するアプリにフラグを付けているためです。コードが無効になっている場合や、AmplitudeなどのサードパーティのSDK開発者から提供されている場合でも同様です。
• IDFAに代わるものを検討してください。 ユーザーがIDFAトラッキングを有効にしていると決めつけないでください。オプトイン方式では許諾率が低くなります。デバイスIDやIDFVを使用するか、独自のアプリのメールログインシステムをカスタムユーザープロパティとして渡します。
• Objective-C の iOS ロジックを編集して IDFA と GPS データを取得できます。 ただし、現在のコードは権限を処理しており、アプリユーザーが権限を付与すると、SDK 内の IDFA と GPS データを正確に更新します。

セットアップ

まず、2つのファイルunity-plugin/IdfaIOS/CustomIdfa.mとunity-plugin/IdfaIOS/CustomGPS.mを取得してAssets/Scriptsに配置します。 ファイルをどこにでも配置できますが、すべての #import ステートメントが正しいパスに導くことを確認してください。

あなたの .cs ゲームスクリプトのインポートセクション（上部）に、次のインポートを追加します：

#if (UNITY_IPHONE || UNITY_TVOS)
using System.Runtime.InteropServices;
#endif

ゲームクラス内でMonoBehaviorクラスやその他のクラス内に次のコードを追加します。

public class AmplitudeDemo : MonoBehavior {
#if (UNITY_IPHONE || UNITY_TVOS)
    [DllImport ("__Internal")]
    private static extern void setIdfaBlock(string instanceName);
    [DllImport ("__Internal")]
    private static extern void setLocationInfoBlock(string instanceName);
#endif

最後に、ゲームコード(おそらく void Start())でこれらの関数を呼び出します。YOUR_INSTANCE_NAME は、この特定のAmplitudeインスタンスに関連付けられた文字列です。YOUR_INSTANCE_NAME は null または空の文字列にすることもできます。

Amplitude amplitude = Amplitude.getInstance(YOUR_INSTANCE_NAME);
amplitude.init(AMPLITUDE_API_KEY);
#if (UNITY_IPHONE || UNITY_TVOS)
    setLocationInfoBlock(YOUR_INSTANCE_NAME);
    setIdfaBlock(YOUR_INSTANCE_NAME);
#endif

これらの機能は、iOSユーザーにGPS位置情報追跡およびIDFA追跡の許可を承認または拒否するよう促します。

Unityアプリには2つの特別な設定が必要です。
場所については、Unity > 編集 > プロジェクト設定に移動します... 下の最初の画像のメニューがポップアップします。 [プレーヤー] を選択し、[iOS] タブをクリックします。 **[Other 設定] をクリックし、[Location Usage Description] **フィールドまでスクロールします。 テキストボックスに、ユーザーにGPS追跡権限を求める文を入力します。

IDFA の場合は、Apple の仕様に従ってInfo.plistファイルを編集してください。 この Unity の投稿に記載されているガイダンスに従って、Unity スクリプトを使用してこれを行うことができます。

また、Unity がアプリを iOS 用にコンパイルして Xcode で起動したら、最上位ファイル Info.plist を見つけます。任意のキー値ペアの横にあるプラス記号をクリックします。 Xcode エディタを使用してキー Privacy - Tracking Usage Description を見つけ、Type が String であることを確認し、Value フィールドに追跡権限を要求するプロンプトを入力します。