文档

虚幻引擎 SDK 集成指南

开发人员指南	开发人员变更日志
前提条件	奇异账户访问权限下载： Singular 虚幻引擎 SDK 2.5.0 版
兼容性	虚幻引擎 4.23+
集成指南	基本集成跟踪事件和收入实现深度链接添加SKAdNetwork支持高级选项

安装 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"
     });
     //...
}

关闭已打开的虚幻项目。
重新打开项目。如果出现 "缺少模块 "提示，请选择 "是 "继续。
从菜单中启用SingularSDK Plugin ："Edit>Plugins"。搜索 Singular。
在应用程序的Build.cs 文件中将SingularSDK 作为PublicDependencyModuleNames 数组的依赖项 (Source/ProjectName/<YOUR_APP>.Build.cs)：
```
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"
```

初始化 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;

}

方法参数

参数	是否需要？	说明	默认值
sdkKey		要获取这些密钥，请登录 Singular 账户，进入"开发工具 > SDK 集成 > SDK 密钥"页面。
sdkSecret
会话超时		设置自定义会话超时（以秒为单位）。	60
自定义用户 ID		向 Singular 发送用户 ID。了解更多详情
waitForTrackingAuthorization（等待跟踪授权）WithTimeoutInterval（超时间隔		(iOS）延迟向 Singular 发送会话/事件，直到用户同意或拒绝共享其设备标识符数据。了解更多信息	假
skAdNetworkEnabled		(iOS）设置为"True "可让 Singular 跟踪用户的转换值。更多信息，请参阅Singular 的 SKAdNetwork 解决方案介绍。	否
手动转换管理		(iOS)如果您想手动管理 SKAdNetwork 转换值（在代码中自行设置和更新），则设置为 "True"。更多信息，请参阅 Singular 的 SKAdNetwork 解决方案介绍。	假
oaidCollection		(Android）设为 "true "可收集设备的 OAID。	假

设置用户 ID

您可以使用 Singular SDK 方法向 Singular 发送内部用户 ID。

注意：如果使用Singular 的跨设备解决方案，则必须在所有平台上收集用户 ID。

用户 ID 可以是任何标识符，但不应暴露 PII（个人身份信息）。例如，不应使用用户的电子邮件地址、用户名或电话号码。Singular 建议使用仅对第一方数据唯一的哈希值。
传递给Singular的用户ID值也应该是你在所有平台（Web/移动/PC/控制台/离线）上获取的相同的内部用户ID。
Singular 将在用户级导出、ETL 和内部 BI 回传（如果配置）中包含用户 ID。用户 ID 是第一方数据，Singular 不会与其他方共享。
使用 Singular SDK 方法设置的用户 ID 值将一直存在，直到使用UnsetCustomUserId 方法取消设置或卸载应用程序为止。关闭或重启应用程序不会取消设置用户 ID。

要设置用户 ID，请使用SetCustomUserId 方法。要取消设置（例如，如果用户 "注销 "账户），请致电UnsetCustomUserId 。

注意：如果多个用户使用一台设备，我们建议实施注销流程，为每次登录和注销设置和取消设置用户 ID。

如果已经知道应用程序打开时的用户 ID，请在初始化 Singular SDK 之前调用SetCustomUserId 。这样，Singular 就能从第一次会话中获得用户 ID。不过，在用户注册或登录之前，用户 ID 通常是不可用的。在这种情况下，请在注册流程完成后调用SetCustomUserId 。

SingularSDK 设置自定义用户 ID 方法
说明	向 Singular 发送用户 ID。
签名	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 值（请参阅 "应用程序跟踪透明度"）。拥有 IDFA 可以识别设备并执行安装归因，Singular 从中获益匪浅。因此，在Singular SDK 开始向 Singular 服务器发送用户会话和用户事件之前，您应该征求用户同意。

一旦SDK发送了会话，就会触发Singular的安装归因流程，该流程仅基于Singular当时可用的数据。

要延迟 SDK 发送用户会话和用户事件，可使用waitForTrackingAuthorizationWithTimeoutInterval参数初始化 Singular SDK。如果这样做

SDK 将被初始化并开始记录会话和用户事件，但不会将其发送到Singular 服务器。
一旦授予/拒绝了 App Tracking Transparency 同意，或者设定的超时结束，SDK 就会将会话和任何排队的事件发送到 Singular 服务器（无论是否有 IDFA）。
然后，Singular 将利用可用的 IDFA 启动归属过程。

如需了解更多信息，请参阅为 iOS 14 做准备。