Unreal Engine SDK - 基本的な統合


インストール

SDK プラグインをプロジェクトの Plugins フォルダに追加し、Unreal Engine プロジェクトで有効化して Singular Unreal Engine SDK をインストールします。

SDK のインストール

以下の手順に従って、Singular SDK を Unreal Engine プロジェクトに統合してください。

  1. 上記のリンクから SDK アーカイブをダウンロードして展開します。
  2. Projectのルートフォルダに Plugins フォルダが存在しない場合は作成します。
  3. アプリの「Plugins」フォルダ内に「SingularSDK」フォルダを作成します。
  4. 展開したアーカイブファイルを、アプリの Plugins フォルダ内の「SingularSDK」フォルダにコピーします。

    PluginsディレクトリにSingularSDKプラグインが配置されたプロジェクトのフォルダーツリー。Resources、Source、SingularSDK.upluginが含まれています。

  5. Unreal プロジェクトが開いている場合は閉じます。
  6. プロジェクトを再度開きます。Missing Modules のプロンプトが表示されたら、Yes を選択して続行します。
    不足しているSingularSDKモジュールを再ビルドするかどうかを尋ねるUnreal Engineのダイアログ。
  7. メニュー「Edit>Plugins」から SingularSDK Plugin を有効化します。Singular を検索してください。
    「Singular」でフィルタリングしたUnreal Engineのプラグインブラウザ。有効化されたSingular SDK Pluginバージョン2.5.0が表示されています。
  8. アプリの Build.cs ファイル(Source/ProjectName/<YOUR_APP>.Build.cs)の PublicDependencyModuleNames 配列に SingularSDK を依存関係として追加します。

    C++
    PublicDependencyModuleNames.AddRange(new string[] { 
        "Core", 
        "CoreUObject",
        "Engine", 
        "InputCore", 
        "SingularSDK" 
    });

既知のインストール上の問題

初回ビルド時に、Singular フレームワークのヘッダーファイルに関する致命的なエラーが発生する場合があります。

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

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」に移動します。
UnzippedFrameworks内にネストされたSingular.frameworkを示すファイルブラウザ。内側のSingular.frameworkフォルダーがハイライトされています。

SDKの初期化

アプリを起動するたびにSingular SDKを初期化し、アトリビューショントラッキング、セッション管理、イベントレポートを有効にします。

SDID について

SDID(Singular Device ID)は、Singular が生成・管理するデバイスレベルの識別子です。この SDK がアプリで動作し、サーバーからも Server-to-Server(S2S)API 経由でイベントを送信するハイブリッド連携では、同じ SDID をサーバー側のイベントに付与することで、それらのイベントを SDK がトラッキングしているのと同じデバイスに結び付けられます。これにより、Singular はプラットフォーム固有の広告識別子に依存せず、SDK と S2S のアクティビティを単一のデバイスにアトリビューションできます。

デフォルトで有効なSDID: 2026年7月15日より、新規Singularのお客様ではSDID(Singular Device ID)がデフォルトで有効になります。SDKが初期化時にSDIDを自動的に生成・解決するため、追加の設定は必要ありません。以下の例ではSDID受信コールバックを登録し、SDKがSDIDを受信したことをログで確認できるようにしています。

カスタムSDIDはエンタープライズ機能です: カスタムSDIDの設定はエンタープライズ機能であり、デフォルトでは有効になっていません。アカウントで有効化されていない限り、カスタムSDIDを設定しないでください。担当のSingular Customer Success Managerにお問い合わせください。以下の例では意図的にカスタムSDIDを設定していません。

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

SDKを初期化する理由

SDKの初期化は、Singularのすべてのアトリビューション機能の前提条件です。 ユーザーのリテンションメトリックスを計算するために、Singularに送信される新しいセッションを作成します。

ベストプラクティスです:ゲームモードのコンストラクタなど、アプリのライフサイクルのできるだけ早い段階でSDKを初期化します。


初期化メソッド

USingularSDKBPLibrary::Initialize

Initialize メソッドをコールしてSingular SDKを起動し、ユーザーセッションをSingularサーバーに送信します。

メソッドのシグネチャ

C++
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,
    bool enableLogging = false,
    int logLevel = 3,
    bool clipboardAttribution = false,
    FString facebookAppId = TEXT(""),
    FString customSdid = TEXT("")
);

実装例

ゲームモードのコンストラクタで、API認証情報と設定オプションを使用してSDKを初期化します。

C++
// Copyright Epic Games, Inc. All Rights Reserved.

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

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

