文档

虚幻引擎 SDK - 方法参考

Singular Unreal Engine SDK 为虚幻引擎应用程序提供了全面的跟踪和属性功能。本参考文档记录了所有可用的SDK方法及其签名和使用示例。

创建推荐人短链接

生成一个可共享的短 Singular 链接，用于跟踪用户到用户归因和病毒式增长活动。

签名

static void CreateReferrerShortLink(
    FString baseLink,
    FString referrerName,
    FString referrerId,
    TMap<FString, FString> args
);

使用示例

// Create a referrer short link
FString BaseLink = TEXT("https://example.sng.link/abc123");
FString ReferrerName = TEXT("John Doe");
FString ReferrerId = TEXT("user_12345");

TMap<FString, FString> PassthroughParams;
PassthroughParams.Add(TEXT("campaign"), TEXT("summer_promo"));
PassthroughParams.Add(TEXT("level"), TEXT("5"));

USingularSDKBPLibrary::CreateReferrerShortLink(
    BaseLink,
    ReferrerName,
    ReferrerId,
    PassthroughParams
);

获取限制数据共享

获取限制数据共享状态

检查当前的数据共享限制状态，以确保隐私合规。

签名

static bool GetLimitDataSharing();

使用示例

// Check if data sharing is limited
bool IsLimited = USingularSDKBPLibrary::GetLimitDataSharing();

if (IsLimited)
{
    UE_LOG(LogTemp, Log, TEXT("Data sharing is currently limited"));
}
else
{
    UE_LOG(LogTemp, Log, TEXT("Data sharing is enabled"));
}

初始化

初始化 Singular SDK

使用配置参数（包括 API 凭据、跟踪设置和隐私选项）初始化 Singular SDK。

签名

static bool Initialize(
    FString apiKey,
    FString apiSecret,
    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("")
);

使用示例

// Initialize SDK with required parameters
FString ApiKey = TEXT("SDK KEY");
FString ApiSecret = TEXT("YOUR_API_SECRET");

bool Success = USingularSDKBPLibrary::Initialize(
    ApiKey,
    ApiSecret,
    60,                    // Session timeout in seconds
    TEXT(""),             // Custom user ID (optional)
    true,                 // SKAdNetwork enabled
    false,                // Manual SKAN conversion management
    0,                    // Wait for tracking authorization timeout
    false,                // OAID collection
    true,                 // Enable logging for debugging
    3,                    // Log level (0-5)
    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"));
}

IsAllTrackingStopped

检查是否已停止所有跟踪

确定是否因隐私合规或用户偏好而停止了所有跟踪。

签名

static bool IsAllTrackingStopped();

使用示例

// Check tracking status
bool IsTrackingStopped = USingularSDKBPLibrary::IsAllTrackingStopped();

if (IsTrackingStopped)
{
    UE_LOG(LogTemp, Warning, TEXT("Tracking is currently stopped"));
    // Update UI to reflect tracking status
}
else
{
    UE_LOG(LogTemp, Log, TEXT("Tracking is active"));
}

限制数据共享

设置数据共享限制

控制是否与第三方共享用户数据，以遵守 GDPR 和 CCPA 等隐私法规。

签名

static void LimitDataSharing(bool shouldLimitDataSharing);

使用示例

// Limit data sharing when user opts out
USingularSDKBPLibrary::LimitDataSharing(true);
UE_LOG(LogTemp, Log, TEXT("Data sharing has been limited"));

// Enable data sharing when user opts in
USingularSDKBPLibrary::LimitDataSharing(false);
UE_LOG(LogTemp, Log, TEXT("Data sharing has been enabled"));

恢复所有跟踪

在停止跟踪后重新启用跟踪，允许 SDK 恢复数据收集和事件报告。

签名

static void ResumeAllTracking();

使用示例

// Resume tracking when user grants consent
USingularSDKBPLibrary::ResumeAllTracking();
UE_LOG(LogTemp, Log, TEXT("Tracking has been resumed"));

发送事件

