虚幻引擎 SDK - 基本集成


安装

将 SDK 插件添加到项目的 Plugins 文件夹并在 Unreal Engine 项目中启用,即可安装 Singular Unreal Engine SDK。

安装 SDK

请按以下步骤将 Singular SDK 集成到您的 Unreal Engine 项目中。

  1. 从上方提供的链接下载并解压 SDK 压缩包。
  2. ProjectPlugins 根目录中创建文件夹(若尚不存在)。
  3. 在应用的“Plugins”文件夹中创建“SingularSDK”文件夹。
  4. 将解压后的文件复制到应用 Plugins 文件夹下的“SingularSDK”文件夹中。

    项目文件夹树,Plugins 目录下包含 SingularSDK 插件,其中含有 Resources、Source 和 SingularSDK.uplugin。

  5. 如果 Unreal 项目处于打开状态,请先关闭。
  6. 重新打开项目。如果出现 Missing Modules 提示,请选择 Yes 继续。
    Unreal Engine 对话框,询问是否重新构建缺失的 SingularSDK 模块。
  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 framework 头文件相关的致命错误。

已知问题: 首次构建时您可能会遇到以下致命错误:

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);
}

将对应的处理程序声明添加到您的 game mode 头文件中(例如 AMyProject2GameMode.h):

UFUNCTION()
void OnSingularSdidReceived(const FString result);

UFUNCTION()
void OnSingularDidSetSdid(const FString result);

配置参数

必需参数

这些参数是 SDK 初始化所必需的。从 Singular 面板获取您的凭据。

  • sdkKey:您的 Singular SDK 密钥,可从 Singular 账户中的"开发工具 > SDK 集成 > SDK 密钥"中获取。
  • sdkSecret:您的 Singular SDK 密钥,可从 Singular 账户中的同一位置获取。

重要提示:请妥善保管 SDK 证书,不要将其提交到公共版本控制库。


可选参数

使用这些可选配置参数自定义 SDK 行为。

  • sessionTimeout(默认值:60):设置自定义会话超时(以秒为单位)。在这段时间内未活动,当用户返回应用程序时会创建一个新会话。
  • customUserId(默认值:空):了解有关自定义用户 ID 的更多信息
  • skAdNetworkEnabled(默认值:true,仅限 iOS):为 iOS 归因启用 SKAdNetwork 支持。请参阅Singular 的 SKAdNetwork 解决方案介绍
  • manualSkanConversionManagement(默认值:false,仅限 iOS):设为 true 可手动管理 SKAdNetwork 转换值,而不是让 Singular 自动处理。
  • waitForTrackingAuthorizationWithTimeoutInterval(默认值:0,仅限 iOS):延迟向 Singular 发送会话/事件,直到用户回复 ATT(应用程序跟踪透明度)提示或超时。了解有关 ATT 支持的更多信息
  • oaidCollection(默认:false,仅限 Android):设置为 "true "可在 Android 设备上收集设备的 OAID(开放式匿名设备标识符)。
  • enableLogging(默认值:false):启用 SDK 调试日志以排除故障。在生产构建中应禁用。
  • logLevel(默认值:3):仅限 Android。使用 android.util.Log 级别,2 Verbose 至 7 Assert,数值越小越详细。
  • clipboardAttribution(默认值:false,仅限 iOS):启用从剪贴板读取通用链接属性。
  • facebookAppId(默认值:空):设置 Facebook 应用程序 ID,以便整合 Facebook 归因。
  • customSdid(默认值:空):设置自定义Singular设备 ID,而不是使用自动生成的标识符。