AMyProject2GameMode::AMyProject2GameMode()
    : Super()
{
#if PLATFORM_IOS
    // Log IDFV for iOS testing
    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

    // Register the SDID accessor handler before initialization to confirm the SDK
    // received the SDID (SDID is enabled by default for new accounts)
    USingularDelegates* SingularDelegates = CreateDefaultSubobject<USingularDelegates>(TEXT("SingularSdidAccessorHandler"));
    SingularDelegates->OnSingularSdidReceived.AddDynamic(this, &AMyProject2GameMode::OnSingularSdidReceived);
    SingularDelegates->OnSingularDidSetSdid.AddDynamic(this, &AMyProject2GameMode::OnSingularDidSetSdid);

    // Initialize Singular SDK
    bool Success = USingularSDKBPLibrary::Initialize(
        "YOUR_SDK_KEY",        // API Key from Singular dashboard
        "YOUR_SDK_SECRET",      // Secret from Singular dashboard
        60,                      // Session timeout in 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
        true,                    // Enable logging for debugging
        3,                       // Log level (0-5, higher = more verbose)
        false,                   // Clipboard attribution
        TEXT(""),               // Facebook App ID (optional)
        TEXT("")                // Custom SDID (optional)
    );

    if (Success)
    {
        UE_LOG(LogTemp, Log, TEXT("Singular SDK initialized successfully"));
    }
    else
    {
        UE_LOG(LogTemp, Error, TEXT("Failed to initialize Singular SDK"));
    }

    // Set default pawn class
    static ConstructorHelpers::FClassFinder<APawn> PlayerPawnClassFinder(
        TEXT("/Game/FirstPerson/Blueprints/BP_FirstPersonCharacter")
    );
    DefaultPawnClass = PlayerPawnClassFinder.Class;
}

void AMyProject2GameMode::OnSingularSdidReceived(const FString result)
{
    UE_LOG(LogTemp, Log, TEXT("Singular SDID received: %s"), *result);
}

void AMyProject2GameMode::OnSingularDidSetSdid(const FString result)
{
    UE_LOG(LogTemp, Log, TEXT("Singular SDID set: %s"), *result);
}

ゲームモードのヘッダー(例:AMyProject2GameMode.h)に、対応するハンドラーの宣言を追加します:

UFUNCTION()
void OnSingularSdidReceived(const FString result);

UFUNCTION()
void OnSingularDidSetSdid(const FString result);

設定パラメータ

必須パラメータ

これらのパラメータはSDKの初期化に必要です。Singularダッシュボードから認証情報を取得してください。

  • sdkKey:Singularアカウントの"Developer Tools > SDK Integration > SDK Keys"からSingular SDK Keyを取得します。
  • sdkSecret:Singularアカウントの同じ場所からお客様のSingular SDK Secretを取得します。

重要:SDK認証情報は安全に保管し、公開バージョン管理リポジトリにコミットしないでください。


オプションのパラメータ

オプションの設定パラメータでSDKの動作をカスタマイズします。

  • sessionTimeout(デフォルト: 60):カスタムセッションタイムアウトを秒単位で設定します。この非アクティブ時間が経過すると、ユーザーがアプリに戻ったときに新しいセッションが作成されます。
  • customUserId(デフォルト:空):初期化時にカスタムユーザーIDを設定します。カスタムユーザーIDについてはこちらをご覧ください
  • skAdNetworkEnabled(デフォルト:true、iOSのみ):iOSアトリビューション用のSKAdNetworkサポートを有効にします。SingularのSKAdNetworkソリューションの紹介をご覧ください。
  • manualSkanConversionManagement(デフォルト:false、iOSのみ):Singularが自動的にSKAdNetworkの変換値を処理するのではなく、手動で管理する場合はtrueに設定します。
  • waitForTrackingAuthorizationWithTimeoutInterval(デフォルト:0、iOSのみ):ユーザーがATT(App Tracking Transparency)のプロンプトに応答するか、タイムアウトが経過するまで、Singularへのセッション/イベントの送信を遅らせます。ATTのサポートについてはこちらをご覧ください
  • oaidCollection(デフォルト:false、Androidのみ):AndroidデバイスでデバイスのOAID(Open Anonymous Device Identifier)を収集するには、trueに設定します。
  • enableLogging(デフォルト:false):トラブルシューティングのためにSDKデバッグ・ロギングを有効にします。本番ビルドでは無効にする必要があります。
  • logLevel(デフォルト: 3): Android専用です。android.util.Logのレベル(2 Verbose〜7 Assert)を使用し、数値が小さいほど詳細になります。
  • clipboardAttribution(Default:false、iOSのみ): ユニバーサルリンクの属性のためにクリップボードからの読み込みを有効にします。
  • facebookAppId(デフォルト: 空):Facebookアトリビューション統合のためにFacebookアプリIDを設定します。
  • customSdid(デフォルト:空):自動生成された識別子を使用する代わりに、カスタムSingular Device IDを設定します。