虚幻引擎 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
);

clipboardAttribution

剪贴板属性

启用从剪贴板读取数据以支持 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
    3,                         // logLevel
    ClipboardAttribution,      // Enable clipboard attribution
    TEXT(""),                  // facebookAppId
    TEXT("")                   // customSdid
);

customSdid

自定义单个设备 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
    3,                         // logLevel
    false,                     // clipboardAttribution
    TEXT(""),                  // facebookAppId
    CustomSdid                 // Custom SDID
);

customUserId

自定义用户 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
    3,                         // logLevel
    false,                     // clipboardAttribution
    TEXT(""),                  // facebookAppId
    TEXT("")                   // customSdid
);

enableLogging

启用日志记录

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

仅限 Android。该值仅在 Android 上传递给 SDK，在 iOS 上无效。

签名

C++ 
bool enableLogging
// Default: false

使用示例

C++ 
// Enable logging for development builds
bool EnableLogging = true;
int LogLevel = 2;  // 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 归因整合。

仅限 Android。该值仅在 Android 上传递给 SDK，在 iOS 上无效。

签名

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
    3,                         // logLevel
    false,                     // clipboardAttribution
    FacebookAppId,             // Facebook App ID
    TEXT("")                   // customSdid
);

logLevel

日志级别

设置 SDK 日志输出的详细程度。取值为 Android android.util.Log 常量，数值越小越详细：2 Verbose、3 Debug、4 Info、5 Warn、6 Error、7 Assert。默认值为 3（Debug）。

仅限 Android。该值仅在 Android 上传递给 SDK，在 iOS 上无效。

签名

C++ 
int logLevel
// Default: 3 (Debug)
// android.util.Log levels: 2 Verbose, 3 Debug, 4 Info,
// 5 Warn, 6 Error, 7 Assert - lower is more verbose

使用示例

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

USingularSDKBPLibrary::Initialize(
    ApiKey,
    ApiSecret,
    60,                        // sessionTimeout
    TEXT(""),                  // customUserId
    true,                      // skAdNetworkEnabled
    false,                     // manualSkanConversionManagement
    0,                         // waitForTrackingAuthorizationWithTimeoutInterval
    false,                     // oaidCollection
    true,                      // enableLogging
    LogLevel,                  // 2 = 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
    3,                         // 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
    3,                         // logLevel
    false,                     // clipboardAttribution
    TEXT(""),                  // facebookAppId
    TEXT("")                   // customSdid
);

sessionTimeout

会话超时

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

签名

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
    3,                         // logLevel
    false,                     // clipboardAttribution
    TEXT(""),                  // facebookAppId
    TEXT("")                   // customSdid
);

singularEspDomains

ESP 域名

注册您的电子邮件服务提供商（ESP）用于包装 Singular 链接的域名。当邮件中的链接被 ESP 重写后，SDK 会针对这些域名跟随被包装的重定向，因此原始的 Singular 链接参数仍可被还原。

这不是 Initialize 的参数。与本页其他所有选项不同，singularEspDomains 是 USingularSDKBPLibrary 的公共静态成员。请在调用 Initialize 之前为其赋值；该值会在构建配置时被读取。iOS 和 Android 均可使用。

签名

C++
static TArray<FString> singularEspDomains
// Default: empty

使用示例

C++
// Register your ESP domains BEFORE initializing the SDK
USingularSDKBPLibrary::singularEspDomains = {
    TEXT("links.example-esp.com"),
    TEXT("click.example-esp.net")
};

USingularSDKBPLibrary::Initialize(
    ApiKey,
    ApiSecret,
    60,                        // sessionTimeout
    TEXT(""),                  // customUserId
    true,                      // skAdNetworkEnabled
    false,                     // manualSkanConversionManagement
    0,                         // waitForTrackingAuthorizationWithTimeoutInterval
    false,                     // oaidCollection
    false,                     // enableLogging
    3,                         // 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
    3,                         // logLevel
    false,                     // clipboardAttribution
    TEXT(""),                  // facebookAppId
    TEXT("")                   // customSdid
);

waitForTrackingAuthorizationWithTimeoutInterval

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

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

仅限 iOS。IDFA 只能附加到首次会话，因此若该会话在用户响应 ATT 提示之前发送，该次安装将永久没有 IDFA。如果您的应用会显示该提示，Singular 建议设置为 300。

签名

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
    3,                         // 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"));
}