虚幻引擎 SDK - 配置方法参考

关注
Avatar
Jared Ornstead
Updated
文档

虚幻引擎 SDK - 配置参考

通过 Initialize 方法参数配置 Singular Unreal Engine SDK。本参考记录了所有可用的配置选项及其类型、默认值和使用示例。

apiKey

API 密钥（必填）

从 Singular 面板获取的您的 Singular API 密钥。初始化 SDK 和识别应用程序时需要此密钥。

签名

C++ 
FString apiKey

使用示例

C++ 
FString ApiKey = TEXT("your_singular_api_key");

USingularSDKBPLibrary::Initialize(
    ApiKey,
    ApiSecret,
    // ... other parameters
);

apiSecret

API 密钥（必填）

从 Singular 面板获取的您的 Singular API Secret。初始化 SDK 和验证应用程序时需要此密文。

签名

C++ 
FString apiSecret

使用示例

C++ 
FString ApiSecret = TEXT("your_singular_api_secret");

USingularSDKBPLibrary::Initialize(
    ApiKey,
    ApiSecret,
    // ... other parameters
);

剪贴板属性

剪贴板属性

启用从剪贴板读取数据以支持 iOS 通用链接属性，从而提高跟踪准确性（仅限 iOS）。

签名

C++ 
bool clipboardAttribution
// Default: false

使用示例

C++ 
// Enable clipboard attribution for iOS
bool ClipboardAttribution = true;

USingularSDKBPLibrary::Initialize(
    ApiKey,
    ApiSecret,
    60,                        // sessionTimeout
    TEXT(""),                  // customUserId
    true,                      // skAdNetworkEnabled
    false,                     // manualSkanConversionManagement
    0,                         // waitForTrackingAuthorizationWithTimeoutInterval
    false,                     // oaidCollection
    false,                     // enableLogging
    0,                         // logLevel
    ClipboardAttribution,      // Enable clipboard attribution
    TEXT(""),                  // facebookAppId
    TEXT("")                   // customSdid
);

自定义设备 ID

自定义单个设备 ID

设置自定义单个设备 ID（SDID），而不是使用自动生成的设备标识符。

签名

C++ 
FString customSdid
// Default: TEXT("")

使用示例

C++ 
// Set custom SDID
FString CustomSdid = TEXT("custom_device_id_12345");

USingularSDKBPLibrary::Initialize(
    ApiKey,
    ApiSecret,
    60,                        // sessionTimeout
    TEXT(""),                  // customUserId
    true,                      // skAdNetworkEnabled
    false,                     // manualSkanConversionManagement
    0,                         // waitForTrackingAuthorizationWithTimeoutInterval
    false,                     // oaidCollection
    false,                     // enableLogging
    0,                         // logLevel
    false,                     // clipboardAttribution
    TEXT(""),                  // facebookAppId
    CustomSdid                 // Custom SDID
);

自定义用户 ID

自定义用户 ID

在初始化时设置自定义用户标识符，以便使用自己的 ID 系统跨设备跟踪用户。

签名

C++ 
FString customUserId
// Default: TEXT("")

使用示例

C++ 
// Set custom user ID at initialization
FString CustomUserId = TEXT("user_xyz789");

USingularSDKBPLibrary::Initialize(
    ApiKey,
    ApiSecret,
    60,                        // sessionTimeout
    CustomUserId,              // Set custom user ID
    true,                      // skAdNetworkEnabled
    false,                     // manualSkanConversionManagement
    0,                         // waitForTrackingAuthorizationWithTimeoutInterval
    false,                     // oaidCollection
    false,                     // enableLogging
    0,                         // logLevel
    false,                     // clipboardAttribution
    TEXT(""),                  // facebookAppId
    TEXT("")                   // customSdid
);

启用日志记录

启用日志记录

为调试目的启用 SDK 日志。在生产构建中应禁用。

签名

C++ 
bool enableLogging
// Default: false

使用示例

C++ 
// Enable logging for development builds
bool EnableLogging = true;
int LogLevel = 5;  // Verbose logging

