文件

支持 SKAdNetwork

SKAdNetwork是Apple为iOS应用程序安装活动提供的注重隐私的归因框架。从虚幻引擎SDK 2.0.11版本开始，SKAdNetwork默认在托管模式下启用，Singular会根据您在仪表板中配置的转换模型自动更新转换值。

无需额外配置：如果您使用的是虚幻引擎SDK 2.0.11或更高版本，SKAdNetwork开箱即用。基本功能无需更改代码或进行额外设置。

了解 SKAN 模式

托管模式（默认）

在托管模式下，Singular 会根据您在仪表板中配置的转换模型自动处理转换值更新。这是大多数应用程序的推荐方法，因为它只需最少的代码，并提供最佳的转换跟踪。

自动更新：Singular 根据用户事件和配置的模型管理所有转换值更新。
仪表板配置：在 Singular 面板中设计转换模型，无需修改代码。
优化：受益于 Singular 在苹果限制条件下最大化转换值更新的专业知识。

手动模式（高级）

手动模式可让您完全控制转换值更新，允许您实施自定义逻辑来确定何时以及如何更新 SKAN 转换值。只有当您有管理模式无法满足的特殊要求时，才使用该模式。

高级功能：手动模式需要仔细实施并了解 Apple 的 SKAdNetwork 限制，包括转换值更新窗口和限制。大多数应用程序应使用 "托管模式"。

配置选项

在USingularSDKBPLibrary::Initialize 方法中配置 SKAdNetwork 行为。下表列出了可用选项及其默认值。

选项	默认值	说明
skAdNetworkEnabled	True	启用 SKAdNetwork 对 iOS 归因跟踪的支持。
manualSKANConversionManagement	False	启用手动模式以自行控制转换值更新。

注意：从虚幻引擎 SDK 版本 2.0.11 开始，默认情况下启用 SKAdNetwork。如果您使用的是旧版本，则需要通过将ode translatete="no "skAdNetworkEnabled设置为ode translate="="no "True或调用SkanRegisterAppForAdNetworkAttribution() 来启用SKAdNetwork。

旧版 SDK 版本

如果您使用的虚幻引擎 SDK 版本早于 2.0.11，请使用下面的方法手动启用 SKAdNetwork 支持。

在旧版本的SDK中启用SKAdNetwork

通过配置启用

在初始化 SDK 时将skAdNetworkEnabled 设置为True。

// Initialize with SKAdNetwork enabled
bool Success = USingularSDKBPLibrary::Initialize(
    TEXT("YOUR_SDK_KEY"),
    TEXT("YOUR_SDK_SECRET"),
    60,                      // Session timeout
    TEXT(""),                // Custom user ID
    true,                    // Enable SKAdNetwork
    false,                   // Manual SKAN management
    0,                       // Wait for tracking authorization
    false,                   // OAID collection
    true,                    // Enable logging
    3,                       // Log level
    false,                   // Clipboard attribution
    TEXT(""),                // Facebook App ID
    TEXT("")                 // Custom SDID
);

if (Success)
{
    UE_LOG(LogTemp, Log, TEXT("SDK initialized with SKAdNetwork enabled"));
}

通过方法调用启用

或者，在应用程序初始化代码中直接调用注册方法。

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

建议：升级到最新的虚幻引擎SDK版本，以便从自动启用SKAdNetwork以及最新功能和错误修复中获益。

配置手动模式

要实现自定义转换值逻辑，请启用手动模式并使用提供的SDK方法在应用程序的整个生命周期内更新和监控转换值。

在手动模式下使用 SKAdNetwork（高级）

启用手动模式

在初始化 SDK 时将manualSKANConversionManagement 设置为True，以便控制转换值更新。

// Initialize with Manual Mode enabled
bool Success = USingularSDKBPLibrary::Initialize(
    TEXT("YOUR_SDK_KEY"),
    TEXT("YOUR_SDK_SECRET"),
    60,                      // Session timeout
    TEXT(""),                // Custom user ID
    true,                    // Enable SKAdNetwork
    true,                    // Enable Manual SKAN management
    0,                       // Wait for tracking authorization
    false,                   // OAID collection
    true,                    // Enable logging
    3,                       // Log level
    false,                   // Clipboard attribution
    TEXT(""),                // Facebook App ID
    TEXT("")                 // Custom SDID
);

if (Success)
{
    UE_LOG(LogTemp, Log, TEXT("SDK initialized with Manual SKAN Mode"));
}

