Unreal Engine SDK - 基本的な統合

ドキュメント

アンリアル エンジン SDK 統合ガイド

開発者向けガイド 開発者向けガイド変更履歴
前提条件
互換性 アンリアル エンジン 4.23 以上
インテグレーション ガイド
  1. 基本的なインテグレーション
  2. イベントと収益のトラッキング
  3. ディープリンクの実装
  4. SKAdNetwork サポートの追加
  5. 詳細オプション

SDKのインストール

  1. SDKアーカイブをダウンロードし、解凍します。
  2. Project ルートフォルダにPlugins フォルダが存在しない場合は作成します。
  3. アプリの"Plugins"フォルダ内に"SingularSDK"フォルダを作成します。
  4. 解凍したアーカイブファイルを"SingularSDK" "フォルダにコピーし、アプリの"Plugins "フォルダにコピーします。

    unreal_sdk_install.png

    ヒント:プラグインのロード時にバージョン警告が表示されないようにするには、SingularSDK.uplugin ファイルから"EngineVersion" : "4.25.0" 行を削除します。

  5. 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"
         });
         //...
    }
  6. アンリアル プロジェクトを開いている場合は、閉じます。
  7. プロジェクトを再度開きます。Missing Modules プロンプトが表示されたら、[Yes] を選択して続行します。
    unrealModules.png
  8. メニューからSingularSDK Plugin を有効にします:"Edit>Plugins" を選択します。Singularを検索する。
    unreal_plugin_enabled.png
  9. アプリのBuild.cs ファイル (Source/ProjectName/<YOUR_APP>.Build.cs) のPublicDependencyModuleNames 配列に、依存関係としてSingularSDK を追加する:
    app_build.png

    PublicDependencyModuleNames.AddRange(new string[] { "Core", "CoreUObject",
      "Engine", "InputCore", "SingularSDK" });
ビルド時の既知の問題: 致命的なエラー: 'Singular/Singular.h' ファイルが見つかりません。

既知の問題:最初のビルド時に、以下の致命的なエラーが発生する可能性があります:

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"
      config_update.png
framework.png

SDKの初期化

:Singular SDKを実装する際には、GDPR、CCPA、COPPAを含むがこれに限定されない、ビジネスを行う地域で制定された様々なプライバシー法を遵守することを忘れないでください。詳しくはSDKのオプトインとオプトアウトをご覧ください。

SDK初期化コードは、アプリを開くたびに呼び出す必要があります。これはSingularのすべてのアトリビューション機能の前提条件であり、またユーザー保持の計算に使用される新しいセッションをSingularに送信します。SDKの初期化は、アプリの実行のできるだけ早い段階で行うことをお勧めします。

SDKを初期化するには、SingularSDKBPLibrary クラスのUSingularSDKBPLibrary::Initialize メソッドを呼び出します:

  • SDKを初期化するには、ゲームモードのコンストラクタで、iOS用のidfv識別子を出力するのがよいでしょう:
USingularSDKBPLibrary::Initialize Method
説明 Singular SDKを初期化し、ユーザーセッションをSingularサーバーに送信します。
署名
static bool Initialize(FString sdkKey, FString sdkSecret,
       int sessionTimeout = 60,
       FString customUserId = TEXT(""),
       bool skAdNetworkEnabled = true,
       bool manualSkanConversionManagement = false,
       int waitForTrackingAuthorizationWithTimeoutInterval = 0,
       bool oaidCollection = false);
使用例
// Copyright Epic Games, Inc. All Rights Reserved.

#include "MyProject2GameMode.h"
#include "MyProject2Character.h"
#include "UObject/ConstructorHelpers.h"
#include "SingularSDKBPLibrary.h"

#if PLATFORM_IOS
#include "IOS/IOSPlatformMisc.h"
#import 
#endif

