支持推送通知
通过将 Apple Push Notification Service（APNs）与 Singular SDK 集成，跟踪用户与推送通知的交互，从而衡量再互动活动并准确归因转化。
请遵循下面的实施指南，确保通知数据正确传递到 Singular SDK 以实现准确归因。
为什么要跟踪推送通知： 推送通知推动再互动，但跟踪需要正确的集成。Singular 确保与通知交互的用户被正确归因，优化营销活动和参与策略。
先决条件： 在生成 APNs token 并且 Singular 能够提取推送 payload 之前，请验证以下所有条件均已就绪：
- 在 Xcode 中应用目标的 Signing & Capabilities 下已启用 Push Notifications 能力。
- 已为您的应用将 APNs 密钥（.p8）或证书（.p12）上传到 Singular 仪表板。
- 应用使用包含 aps-environment entitlement 的配置文件进行构建。
- 测试在真机上进行——APNs token 不会在 iOS 模拟器上发放。
-
Singular.start(_:)在 SDK 通过pushNotificationLinkPath从通知 payload 中提取 Singular 链接之前已运行。
实施指南
注册推送通知
请求用户授权以接收推送通知，并使用 UNUserNotificationCenter 将应用注册到 APNs。
import UserNotifications
// Set the current instance as the delegate for UNUserNotificationCenter
UNUserNotificationCenter.current().delegate = self
// Define the notification authorization options (alert, badge, sound)
let pushAuthOptions: UNAuthorizationOptions = [.alert, .badge, .sound]
// Request notification authorization from the user
UNUserNotificationCenter.current().requestAuthorization(options: pushAuthOptions) { granted, error in
// If an error occurs during authorization, print the error description
if let error = error {
print("registerForPushNotifications : failure - \(error.localizedDescription)")
}
// If the user granted permission, register for remote notifications
if granted {
// Ensure registration is done on the main thread
DispatchQueue.main.async {
UIApplication.shared.registerForRemoteNotifications()
}
}
}- (void)registerForPushNotifications:(UIApplication *)application {
// Set delegate to self
[UNUserNotificationCenter currentNotificationCenter].delegate = self;
// Define the push notification options
UNAuthorizationOptions pushAuthOptions = UNAuthorizationOptionAlert |
UNAuthorizationOptionBadge |
UNAuthorizationOptionSound;
// Request push notification authorization
[[UNUserNotificationCenter currentNotificationCenter]
requestAuthorizationWithOptions:pushAuthOptions
completionHandler:^(BOOL granted, NSError * _Nullable error) {
if (error) {
NSLog(@"registerForPushNotifications : failure - %@", error.localizedDescription);
}
if (granted) {
dispatch_async(dispatch_get_main_queue(), ^{
[application registerForRemoteNotifications];
});
}
}];
}最佳实践： 请在应用生命周期的早期请求通知授权，最好是在向用户展示价值之后，以提高 opt-in 率。
处理通知响应
当用户点击推送通知时处理通知响应，并将 payload 数据转发给 Singular 以进行跟踪。
func userNotificationCenter(_ center: UNUserNotificationCenter,
didReceive response: UNNotificationResponse,
withCompletionHandler completionHandler: @escaping () -> Void) {
// Extract the notification payload
let userInfo = response.notification.request.content.userInfo
// Pass the notification data to Singular for tracking
Singular.handlePushNotification(userInfo)
// Call the completion handler to indicate processing is complete
completionHandler()
}- (void)userNotificationCenter:(UNUserNotificationCenter *)center
didReceiveNotificationResponse:(UNNotificationResponse *)response
withCompletionHandler:(void (^)(void))completionHandler {
// Extract the push notification payload (user info)
NSDictionary *userInfo = response.notification.request.content.userInfo;
// Log the userInfo dictionary for debugging purposes
NSLog(@"didReceiveNotificationResponse userInfo = %@", userInfo);
// Pass the notification data to Singular for tracking
[Singular handlePushNotification:userInfo];
// Call the completion handler to indicate processing is complete
completionHandler();
}最佳实践： 请始终及时调用 completion handler，以确保系统知道通知处理已完成。延迟完成可能会导致系统警告或限流。
为推送 payload 配置 SDK
在您的 SDK 配置中添加推送通知 payload 选择器，以指定 Singular 链接在通知数据结构中的位置。
func getConfig() -> SingularConfig? {
guard let config = SingularConfig(apiKey: "SDK_KEY", andSecret: "SDK_SECRET") else {
return nil
}
// Configure push notification link paths
config.pushNotificationLinkPath = [
["sng_link"],
["rootObj", "nestedObj", "anotherNested", "singularLink"]
]
return config
}
// Start the Singular SDK with the configuration
if let config = getConfig() {
Singular.start(config)
}- (SingularConfig *)getConfig {
SingularConfig *config = [[SingularConfig alloc] initWithApiKey:@"SDK_KEY"
andSecret:@"SDK_SECRET"];
// Configure push notification link paths
config.pushNotificationLinkPath = @[
@[@"sng_link"],
@[@"rootObj", @"nestedObj", @"anotherNested", @"singularLink"]
];
return config;
}
// Start the Singular SDK with the configuration
SingularConfig *config = [self getConfig];
[Singular start:config];选择器配置：
-
简单键：
对 payload 中的顶层键使用
["sng_link"] -
嵌套键：
使用
["rootObj", "nestedObj", "key"]遍历嵌套的 JSON 结构 - 多路径： 定义多个选择器数组，以检查 Singular 链接可能出现的不同位置
验证指南
在 Start Session 中验证 payload
通过检查 start session API 调用，确认推送通知链接已正确传递给 Singular。
当用户点击通知时，Singular SDK 会在 start session 请求的
singular_link
参数中包含推送通知 payload。
Start Session 请求示例：
https://skan.singular.net:443/api/v1/start?
dnt=-1
&update_time=0
&singular_link=https://sl.sng.link/Cclbu/2a7n?_dl=com.singular.app&_smtype=3
&i=com.singular.SwiftScene
&sdk=Singular/12.7.1
&p=iOS
&v=18.2.1备选验证方式： 使用 Singular SDK Console 验证推送通知跟踪。检查 Deeplink URL 字段，以确认跟踪链接已被正确捕获。
高级配置
ESP 域名配置
如果您将 Singular 链接包装在 Email Service Provider（ESP）或其他第三方域名中，请配置外部域名。
func getConfig() -> SingularConfig? {
guard let config = SingularConfig(apiKey: "SDK_KEY", andSecret: "SDK_SECRET") else {
return nil
}
// Configure ESP domains for wrapped links
config.espDomains = ["sl.esp.link", "custom.domain.com"]
return config
}- (SingularConfig *)getConfig {
SingularConfig *config = [[SingularConfig alloc] initWithApiKey:@"SDK_KEY"
andSecret:@"SDK_SECRET"];
// Configure ESP domains for wrapped links
config.espDomains = @[@"sl.esp.link", @"custom.domain.com"];
return config;
}
安全说明：
默认情况下，仅允许在 Singular 的 Manage Links 页面中预定义的
sng.link
域名。如果使用包装链接，请显式配置 ESP 域名。
动态深度链接路由
通过配置带有动态再营销覆盖的单个 Singular 跟踪链接，从单个通知实现多个深度链接目标。
用例示例： 一条具有多个操作选项的突发新闻通知
-
阅读最新新闻：
newsapp://article?id=12345 -
热门话题：
newsapp://trending -
体育：
newsapp://sports
不要创建多个跟踪链接，而是使用一个 Singular 链接并根据用户选择动态覆盖再营销。有关实现细节，请参阅 在 Singular 跟踪链接中覆盖再营销 。
重要注意事项
实现说明
-
无回调处理程序：
与
singularLinksHandler不同，推送通知功能不提供 payload 回调。请实现您自己的深度链接逻辑，将用户路由到您应用中的特定内容 -
归因流程：
当用户点击通知时，Singular 会检索 payload 并将其包含在由
Singular.start()触发的 start session 事件中。后端处理这些数据以归因推送通知触点，并注册再互动跟踪 -
域名限制：
默认情况下，仅允许来自 Manage Links 页面的 Singular 链接域名（
sng.link）。对于包装链接，请使用espDomains显式配置 ESP 域名
成功： 通过遵循这些步骤，您的应用现在可以通过 Singular 跟踪推送通知交互，改善活动表现洞察并确保准确的再互动归因。