安装

通过将SDK插件添加到您的项目的Plugins文件夹中并在您的虚幻引擎项目中启用它来安装Singular虚幻引擎SDK。

安装SDK

请按照以下步骤将Singular SDK集成到您的虚幻引擎项目中。

从上面提供的链接中下载并解压SDK压缩包。
在Project 根文件夹中创建一个Plugins 文件夹（如果该文件夹不存在）。
在您应用程序的 "Plugins" 文件夹中创建一个文件夹 "SingularSDK"。
将提取的存档文件复制到您应用程序的 "Plugins" 文件夹中的 "SingularSDK"" 文件夹。
关闭当前打开的虚幻项目。
重新打开项目。如果出现 "缺少模块 "提示，请选择 "是 "继续。
从菜单中启用SingularSDK Plugin ："Edit>Plugins"。搜索 Singular。
在应用程序的Build.cs 文件中将SingularSDK 作为PublicDependencyModuleNames数组的依赖项 (Source/ProjectName/<YOUR_APP>.Build.cs)。
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"

SDK 初始化

每次启动应用程序时初始化 Singular SDK，以启用归因跟踪、会话管理和事件报告。

隐私合规性：在实施 Singular SDK 时，切记遵守业务所在地区颁布的隐私法，包括 GDPR、CCPA 和 COPPA。如需了解更多信息，请参阅SDK 选择加入和选择退出实践。

为什么要初始化 SDK

SDK初始化是所有Singular归因功能的先决条件，它会创建一个新的会话发送给Singular，用于计算用户留存指标。

最佳实践：在应用程序的生命周期中尽早初始化 SDK，例如在游戏模式构造函数中。

初始化方法

USingularSDKBPLibrary::Initialize

调用 Initialize 方法启动 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,
    bool enableLogging = false,
    int logLevel = 0,
    bool clipboardAttribution = false,
    FString facebookAppId = TEXT(""),
    FString customSdid = TEXT("")
);

实现示例

在游戏模式构造函数中使用 API 凭据和配置选项初始化 SDK。

// 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 <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

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

配置参数

必需参数

这些参数是 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（默认值：0）：设置日志记录的繁琐程度（0-5）。数值越高，日志越详细。
clipboardAttribution（默认值：false，仅限 iOS）：启用从剪贴板读取通用链接属性。
facebookAppId（默认值：空）：设置 Facebook 应用程序 ID，以便整合 Facebook 归因。
customSdid（默认值：空）：设置自定义奇异设备 ID，而不是使用自动生成的标识符。

虚幻引擎 SDK - 基本集成

安装

安装SDK

已知安装问题

SDK 初始化

为什么要初始化 SDK

初始化方法

USingularSDKBPLibrary::Initialize

方法签名

实现示例

配置参数

必需参数

可选参数