USingularSDKBPLibrary::Initialize(
    ApiKey,
    ApiSecret,
    60,                        // sessionTimeout
    TEXT(""),                  // customUserId
    true,                      // skAdNetworkEnabled
    false,                     // manualSkanConversionManagement
    0,                         // waitForTrackingAuthorizationWithTimeoutInterval
    false,                     // oaidCollection
    EnableLogging,             // Enable logging
    LogLevel,                  // Set log level
    false,                     // clipboardAttribution
    TEXT(""),                  // facebookAppId
    TEXT("")                   // customSdid
);

facebookAppId

Facebook 应用程序 ID

设置 Facebook 应用程序 ID 以启用 Facebook 归因整合。

签名

C++ 
FString facebookAppId
// Default: TEXT("")

使用示例

C++ 
// Set Facebook App ID for attribution
FString FacebookAppId = TEXT("123456789012345");

USingularSDKBPLibrary::Initialize(
    ApiKey,
    ApiSecret,
    60,                        // sessionTimeout
    TEXT(""),                  // customUserId
    true,                      // skAdNetworkEnabled
    false,                     // manualSkanConversionManagement
    0,                         // waitForTrackingAuthorizationWithTimeoutInterval
    false,                     // oaidCollection
    false,                     // enableLogging
    0,                         // logLevel
    false,                     // clipboardAttribution
    FacebookAppId,             // Facebook App ID
    TEXT("")                   // customSdid
);

日志级别

日志级别

设置 SDK 日志的冗长程度。数值越高，日志越详细。有效范围：0-5.

签名

C++ 
int logLevel
// Default: 0
// Valid range: 0 (minimal) to 5 (verbose)

使用示例

C++ 
// Set verbose logging for debugging
int LogLevel = 5;

USingularSDKBPLibrary::Initialize(
    ApiKey,
    ApiSecret,
    60,                        // sessionTimeout
    TEXT(""),                  // customUserId
    true,                      // skAdNetworkEnabled
    false,                     // manualSkanConversionManagement
    0,                         // waitForTrackingAuthorizationWithTimeoutInterval
    false,                     // oaidCollection
    true,                      // enableLogging
    LogLevel,                  // Set log level to verbose
    false,                     // clipboardAttribution
    TEXT(""),                  // facebookAppId
    TEXT("")                   // customSdid
);

manualSkanConversionManagement

手动 SKAdNetwork 转换管理

启用对 SKAdNetwork 转换值更新的手动控制，而非自动管理（仅限 iOS）。

签名

C++ 
bool manualSkanConversionManagement
// Default: false

使用示例

C++ 
// Enable manual SKAN conversion management
bool ManualSkanManagement = true;

USingularSDKBPLibrary::Initialize(
    ApiKey,
    ApiSecret,
    60,                        // sessionTimeout
    TEXT(""),                  // customUserId
    true,                      // skAdNetworkEnabled
    ManualSkanManagement,      // Enable manual SKAN management
    0,                         // waitForTrackingAuthorizationWithTimeoutInterval
    false,                     // oaidCollection
    false,                     // enableLogging
    0,                         // logLevel
    false,                     // clipboardAttribution
    TEXT(""),                  // facebookAppId
    TEXT("")                   // customSdid
);

// Later, manually update conversion value
USingularSDKBPLibrary::SkanUpdateConversionValue(15);

oaidCollection

OAID 收集

启用收集中国 Android 设备的开放式匿名标识符（OAID）（仅限 Android）。

签名

C++ 
bool oaidCollection
// Default: false

使用示例

C++ 
// Enable OAID collection for Chinese Android devices
bool OaidCollection = true;

USingularSDKBPLibrary::Initialize(
    ApiKey,
    ApiSecret,
    60,                        // sessionTimeout
    TEXT(""),                  // customUserId
    true,                      // skAdNetworkEnabled
    false,                     // manualSkanConversionManagement
    0,                         // waitForTrackingAuthorizationWithTimeoutInterval
    OaidCollection,            // Enable OAID collection
    false,                     // enableLogging
    0,                         // logLevel
    false,                     // clipboardAttribution
    TEXT(""),                  // facebookAppId
    TEXT("")                   // customSdid
);

