支持推送通知

通过将 Firebase Cloud Messaging (FCM) 与 Singular SDK 集成，跟踪用户与推送通知的互动，以衡量再参与活动并准确归因于转化。

请遵循以下实施指南，以确保通知数据正确传递到 Singular SDK，从而获得正确的归因。

实施指南

集成 Singular SDK

使用Singular Cordova SDK指南中的标准安装说明，在您的Cordova 项目中集成Singular SDK。

设置 Firebase 云消息

使用@havesource/cordova-plugin-push 等插件在 Cordova 项目中配置推送通知，并按照 Firebase 的设置指南进行特定平台的集成。

iOS 配置

在 Firebase 中注册 iOS 应用程序，并在 Xcode 中配置推送通知功能。

1. 注册 iOS 应用程序：在 Firebase 控制台项目中创建 iOS 应用程序
2. 添加配置文件：下载GoogleService-Info.plist 并将其包含在您的 iOS 平台文件夹中
3. 启用功能：在 Xcode 项目设置中，启用推送通知功能
4. 启用后台模式：启用后台模式并勾选远程通知

安卓配置

在 Firebase 中注册您的 Android 应用程序，并将配置文件添加到您的项目中。

1. 注册 Android 应用程序：在 Firebase 控制台项目中创建一个 Android 应用程序
2. 添加配置文件：下载google-services.json 并将其放入platforms/android/app/
3. 验证依赖关系：确保正确安装 Firebase 插件并授予消息传递权限

配置推送链接路径

在推送通知有效载荷结构中定义 Singular 跟踪链接所在的 JSON 路径，以启用正确的归因跟踪。

通过传递字符串数组配置推送链接路径，字符串数组指定了推送通知数据结构中 Singular 链接的关键路径。每个路径都是一个数组，代表键的嵌套结构。

// Create configuration
var config = new cordova.plugins.SingularCordovaSdk.SingularConfig(
  'YOUR_SDK_KEY',
  'YOUR_SDK_SECRET'
);

// Configure paths where Singular links appear in push payload
config.withPushNotificationsLinkPaths([
  ['sng_link'],                              // Top-level key
  ['path', 'to', 'url'],                     // Nested path
  ['rootObj', 'nestedObj', 'singularLink']   // Deep nested path
]);

// Initialize SDK
cordova.plugins.SingularCordovaSdk.init(config);

路径配置示例：

• 简单键：对有效载荷中的顶级键使用['sng_link']
• 嵌套键：使用['rootObj', 'nestedObj', 'key'] 遍历嵌套的 JSON 结构
• 多路径：定义多个路径数组，以检查奇异链接的不同可能位置

有关完整的方法文档，请参阅withPushNotificationsLinkPaths 参考资料。

特定平台处理

配置特定平台代码，以便在用户与推送通知交互时，根据应用程序状态将通知数据传递给 Singular SDK。

iOS 推送通知处理

处于终止状态的应用程序

配置 iOS AppDelegate，将启动选项传递给 Singular SDK，以便在应用程序从终止状态打开时自动跟踪推送。

在AppDelegate.m 中的本地 iOS 代码中，调用didFinishLaunchingWithOptions 中的以下方法：

// Import at the top of the file
#import <SingularCordovaSdk/SingularCordovaSdk.h>

- (BOOL)application:(UIApplication *)application 
    didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    
    // Pass launch options to Singular for push tracking
    [SingularCordovaSdk setLaunchOptions:launchOptions];
    
    // Your other initialization code
    return YES;
}

后台或前台应用程序

当应用程序在后台或前台状态下接收通知时，使用handlePushNotification() 方法将推送数据传递给 SDK。

在处理推送通知的 JavaScript 代码中调用以下方法：

// Handle push notification when app is in background or foreground
document.addEventListener('deviceready', initializePushHandling, false);

function initializePushHandling() {
  // Initialize push plugin
  var push = PushNotification.init({
    android: {},
    ios: {
      alert: true,
      badge: true,
      sound: true
    }
  });
  
  // Handle notification when app is in foreground or background
  push.on('notification', function(data) {
    console.log('Push notification received:', data);
    
    // Pass notification data to Singular
    cordova.plugins.SingularCordovaSdk.handlePushNotification(data.additionalData);
    
    // Your custom notification handling logic
    handleNotificationNavigation(data);
  });
}

function handleNotificationNavigation(data) {
  // Navigate to appropriate screen based on notification data
  if (data.additionalData && data.additionalData.route) {
    console.log('Navigating to:', data.additionalData.route);
    // Your navigation logic
  }
}

有关完整的方法文档，请参阅handlePushNotification 参考资料。

安卓推送通知处理

处于终止状态的应用程序

对于处于终止状态的 Android 应用程序，无需进行任何操作。当用户点击通知时，Cordova 桥接层会自动处理这种情况。

后台或前台应用程序

配置您的 Android MainActivity，以便在应用程序处于后台或前台状态时将通知意图传递给 Singular SDK。

在您的主 Cordova 活动（如MainActivity.java ）中，覆盖onNewIntent ：

// Add imports at the top
import android.content.Intent;
import singular_cordova_sdk.SingularCordovaSdk;