AMyProject2GameMode::AMyProject2GameMode()
	: Super()
{
	#if PLATFORM_IOS
    NSString *idfv = [[UIDevice currentDevice] identifierForVendor].UUIDString;
    if (idfv)
    {
        FString IDFVString = FString(idfv);
        UE_LOG(LogTemp, Log, TEXT("IDFV: %s"), *IDFVString);
    }
    else
    {
        UE_LOG(LogTemp, Warning, TEXT("Failed to retrieve IDFV"));
    }
#endif

	USingularSDKBPLibrary::Initialize(
            "SDK KEY",    // API Key from config
            "SDK SECRET", // Secret from config
            60,                // Session timeout (seconds)
            TEXT(""),          // Custom user ID (optional)
            true,              // Enable SKAdNetwork for iOS
            false,             // Manual SKAdNetwork conversion management
            30,                // Wait 30 seconds for ATT prompt
            false              // Disable OAID collection (iOS-specific)
        );
	
	// set default pawn class to our Blueprinted character
	static ConstructorHelpers::FClassFinder PlayerPawnClassFinder(TEXT("/Game/FirstPerson/Blueprints/BP_FirstPersonCharacter"));
	DefaultPawnClass = PlayerPawnClassFinder.Class;

}

メソッドのパラメータ

パラメータ 必須か? 説明 デフォルト
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)
使用例
USingularSDKBPLibrary::SetCustomUserId("custom_user_id");
SingularSDK UnsetCustomUserId メソッド
説明 Singular に送信されたユーザー ID の設定を解除します。
シグネチャ static void UnsetCustomUserId()
使用例
USingularSDKBPLibrary::UnsetCustomUserId();

オプション:カスタムユーザーID デバイスマッピング

重要:この高度なエンタープライズ機能は例外的な場合にのみ使用できます。実装する前にSingularのソリューションエンジニアにご相談ください。

Singularはサーバー間の統合により、追加のモバイルイベント追跡データを受け取ることができます。この機能を利用するには、ユーザーIDをSingularのモバイルデバイス追跡識別子にマッピングする必要があります。

注意:Singular SDKを初期化した後、またはユーザーIDを取得した後、できるだけ早くこのメソッドを呼び出してください。

SingularSDK SetCustomUserId メソッド
説明 ログイン時と同じカスタムユーザーIDを設定し、Singularのトラッキング識別子にマッピングします。
シグネチャ static void SetDeviceCustomUserId(FString customUserId)
使用例
USingularSDKBPLibrary::SetDeviceCustomUserId("custom_user_id");


iOS 14+ アプリのトラッキングの透明性のサポート

iOS 14+ では、アプリはユーザーデータを共有する前に、デバイスの IDFA 値を使うことも含めて、ユーザーの同意を求めなければなりません(App Tracking Transparency を参照)。Singularは、デバイスを識別し、インストールアトリビューションを実行するために、IDFAを持つことで大きな利益を得ています。そのため、Singular SDKがユーザーセッションとユーザーイベントをSingularサーバーに送信し始める前に、ユーザーの同意を求める必要があります。

SDKがセッションを送信すると、その時点でSingularが利用可能なデータのみに基づいて、Singularのインストールアトリビューションプロセスが開始されます。

SDKがユーザーセッションとユーザーイベントを送信するのを遅らせるには、watefForTrackingAuthorizationWithTimeoutIntervalパラメータでSingular SDKを初期化します。そうすると

  1. SDKは初期化され、セッションとユーザーイベントの記録を開始しますが、Singularサーバーにはまだ送信されません。
  2. App Tracking Transparencyの同意が許可/拒否されるか、設定されたタイムアウトが経過するとすぐに、SDKはセッションとキューに入ったイベントをSingularサーバーに送信します(IDFAの有無は問いません)。
  3. Singularはその後、IDFAが利用可能であればそれを利用してアトリビューションプロセスを開始します。

詳細については、iOS 14 の準備を参照してください。