更新转换值

使用此方法可根据自定义逻辑手动更新 SKAdNetwork 转换值。转换值必须是 0 到 63 之间的整数。

重要信息：此方法仅在manualSKANConversionManagement 设置为 True 时有效。如果托管模式处于活动状态，手动更新将被忽略。

方法签名

static bool SkanUpdateConversionValue(int conversionValue)

使用示例

// Track a sign-up event
USingularSDKBPLibrary::SendEvent(TEXT("SignUp"));

// Update the conversion value to 7
bool Success = USingularSDKBPLibrary::SkanUpdateConversionValue(7);

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

// Example: Update based on purchase tier
void OnPurchaseComplete(float PurchaseAmount)
{
    // Track revenue event
    USingularSDKBPLibrary::SendRevenue(TEXT("purchase"), TEXT("USD"), PurchaseAmount);

    // Calculate conversion value based on amount
    int ConversionValue = 10; // Default
    if (PurchaseAmount >= 100.0f)
    {
        ConversionValue = 63; // High value
    }
    else if (PurchaseAmount >= 50.0f)
    {
        ConversionValue = 40; // Medium value
    }
    else if (PurchaseAmount >= 10.0f)
    {
        ConversionValue = 20; // Low value
    }

    USingularSDKBPLibrary::SkanUpdateConversionValue(ConversionValue);
}

获取当前转换值

读取 Singular SDK 追踪的当前转换值。这对于根据当前状态执行条件逻辑非常有用。

方法签名

static int SkanGetConversionValue()

使用示例

// Get the current conversion value
int CurrentValue = USingularSDKBPLibrary::SkanGetConversionValue();
UE_LOG(LogTemp, Log, TEXT("Current conversion value: %d"), CurrentValue);

// Only update if current value is below threshold
if (CurrentValue < 30)
{
    USingularSDKBPLibrary::SkanUpdateConversionValue(30);
    UE_LOG(LogTemp, Log, TEXT("Conversion value updated from %d to 30"), CurrentValue);
}

监控转换值更新

设置一个委托，以便在转换值发生变化时接收实时通知。这样，您就可以对转换值更新做出反应，并记录分析结果或触发其他应用程序行为。

实施步骤

在类头文件顶部添加 ode translate="no "o "#include "SingularDelegates.h"。

在类头文件中添加以下委托声明：

// Delegate to register for conversion value updates
UPROPERTY(BlueprintAssignable, Category = "Singular-SDK")
FOnConversionValueUpdated OnConversionValueUpdated;

// Method that will handle the conversion value update
UFUNCTION()
void OnNewConversionValue(int32 ConversionValue);

在类的实现文件中，注册委托：

// Register the delegate (typically in BeginPlay or constructor)
OnConversionValueUpdated.AddDynamic(this, &UYourClassName::OnNewConversionValue);

实现回调方法：

ode class="="cpp"void UYourClassName::OnNewConversionValue(int32 ConversionValue)
{
    // This method is called whenever the conversion value is updated
    UE_LOG(LogTemp, Log, TEXT("Conversion value updated to: %d"), ConversionValue);

    // Log the update to your analytics
    LogConversionValueUpdate(ConversionValue);

    // Trigger any app-specific behavior
    if (ConversionValue >= 50)
    {
        UnlockPremiumFeature();
    }
}

最佳实践：使用转换值委托来保持整个应用程序当前转换状态的同步视图。这对于调试和确保您的自定义逻辑正确运行特别有用。

其他资源

有关 SKAdNetwork 实施和最佳实践的更全面信息，请参阅《iOS SDK SKAdNetwork 实施指南》。

支持应用程序跟踪透明度 (ATT)

应用程序跟踪透明度 (ATT) 是苹果公司的隐私框架，要求在访问设备的 IDFA（广告商标识符）和共享用户数据之前征得用户同意。正确实施 ATT 对于 iOS 归因和最大限度地提高用户获取活动的准确性至关重要。

ATT 为何对归因至关重要

从 iOS 14.5 开始，应用程序在访问 IDFA 之前必须通过 ATT 框架请求用户许可。虽然在没有 IDFA 的情况下仍可使用指纹识别和概率方法进行归因，但有了 IDFA，归因的准确性会大大提高，并提供确定性匹配。

确定性归属：IDFA 可实现精确的设备级归因，将广告印象与安装直接联系起来。
广告网络优化：通过访问 IDFA，广告网络可以更好地优化广告活动并提供更准确的报告。
用户级洞察：访问 IDFA 可以进行更精细的用户行为分析和群组跟踪。