// Add to MainActivity class
@Override
protected void onNewIntent(Intent intent) {
    super.onNewIntent(intent);
    
    // Pass intent to Singular for push tracking
    SingularCordovaSdk.handleNewIntent(intent);
}

此外，在 JavaScript 代码中使用与上述 iOS 后台/前台处理相同的方法实现推送消息处理。

验证指南

通过检查 Singular SDK 的启动会话调用和监控归因数据，验证推送通知跟踪是否正常工作。

验证启动会话中的有效载荷

检查 API 调用参数

通过检查启动会话 API 调用，确认推送通知链接已正确传递给 Singular。

当用户点击通知时，Singular SDK 会在开始会话请求的singular_link 参数下包含推送通知有效载荷。

启动会话请求示例：

https://sdk-api-v1.singular.net/api/v1/start?
a=<SDK-Key>
&singular_link=https://singularassist2.sng.link/C4nw9/r1m0?_dl=singular%3A%2F%2Ftest&_smtype=3
&i=net.singular.singularsampleapp
&install_time=1740905507036
&s=1740905574084
&sdk=Singular/v12.6.2
&singular_install_id=2dc5dfc2-a2a8-484a-aad1-fed6cb7a3023
&u=75f7b911-5a77-597d-8892-56f5e0e210ff

高级配置

实施高级推送通知功能，包括针对复杂通知场景的 ESP 域配置和动态深层链接路由。

ESP 域配置

配置外部域

如果在电子邮件服务提供商 (ESP) 或其他第三方域中封装 Singular 链接，请配置外部域。

// Create configuration
var config = new cordova.plugins.SingularCordovaSdk.SingularConfig(
  'YOUR_SDK_KEY',
  'YOUR_SDK_SECRET'
);

// Configure ESP domains for wrapped Singular links
config.withESPDomains(['sl.esp.link', 'custom.domain.com']);

// Initialize SDK
cordova.plugins.SingularCordovaSdk.init(config);

有关完整的方法文档，请参阅withESPDomains 参考资料。

动态深度链接路由

从单个通知执行多个操作

通过配置具有动态重定向重写功能的 Singular 跟踪链接，从单个通知中实现多个深度链接目的地。

用例示例：具有多个操作选项的突发新闻通知

• 阅读最新新闻： newsapp://article?id=12345
• 热门话题 newsapp://trending
• 体育： newsapp://sports

与其创建多个跟踪链接，不如使用一个单一链接，并根据用户选择动态覆盖重定向。有关实施详情，请参阅在奇异跟踪链接中覆盖重定向。

// Handle multiple deep link options from single notification
function handleNotificationWithActions(notificationData) {
  // Extract action selection from notification data
  var selectedAction = notificationData.action;
  var singularLink = notificationData.sng_link;
  
  // Route based on action
  switch (selectedAction) {
    case 'read_news':
      navigateToArticle(notificationData.article_id);
      break;
    case 'trending':
      navigateToTrending();
      break;
    case 'sports':
      navigateToSports();
      break;
    default:
      navigateToHome();
  }
  
  // Pass notification to Singular for attribution
  cordova.plugins.SingularCordovaSdk.handlePushNotification(notificationData);
}

function navigateToArticle(articleId) {
  console.log('Navigating to article:', articleId);
  // Your navigation logic
}

function navigateToTrending() {
  console.log('Navigating to trending');
  // Your navigation logic
}

function navigateToSports() {
  console.log('Navigating to sports');
  // Your navigation logic
}

function navigateToHome() {
  console.log('Navigating to home');
  // Your navigation logic
}

重要注意事项

了解与 Singular SDK 集成推送通知跟踪时的关键实施细节和限制。

实施注意事项

关键行为和限制

• 无回调处理程序：与withSingularLink 不同，推送通知功能不提供有效负载回调。您必须实施自己的深层链接逻辑，根据通知数据将用户导向应用程序中的特定内容。
• 归属流：当用户点击通知时，Singular 会检索有效载荷并将其包含在由Singular.init(config) 触发的启动会话事件中。后台会处理这些数据，对推送通知接触点进行归属，并注册重新参与跟踪。
• 域限制：默认情况下，只允许使用 "管理链接 "页面上的 Singular 链接域 (sng.link)。请使用withESPDomains()为封装链接明确配置 ESP 域。
• 平台差异：iOS 需要 AppDelegate 配置来处理终止状态，而 Android 则通过桥接模块自动处理终止状态场景
• 路径配置：SDK 会使用withPushNotificationsLinkPaths() 中定义的路径搜索 Singular 链接。请确保您的通知有效载荷结构与配置的路径相匹配，以便正确提取链接。

测试建议

1. 测试所有应用程序状态：验证推送跟踪在应用程序终止、后台和前台时是否正常工作
2. 验证有效载荷结构：确认您的通知有效载荷在配置的路径上包含奇异链接
3. 检查启动会话调用：使用网络监控工具验证singular_link 参数是否出现在启动会话请求中
4. 监控归属：检查 Singular SDK 控制台，确认推送通知在营销活动数据中的归属正确无误
5. 测试深层链接：验证用户在点击不同通知类型时是否被正确导航到目标内容