支持推送通知
通过将 Firebase Cloud Messaging (FCM) 或 Apple Push Notification service (APNs) 与 Singular SDK 集成，跟踪用户与推送通知的互动，以衡量再参与活动并准确归因转化。
请遵循以下实施指南，以确保通知数据正确传递到 Singular SDK，从而实现正确的归因。
为什么要跟踪推送通知？推送通知能促进用户重新参与，但跟踪需要正确的集成。Singular 可确保与通知互动的用户得到正确归因，从而优化营销活动和参与策略。
实施指南
集成 Singular SDK
使用Singular虚幻引擎SDK指南中记录的标准安装说明在您的虚幻引擎项目中集成Singular SDK。
注册推送令牌
向Singular注册您的推送通知令牌，以启用卸载跟踪和推送归因。
// Register push token for uninstall tracking
void UYourGameInstance::OnPushTokenReceived(const FString& Token)
{
// Pass the FCM or APNs token to Singular
USingularSDKBPLibrary::SetUninstallToken(Token);
UE_LOG(LogTemp, Log, TEXT("Push token registered: %s"), *Token);
}方法签名：
static void SetUninstallToken(FString token);
最佳实践：从 FCM (Android) 或 APNs (iOS) 收到推送通知令牌后，请立即致电SetUninstallToken。这样可以确保正确跟踪卸载和推送通知互动。
特定平台处理
iOS 推送通知处理
配置推送通知路径
对于 iOS 实现，请在 SDK 初始化期间配置推送通知有效载荷结构中 Singular 跟踪链接所在的 JSON 路径。
// iOS: Configure push notification link paths in initialization
// Note: This is typically configured through the iOS native bridge
// The Singular iOS SDK automatically handles push tracking when configured
// Example configuration in iOS native code (Objective-C):
// SingularConfig *config = [[SingularConfig alloc] initWithApiKey:@"API_KEY" andSecret:@"API_SECRET"];
// config.singularLinksHandler = ^(SingularLinkParams * _Nonnull params) {
// // Handle deep link from push notification
// };
// [Singular start:config];终止状态（应用程序未运行）
处于终止状态的 iOS 应用程序无需手动操作。当用户在应用程序未运行时点击通知时，Singular iOS 集成会自动处理推送跟踪。
自动处理：当用户在应用程序未运行时点击推送通知时，Singular 会在应用程序启动期间通过本地 iOS 集成层自动捕获通知有效载荷。
后台状态（应用程序在后台运行）
当应用程序处于后台时收到通知，iOS SDK 会自动处理通知数据。除了初始令牌注册外，不需要额外的 C++ 代码。
重要：确保您的 iOS 项目正确配置了推送通知功能，并在应用程序初始化期间使用SetUninstallToken 注册了 APNs 令牌。
安卓推送通知处理
Firebase 云消息集成
对于安卓实施，请集成 Firebase Cloud Messaging (FCM)，并将推送令牌转发至 Singular SDK 以进行跟踪。
// Android: Register FCM token with Singular
void UYourGameInstance::OnFirebaseTokenReceived(const FString& FcmToken)
{
// Register the FCM token for uninstall tracking
USingularSDKBPLibrary::SetUninstallToken(FcmToken);
UE_LOG(LogTemp, Log, TEXT("FCM token registered with Singular: %s"), *FcmToken);
}处理推送通知数据
当用户点击包含 Singular 跟踪链接的推送通知时，确保将通知数据传递给应用程序的深度链接处理程序，以便正确归属。
// Handle notification tap event
void UYourGameInstance::OnNotificationTapped(const FString& NotificationData)
{
// Parse notification data for Singular links
// Example: Extract "sng_link" or custom key from notification payload
// If notification contains a Singular tracking link, it will be
// automatically processed by the SDK's deep link handler
UE_LOG(LogTemp, Log, TEXT("Notification tapped: %s"), *NotificationData);
// Route user to appropriate content
ProcessNotificationDeepLink(NotificationData);
}
void UYourGameInstance::ProcessNotificationDeepLink(const FString& LinkData)
{
// Your custom deep link routing logic
if (LinkData.Contains(TEXT("article")))
{
// Navigate to article
OpenArticleScreen();
}
else if (LinkData.Contains(TEXT("promotion")))
{
// Navigate to promotion
OpenPromotionScreen();
}
}最佳实践：构建推送通知有效载荷，同时包含 Singular 跟踪链接（用于归因）和应用程序的自定义深度链接数据（用于将用户导向特定内容）。
验证指南
验证推送令牌注册
在应用程序初始化过程中检查 SDK 日志，确认推送通知令牌已在 Singular 正确注册。
// Enable SDK logging to verify token registration
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 for debugging
5, // Verbose log level
false, // Clipboard attribution
TEXT(""), // Facebook App ID
TEXT("") // Custom SDID
);
// After receiving push token
FString PushToken = GetPushNotificationToken();
USingularSDKBPLibrary::SetUninstallToken(PushToken);
// Check logs for confirmation:
// "Push token registered successfully" or similar message调试提示：在开发过程中启用详细日志（日志级别 5），以查看有关推送令牌注册和通知处理的详细信息。为提高性能，在生产构建中禁用详细日志记录。
在仪表板中验证归属
使用 Singular 面板验证推送通知互动是否被正确跟踪。
- 重新参与营销活动：检查仪表板中的 "再参与 "部分，查看推送通知营销活动的性能。
- 用户级数据：导出用户级数据，以验证推送通知接触点是否以正确的归因方式记录。
- 转换事件：确认推送通知点击后触发的事件归因于正确的营销活动。
高级配置
自定义通知有效载荷结构
调整推送通知有效载荷结构，使其包含 Singular 跟踪参数和自定义数据。
推荐的有效载荷结构（JSON）：
{
"notification": {
"title": "Special Offer!",
"body": "Get 50% off today only"
},
"data": {
"sng_link": "https://yourapp.sng.link/Abc12?_dl=myapp://promo",
"campaign_id": "summer_sale_2025",
"promo_code": "SAVE50",
"deep_link": "myapp://promo/summer"
}
}关键要素：
- sng_link：用于归因的 Singular 跟踪链接（推送跟踪需要）。
- campaign_id：您的内部营销活动标识符，供参考。
- deep_link：您应用程序的自定义深度链接，用于内容路由。
- 自定义数据：您的应用程序所需的任何附加数据（促销代码、用户细分等）。
注意：Singular SDK 会自动从 "sng_link "密钥中提取并处理跟踪链接。请确保在所有推送通知活动中一致使用此密钥。
深度链接路由实施
实施集中式深度链接处理程序，以便在用户点击推送通知时将其路由到特定内容。
// Centralized deep link handler
class UDeepLinkHandler : public UObject
{
public:
void HandleDeepLink(const FString& DeepLink)
{
// Parse the deep link URL
if (DeepLink.StartsWith(TEXT("myapp://article/")))
{
FString ArticleId = ExtractArticleId(DeepLink);
NavigateToArticle(ArticleId);
}
else if (DeepLink.StartsWith(TEXT("myapp://promo/")))
{
FString PromoId = ExtractPromoId(DeepLink);
NavigateToPromotion(PromoId);
}
else if (DeepLink.StartsWith(TEXT("myapp://profile")))
{
NavigateToUserProfile();
}
else
{
// Default: Navigate to home screen
NavigateToHome();
}
}
private:
FString ExtractArticleId(const FString& Url)
{
// Extract article ID from URL
FString ArticleId;
Url.Split(TEXT("article/"), nullptr, &ArticleId);
return ArticleId;
}
FString ExtractPromoId(const FString& Url)
{
// Extract promo ID from URL
FString PromoId;
Url.Split(TEXT("promo/"), nullptr, &PromoId);
return PromoId;
}
void NavigateToArticle(const FString& ArticleId)
{
UE_LOG(LogTemp, Log, TEXT("Navigating to article: %s"), *ArticleId);
// Your navigation logic
}
void NavigateToPromotion(const FString& PromoId)
{
UE_LOG(LogTemp, Log, TEXT("Navigating to promotion: %s"), *PromoId);
// Your navigation logic
}
void NavigateToUserProfile()
{
UE_LOG(LogTemp, Log, TEXT("Navigating to user profile"));
// Your navigation logic
}
void NavigateToHome()
{
UE_LOG(LogTemp, Log, TEXT("Navigating to home screen"));
// Your navigation logic
}
};重要注意事项
实施注意事项
- 令牌注册时间：一旦从 FCM 或 APN 获取推送令牌，最好在 SDK 初始化期间或之后立即向 Singular 注册。
- 归因流程：当用户点击包含 Singular 链接的通知时，SDK 会在会话开始事件中自动处理归因数据。无需手动处理归因跟踪。
- 深度链接处理：虽然 Singular 会自动处理归因，但您必须实施自定义的深度链接路由逻辑，以便将用户导航到正确的应用内内容。
- 有效载荷一致性：在所有推送通知活动中使用一致的关键名称（如 "sng_link"），以确保可靠的跟踪。
- 平台差异：iOS 和 Android 在系统层面处理推送通知的方式不同。确保您的实施考虑到特定平台的行为。
- 卸载跟踪：推送令牌还可用于卸载跟踪。Singular 会发送静默推送通知以检测卸载的应用程序，从而提供有价值的留存洞察。
生产检查表：在启动推送通知活动之前，请确认：（1）推送令牌已成功注册；（2）通知有效载荷中包含 Singular 跟踪链接；（3）深层链接路由工作正常；（4）归因数据出现在 Singular 面板中。
隐私和权限
在实施推送通知时，确保符合平台要求和用户隐私法规。
- iOS 许可：用户必须授予接收推送通知的权限。在应用程序流程的适当时间请求许可，而不是在首次启动时立即请求许可。
- Android 许可：从 Android 13（API 级 33）开始，应用程序必须请求 POST_NOTIFICATIONS 权限才能发送通知。
- 用户同意：尊重用户接收营销信息的偏好。在应用程序设置中提供明确的退出机制。
- 数据隐私：避免在推送通知有效载荷中包含个人身份信息 (PII)。使用用户 ID 或其他非 PII 标识符。
成功：通过遵循这些实施步骤，您的虚幻引擎应用程序现在可以使用 Singular 跟踪推送通知的交互，从而提高活动性能洞察力并确保准确的重新参与归因。