发送自定义事件

按名称跟踪自定义事件，以衡量应用程序中的用户操作和参与情况。

签名

static void SendEvent(FString eventName);

使用示例

// Track level completion event
USingularSDKBPLibrary::SendEvent(TEXT("level_completed"));

// Track tutorial start
USingularSDKBPLibrary::SendEvent(TEXT("tutorial_start"));

// Track user achievement
USingularSDKBPLibrary::SendEvent(TEXT("achievement_unlocked"));

SendEventWithArgs

发送带属性的自定义事件

跟踪带有附加属性的自定义事件，提供有关用户操作的详细上下文。

签名

static void SendEventWithArgs(
    FString eventName,
    TMap<FString, FString> args
);

使用示例

// Track level completion with attributes
TMap<FString, FString> LevelAttributes;
LevelAttributes.Add(TEXT("level_name"), TEXT("Dark Forest"));
LevelAttributes.Add(TEXT("level_number"), TEXT("5"));
LevelAttributes.Add(TEXT("time_spent"), TEXT("245"));
LevelAttributes.Add(TEXT("score"), TEXT("8500"));

USingularSDKBPLibrary::SendEventWithArgs(
    TEXT("level_completed"),
    LevelAttributes
);

// Track item purchase with details
TMap<FString, FString> PurchaseAttributes;
PurchaseAttributes.Add(TEXT("item_id"), TEXT("sword_legendary"));
PurchaseAttributes.Add(TEXT("item_category"), TEXT("weapon"));
PurchaseAttributes.Add(TEXT("item_rarity"), TEXT("legendary"));

USingularSDKBPLibrary::SendEventWithArgs(
    TEXT("item_purchased"),
    PurchaseAttributes
);

发送收入事件

跟踪带有货币和金额的创收事件，以衡量货币化绩效。

签名

static void SendRevenue(
    FString eventName,
    FString currency,
    float amount
);

使用示例

// Track in-app purchase revenue
USingularSDKBPLibrary::SendRevenue(
    TEXT("coin_pack_purchase"),
    TEXT("USD"),
    4.99f
);

// Track subscription purchase
USingularSDKBPLibrary::SendRevenue(
    TEXT("premium_subscription"),
    TEXT("EUR"),
    9.99f
);

SendRevenueWithArgs

发送带属性的收入事件

使用附加属性跟踪收入，提供有关交易的详细信息。

签名

static void SendRevenueWithArgs(
    FString eventName,
    FString currency,
    float amount,
    TMap<FString, FString> args
);

使用示例

// Track revenue with transaction details
TMap<FString, FString> TransactionAttributes;
TransactionAttributes.Add(TEXT("product_id"), TEXT("com.game.coins.large"));
TransactionAttributes.Add(TEXT("product_name"), TEXT("Large Coin Pack"));
TransactionAttributes.Add(TEXT("quantity"), TEXT("1"));
TransactionAttributes.Add(TEXT("payment_method"), TEXT("credit_card"));

USingularSDKBPLibrary::SendRevenueWithArgs(
    TEXT("iap_purchase"),
    TEXT("USD"),
    9.99f,
    TransactionAttributes
);

设置自定义用户 ID

分配自定义用户标识符，以便使用自己的 ID 系统跨设备和会话跟踪用户。

签名

static void SetCustomUserId(FString customUserId);

使用示例

// Set custom user ID after login
FString UserId = TEXT("user_abc123xyz");
USingularSDKBPLibrary::SetCustomUserId(UserId);
UE_LOG(LogTemp, Log, TEXT("Custom user ID set: %s"), *UserId);

设置卸载令牌

设置卸载跟踪令牌

注册推送通知令牌，以启用卸载跟踪功能，衡量用户保留率。

签名

static void SetUninstallToken(FString token);

使用示例

// Set push notification token for uninstall tracking
FString PushToken = TEXT("abc123def456...");
USingularSDKBPLibrary::SetUninstallToken(PushToken);
UE_LOG(LogTemp, Log, TEXT("Uninstall token registered"));