会话超时

会话超时

设置会话超时（以秒为单位）。超时后，用户返回时将启动新会话。

签名

C++ 
int sessionTimeout
// Default: 60 (seconds)

使用示例

C++ 
// Set session timeout to 5 minutes
int SessionTimeout = 300;  // 5 minutes in seconds

USingularSDKBPLibrary::Initialize(
    ApiKey,
    ApiSecret,
    SessionTimeout,            // 5 minute session timeout
    TEXT(""),                  // customUserId
    true,                      // skAdNetworkEnabled
    false,                     // manualSkanConversionManagement
    0,                         // waitForTrackingAuthorizationWithTimeoutInterval
    false,                     // oaidCollection
    false,                     // enableLogging
    0,                         // logLevel
    false,                     // clipboardAttribution
    TEXT(""),                  // facebookAppId
    TEXT("")                   // customSdid
);

skAdNetworkEnabled

启用 SKAdNetwork

启用 SKAdNetwork 支持，以便通过 Apple 的隐私保护框架进行 iOS 归属跟踪（仅限 iOS）。

签名

C++ 
bool skAdNetworkEnabled
// Default: true

使用示例

C++ 
// Enable SKAdNetwork for iOS attribution
bool SkAdNetworkEnabled = true;

USingularSDKBPLibrary::Initialize(
    ApiKey,
    ApiSecret,
    60,                        // sessionTimeout
    TEXT(""),                  // customUserId
    SkAdNetworkEnabled,        // Enable SKAdNetwork
    false,                     // manualSkanConversionManagement
    0,                         // waitForTrackingAuthorizationWithTimeoutInterval
    false,                     // oaidCollection
    false,                     // enableLogging
    0,                         // logLevel
    false,                     // clipboardAttribution
    TEXT(""),                  // facebookAppId
    TEXT("")                   // customSdid
);

waitForTrackingAuthorizationWithTimeoutInterval

带超时间隔的跟踪授权等待

以秒为单位设置超时时间，以便在初始化 SDK 之前等待用户回复 ATT（App Tracking Transparency）提示（仅限 iOS 14+）。

签名

C++ 
int waitForTrackingAuthorizationWithTimeoutInterval
// Default: 0 (no waiting)
// Recommended: 60-300 seconds

使用示例

C++ 
// Wait up to 5 minutes for ATT authorization
int WaitTimeout = 300;  // 5 minutes

USingularSDKBPLibrary::Initialize(
    ApiKey,
    ApiSecret,
    60,                        // sessionTimeout
    TEXT(""),                  // customUserId
    true,                      // skAdNetworkEnabled
    false,                     // manualSkanConversionManagement
    WaitTimeout,               // Wait for ATT authorization
    false,                     // oaidCollection
    false,                     // enableLogging
    0,                         // logLevel
    false,                     // clipboardAttribution
    TEXT(""),                  // facebookAppId
    TEXT("")                   // customSdid
);

完整配置示例

完整 SDK 配置

示例显示设置了所有配置选项的完整 SDK 初始化。

C++ 
// Complete configuration example
FString ApiKey = TEXT("SDK KEY");
FString ApiSecret = TEXT("SDK SECRET");
int SessionTimeout = 60;
FString CustomUserId = TEXT("user_12345");
bool SkAdNetworkEnabled = true;
bool ManualSkanConversionManagement = false;
int WaitForTrackingAuthorizationTimeout = 300;
bool OaidCollection = false;
bool EnableLogging = true;
int LogLevel = 3;
bool ClipboardAttribution = true;
FString FacebookAppId = TEXT("123456789012345");
FString CustomSdid = TEXT("");

bool Success = USingularSDKBPLibrary::Initialize(
    ApiKey,
    ApiSecret,
    SessionTimeout,
    CustomUserId,
    SkAdNetworkEnabled,
    ManualSkanConversionManagement,
    WaitForTrackingAuthorizationTimeout,
    OaidCollection,
    EnableLogging,
    LogLevel,
    ClipboardAttribution,
    FacebookAppId,
    CustomSdid
);

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