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 服务器发送用户会话。

方法签名

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

Add the matching handler declarations to your game mode header (for example, 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（默认值：0）：设置日志记录的繁琐程度（0-5）。数值越高，日志越详细。
clipboardAttribution（默认值：false，仅限 iOS）：启用从剪贴板读取通用链接属性。
facebookAppId（默认值：空）：设置 Facebook 应用程序 ID，以便整合 Facebook 归因。
customSdid（默认值：空）：设置自定义Singular设备 ID，而不是使用自动生成的标识符。