建议：Singular 强烈建议实施 ATT 提示并征求用户同意。解释给用户带来的好处（个性化广告、更好的应用体验），以最大限度地提高选择加入率。

SDK 初始化时机

相对于 ATT 提示，SDK 初始化的时机至关重要。如果 SDK 在用户响应 ATT 提示之前初始化并发送第一个会话，则无法捕获 IDFA，导致归因不够准确。

为什么要延迟初始化？

默认情况下，Singular SDK 会在初始化后立即发送会话。当会话来自新设备时，Singular 会仅使用当时可用的数据触发归因过程。如果用户尚未回复 ATT 提示，IDFA 将不可用，归因将基于不太准确的方法。

关键：请务必在Singular SDK 发送第一个会话之前请求 ATT 同意并检索 IDFA。否则将永久丢失该设备归因数据的 IDFA。

配置 SDK 等待超时

通过设置waitForTrackingAuthorizationWithTimeoutInterval 参数，配置 SDK 在初始化前等待用户的 ATT 响应。该延迟可为用户提供响应 ATT 提示的时间，同时防止在未显示提示时出现无限期延迟。

ATT 延迟如何工作

SDK 会初始化并开始记录会话和用户事件，但不会将其发送到Singular 服务器。
一旦App Tracking Transparency同意、拒绝或超时，SDK就会将会话和队列事件发送到Singular（带或不带IDFA）。
如果有 IDFA，Singular 会利用 IDFA 启动归属过程。

实施

配置示例

在初始化 SDK 时设置waitForTrackingAuthorizationWithTimeoutInterval参数。该值表示等待用户 ATT 响应的最长秒数。

// Initialize with ATT delay
bool Success = USingularSDKBPLibrary::Initialize(
    TEXT("YOUR_SDK_KEY"),
    TEXT("YOUR_SDK_SECRET"),
    60,                      // Session timeout
    TEXT(""),                // Custom user ID
    true,                    // Enable SKAdNetwork
    false,                   // Manual SKAN management
    300,                     // Wait up to 300 seconds (5 minutes) for ATT response
    false,                   // OAID collection
    true,                    // Enable logging
    3,                       // Log level
    false,                   // Clipboard attribution
    TEXT(""),                // Facebook App ID
    TEXT("")                 // Custom SDID
);

if (Success)
{
    UE_LOG(LogTemp, Log, TEXT("SDK initialized with ATT delay"));
}

考虑超时：设置适当的超时值（通常为 60-300 秒）。如果超时后用户仍未作出回应，SDK 将继续发送数据，而不发送 IDFA。

ATT 最佳实践

预先提示信息：向用户显示 ATT 前屏幕，解释为什么需要跟踪许可，以及跟踪许可对用户有什么好处（更好的广告、更好的体验）。这可以大大提高选择加入率。
时机很重要：在应用程序流程中的自然时刻显示 ATT 提示，而不是在首次启动时立即显示。让用户先体验您的应用。
自定义消息：使用NSUserTrackingUsageDescription 键在 Info.plist 文件中自定义 ATT 提示信息，以清楚地解释您的跟踪目的。
全面测试：测试授权和拒绝两种情况，确保无论用户如何选择，您的应用都能正常运行。
尊重用户的选择：切勿反复提示已拒绝跟踪的用户，也不要显示激进的信息，迫使他们选择加入。

应用商店审查：未正确实施 ATT 或试图规避框架的应用程序可能会在 App Store 审核期间被拒绝。确保您的实施遵循 Apple 的指导原则并尊重用户的隐私选择。

其他资源

有关 iOS 14+ 更改和最佳实践的更多信息，请参阅以下资源：

虚幻引擎 SDK - 支持 SKAdNetwork 和 ATT

支持 SKAdNetwork

了解 SKAN 模式

托管模式（默认）

手动模式（高级）

配置选项

旧版 SDK 版本

通过配置启用

通过方法调用启用

配置手动模式

启用手动模式

更新转换值

方法签名

使用示例

获取当前转换值

方法签名

使用示例

监控转换值更新

实施步骤

其他资源

支持应用程序跟踪透明度 (ATT)

ATT 为何对归因至关重要

SDK 初始化时机

为什么要延迟初始化？

配置 SDK 等待超时

ATT 延迟如何工作

实施

配置示例

ATT 最佳实践

其他资源