获取转换值

获取 SKAdNetwork 转换值

读取 iOS 应用程序的当前 SKAdNetwork 转换值（仅限 iOS）。

签名

static int SkanGetConversionValue();

使用示例

// Get current SKAdNetwork conversion value (iOS only)
int ConversionValue = USingularSDKBPLibrary::SkanGetConversionValue();
UE_LOG(LogTemp, Log, TEXT("Current conversion value: %d"), ConversionValue);

SkanRegisterAppForAdNetworkAttribution

为广告网络归因注册应用程序

在 Apple 的 SKAdNetwork 框架下注册应用程序，以便进行归因跟踪（仅限 iOS）。

签名

static void SkanRegisterAppForAdNetworkAttribution();

使用示例

// Register for SKAdNetwork attribution (iOS only)
USingularSDKBPLibrary::SkanRegisterAppForAdNetworkAttribution();
UE_LOG(LogTemp, Log, TEXT("Registered for SKAdNetwork attribution"));

SkanUpdateConversionValue

更新 SKAdNetwork 转换值

更新 SKAdNetwork 转换值，以反映用户参与和货币化情况（仅限 iOS）。

签名

static bool SkanUpdateConversionValue(int conversionValue);

使用示例

// Update conversion value based on user actions (iOS only)
int NewValue = 10;
bool Success = USingularSDKBPLibrary::SkanUpdateConversionValue(NewValue);

if (Success)
{
    UE_LOG(LogTemp, Log, TEXT("Conversion value updated to: %d"), NewValue);
}
else
{
    UE_LOG(LogTemp, Warning, TEXT("Failed to update conversion value"));
}

SkanUpdateConversionValues

用粗细值更新 SKAdNetwork 转换值

使用细粒度转换值、粗粒度值和锁定状态更新 SKAdNetwork，适用于 iOS 16.1+（仅限 iOS）。

签名

static void SkanUpdateConversionValues(
    int conversionValue,
    int coarse,
    bool lock
);

使用示例

// Update conversion values with fine and coarse values (iOS 16.1+)
int FineValue = 25;
int CoarseValue = 1;  // 0 = low, 1 = medium, 2 = high
bool Lock = false;    // Set to true to prevent further updates

USingularSDKBPLibrary::SkanUpdateConversionValues(FineValue, CoarseValue, Lock);
UE_LOG(LogTemp, Log, TEXT("Updated conversion values: fine=%d, coarse=%d"), FineValue, CoarseValue);

停止所有跟踪

完全停止所有 SDK 跟踪活动，以符合用户隐私偏好或监管要求。

签名

static void StopAllTracking();

使用示例

// Stop tracking when user withdraws consent
USingularSDKBPLibrary::StopAllTracking();
UE_LOG(LogTemp, Warning, TEXT("All tracking has been stopped"));

跟踪选择加入

记录跟踪选择

通知 Singular 用户已明确选择跟踪，以符合 GDPR 要求。

签名

static void TrackingOptIn();

使用示例

// Record user opt-in for GDPR compliance
USingularSDKBPLibrary::TrackingOptIn();
UE_LOG(LogTemp, Log, TEXT("User has opted in to tracking"));

跟踪 13 岁以下用户

将用户标记为 13 岁以下

通知Singular用户未满13岁，以符合COPPA规定和保护儿童隐私。

签名

static void TrackingUnder13();

使用示例

// Mark user as under 13 for COPPA compliance
USingularSDKBPLibrary::TrackingUnder13();
UE_LOG(LogTemp, Log, TEXT("User marked as under 13 years old"));

取消设置自定义用户 ID

删除自定义用户 ID

清除先前设置的自定义用户 ID，通常在注销或切换账户时使用。

签名

static void UnsetCustomUserId();

使用示例

// Clear custom user ID on logout
USingularSDKBPLibrary::UnsetCustomUserId();
UE_LOG(LogTemp, Log, TEXT("Custom user ID has been cleared"));