アンリアル エンジン SDK 統合ガイド
開発者向けガイド | 開発者向けガイド変更履歴 |
前提条件 |
|
互換性 | アンリアル エンジン 4.23 以上 |
インテグレーション ガイド |
SDKのインストール
- SDKアーカイブをダウンロードし、解凍します。
- Project ルートフォルダにPlugins フォルダが存在しない場合は作成します。
- アプリの"Plugins"フォルダ内に"SingularSDK"フォルダを作成します。
-
解凍したアーカイブファイルを"SingularSDK" "フォルダにコピーし、アプリの"Plugins "フォルダにコピーします。
ヒント:プラグインのロード時にバージョン警告が表示されないようにするには、SingularSDK.uplugin ファイルから"EngineVersion" : "4.25.0" 行を削除します。
-
Plugins/SingularSDK/Source/SingularSDK/SingularSDK.Build.cs" を以下のように更新します:
- ファイルの先頭にusing System.IO; を追加します。
-
Target.Platform == UnrealTargetPlatform.IOS :
-
次のように置き換えます。
PublicAdditionalLibraries.Add("sqlite3.0"); PublicAdditionalLibraries.Add("z");
次のようにします:
// System libraries with explicit paths string XcodeSDKPath = "/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/usr/lib"; PublicAdditionalLibraries.AddRange(new string[] { Path.Combine(XcodeSDKPath, "libsqlite3.tbd"), Path.Combine(XcodeSDKPath, "libz.tbd") }); PublicSystemLibraryPaths.Add(XcodeSDKPath);
-
更新
PublicFrameworks.AddRange(new string[] { "AdSupport", "StoreKit", "SystemConfiguration", "Security" });
これで
PublicFrameworks.AddRange(new string[] { "AdSupport", "AppTrackingTransparency", "StoreKit", "SystemConfiguration", "Security", "AdServices", "WebKit", "Singular" });
-
例
using System.IO; // ... if (Target.Platform == UnrealTargetPlatform.IOS) { // ... // System libraries with explicit paths string XcodeSDKPath = "/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk/usr/lib"; PublicAdditionalLibraries.AddRange(new string[] { Path.Combine(XcodeSDKPath, "libsqlite3.tbd"), Path.Combine(XcodeSDKPath, "libz.tbd") }); PublicSystemLibraryPaths.Add(XcodeSDKPath); //.... PublicFrameworks.AddRange(new string[] { "AdSupport", "AppTrackingTransparency", "StoreKit", "SystemConfiguration", "Security", "AdServices", "WebKit", "Singular" }); //... }
- アンリアル プロジェクトを開いている場合は、閉じます。
- プロジェクトを再度開きます。Missing Modules プロンプトが表示されたら、[Yes] を選択して続行します。
- メニューからSingularSDK Plugin を有効にします:"Edit>Plugins" を選択します。Singularを検索する。
-
アプリのBuild.cs ファイル (Source/ProjectName/<YOUR_APP>.Build.cs) のPublicDependencyModuleNames 配列に、依存関係としてSingularSDK を追加する:
PublicDependencyModuleNames.AddRange(new string[] { "Core", "CoreUObject", "Engine", "InputCore", "SingularSDK" });
既知の問題:最初のビルド時に、以下の致命的なエラーが発生する可能性があります:
Plugins/SingularSDK/Source/SingularSDK/Private/SingularSDKBPLibrary.cpp:14:9: fatal error: 'Singular/Singular.h' file not found
この問題を回避するには、以下の手順に従ってください:
- Plugins/SingularSDK/Source/ThirdParty/iOS" からSingular.framework.zip ファイルを展開してください。
- Singular.framework フォルダーを "/Users/Shared/Epic Games/UE_5.5/Engine/Intermediate/UnzippedFrameworks/Singular" に移動する。
-
/Users/Shared/Epic Games/UE_5.5/Engine/Intermediate/UnzippedFrameworks/Singular/Singular.framework/Headers" からSingularConfig.h を開いて修正する。
-
ファイルの先頭に以下の行を追加する:
#pragma clang diagnostic ignored "-Wobjc-property-no-attribute"
-
SDKの初期化
注:Singular SDKを実装する際には、GDPR、CCPA、COPPAを含むがこれに限定されない、ビジネスを行う地域で制定された様々なプライバシー法を遵守することを忘れないでください。詳しくはSDKのオプトインとオプトアウトをご覧ください。
SDK初期化コードは、アプリを開くたびに呼び出す必要があります。これはSingularのすべてのアトリビューション機能の前提条件であり、またユーザー保持の計算に使用される新しいセッションをSingularに送信します。SDKの初期化は、アプリの実行のできるだけ早い段階で行うことをお勧めします。
SDKを初期化するには、SingularSDKBPLibrary クラスのUSingularSDKBPLibrary::Initialize メソッドを呼び出します:
- SDKを初期化するには、ゲームモードのコンストラクタで、iOS用のidfv識別子を出力するのがよいでしょう:
USingularSDKBPLibrary::Initialize Method | |
---|---|
説明 | Singular SDKを初期化し、ユーザーセッションをSingularサーバーに送信します。 |
署名 |
|
使用例 |
|
メソッドのパラメータ
パラメータ | 必須か? | 説明 | デフォルト |
SDKキー | これらのキーを取得するには、Singularアカウントにログインし、"Developer Tools > SDK Integration > SDK Keys"に進みます。 | ||
sdkSecret | |||
セッションタイムアウト |
カスタムセッションタイムアウトを設定します(秒単位)。 | 60 | |
カスタムユーザーID | ユーザーIDをSingularに送信します。詳細は後述 | ||
waitForTrackingAuthorization WithTimeoutInterval | (iOS)ユーザーがデバイス識別子データの共有に同意するか拒否するまで、Singularへのセッション/イベントの送信を遅らせます。詳細は以下をご覧ください。 | False | |
skAdNetworkEnabled | (iOS) Singularにユーザーのコンバージョン値を追跡させるためにTrueに設定します。詳しくはSingularのSKAdNetworkソリューションの紹介をご覧ください。 | False | |
マニュアルSkanConversion管理 | (iOS)SKAdNetworkのコンバージョン値を手動で管理したい場合、Trueに設定します(コード内で自分で設定・更新します)。詳しくはSingularのSKAdNetworkソリューションの紹介を ご覧 ください。 | False | |
oaidCollection | (Android)デバイスのOAIDを収集するにはtrueを設定します。 | False |
ユーザーIDの設定
Singular SDKのメソッドを使用して、内部ユーザーIDをSingularに送信できます。
注意: Singularのクロスデバイスソリューションを使用する場合は、すべてのプラットフォームでユーザーIDを収集する必要があります。
- ユーザーIDはどのような識別子でもかまいませんが、PII(個人を特定できる情報)を公開すべきではありません。例えば、ユーザーのメールアドレス、ユーザー名、電話番号は使用しないでください。Singularは、お客様のファーストパーティデータにのみユニークなハッシュ値を使用することを推奨します。
- Singularに渡すユーザーIDは、すべてのプラットフォーム(ウェブ/モバイル/PC/コンソール/オフライン)で同じ内部ユーザーIDを使用する必要があります。
- Singularはユーザーレベルのエクスポート、ETL、内部BIポストバック(設定されている場合)にユーザーIDを含めます。ユーザーIDはファーストパーティデータであり、Singularが他者と共有することはありません。
- ユーザーIDの値は、Singular SDKメソッドで設定されると、UnsetCustomUserId メソッドで設定が解除されるまで、またはアプリがアンインストールされるまで保持されます。アプリを終了または再起動しても、ユーザーIDはアンセットされません。
ユーザーIDを設定するには、SetCustomUserId メソッドを使用します。設定を解除するには(ユーザがアカウントから「ログアウト」した場合など)、UnsetCustomUserId を呼び出してください。
注:複数のユーザが1つのデバイスを使用する場合、ログインとログアウトのたびにユーザIDを設定および解除するログアウトフローを実装することを推奨します。
アプリを開いたときにユーザーIDがすでに分かっている場合は、Singular SDKを初期化する前にSetCustomUserId 。こうすることで、Singularは最初のセッションからユーザーIDを持つことができます。しかし、ユーザーIDは通常、ユーザーが登録するかログインを実行するまで利用できません。その場合は、登録フローが完了した後にSetCustomUserId 。
SingularSDK SetCustomUserId メソッド | |
---|---|
説明 | ユーザー ID を Singular に送信します。 |
シグネチャ | static void SetCustomUserId(FString customUserId) |
使用例 |
|
SingularSDK UnsetCustomUserId メソッド | |
説明 | Singular に送信されたユーザー ID の設定を解除します。 |
シグネチャ | static void UnsetCustomUserId() |
使用例 |
|
重要:この高度なエンタープライズ機能は例外的な場合にのみ使用できます。実装する前にSingularのソリューションエンジニアにご相談ください。
Singularはサーバー間の統合により、追加のモバイルイベント追跡データを受け取ることができます。この機能を利用するには、ユーザーIDをSingularのモバイルデバイス追跡識別子にマッピングする必要があります。
注意:Singular SDKを初期化した後、またはユーザーIDを取得した後、できるだけ早くこのメソッドを呼び出してください。
SingularSDK SetCustomUserId メソッド | |
---|---|
説明 | ログイン時と同じカスタムユーザーIDを設定し、Singularのトラッキング識別子にマッピングします。 |
シグネチャ | static void SetDeviceCustomUserId(FString customUserId) |
使用例 |
|
iOS 14+ アプリのトラッキングの透明性のサポート
iOS 14+ では、アプリはユーザーデータを共有する前に、デバイスの IDFA 値を使うことも含めて、ユーザーの同意を求めなければなりません(App Tracking Transparency を参照)。Singularは、デバイスを識別し、インストールアトリビューションを実行するために、IDFAを持つことで大きな利益を得ています。そのため、Singular SDKがユーザーセッションとユーザーイベントをSingularサーバーに送信し始める前に、ユーザーの同意を求める必要があります。
SDKがセッションを送信すると、その時点でSingularが利用可能なデータのみに基づいて、Singularのインストールアトリビューションプロセスが開始されます。
SDKがユーザーセッションとユーザーイベントを送信するのを遅らせるには、watefForTrackingAuthorizationWithTimeoutIntervalパラメータでSingular SDKを初期化します。そうすると
- SDKは初期化され、セッションとユーザーイベントの記録を開始しますが、Singularサーバーにはまだ送信されません。
- App Tracking Transparencyの同意が許可/拒否されるか、設定されたタイムアウトが経過するとすぐに、SDKはセッションとキューに入ったイベントをSingularサーバーに送信します(IDFAの有無は問いません)。
- Singularはその後、IDFAが利用可能であればそれを利用してアトリビューションプロセスを開始します。
詳細については、iOS 14 の準備を参照してください。
Unreal Engine SDK 統合ガイド
インテグレーション ガイド |