支持推送通知
通过将 Firebase Cloud Messaging (FCM) 与 Singular SDK 集成，跟踪用户与推送通知的互动，以衡量再参与活动并准确归因于转化。
请遵循以下实施指南，以确保通知数据正确传递到 Singular SDK，从而获得正确的归因。
为什么要跟踪推送通知？推送通知能推动用户重新参与，但跟踪需要正确的整合。Singular 可确保与通知互动的用户得到正确归因，从而优化营销活动和参与策略。
实施指南
集成 Singular SDK
使用Singular Unity SDK 指南中的标准安装说明，在您的 Unity 项目中集成Singular SDK。
配置推送链接路径
在推送通知有效载荷结构中定义 Singular 跟踪链接所在的 JSON 路径。
使用前冲分隔字符串配置推送链接路径，指定通知数据结构中 Singular 链接的关键路径。
// Configure push link paths in SDK initialization
SingularConfig config = new SingularConfig("SDK_KEY", "SDK_SECRET")
.WithPushNotificationsLinkPaths(new List<string>
{
"sng_link", // Top-level key
"path/to/url", // Nested path
"rootObj/nestedObj/singularLink" // Deep nested path
});
SingularSDK.InitializeSingularSDK();路径配置示例：
-
简单键：对有效负载中的顶级键使用
"sng_link" -
嵌套键：使用
"rootObj/nestedObj/key"遍历嵌套的 JSON 结构 - 多路径：定义多个路径字符串，以检查奇异链接的不同可能位置
注：Unity 编辑器不支持通过其 Inspector UI 输入列表，因此路径被配置为正向斜线分隔字符串，而不是嵌套数组。
特定平台处理
iOS 推送通知处理
终止状态（应用程序未运行）
处于终止状态的 iOS 应用程序无需手动操作。Singular iOS 集成会使用SingularAppController 自动处理推送跟踪。
自动处理：当用户在应用程序未运行时点击推送通知，Singular 会在应用程序启动时自动捕获通知有效载荷。
后台状态（应用程序在后台运行）
当应用程序处于后台时收到通知，可使用HandlePushNotification() 将推送数据传递给 SDK。
using UnityEngine;
using Singular;
using Firebase.Messaging;
using System.Collections.Generic;
public class PushNotificationHandler : MonoBehaviour
{
void Start()
{
// Subscribe to Firebase message received event
Firebase.Messaging.FirebaseMessaging.MessageReceived += OnMessageReceived;
}
private void OnMessageReceived(object sender, MessageReceivedEventArgs e)
{
Debug.Log("Received Firebase push notification");
// Extract notification data
var pushDataDictionary = new Dictionary<string, string>(e.Message.Data);
// Pass notification data to Singular SDK
SingularSDK.HandlePushNotification(pushDataDictionary);
// Your additional notification handling logic
DisplayNotification(e.Message);
}
}
重要：确保在任何自定义通知处理逻辑之前，在后台通知处理程序脚本中调用HandlePushNotification()。
安卓推送通知处理
自动处理（推荐）
确保您的主 Unity 活动扩展了SingularUnityActivity，以便在后台和终止状态下自动处理推送通知。
import com.singular.unitybridge.SingularUnityActivity;
public class MessagingUnityPlayerActivity extends SingularUnityActivity {
// Your custom activity logic here
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
// Your initialization code
}
}
最佳实践：通过扩展SingularUnityActivity ，当应用程序处于后台或终止状态时，SDK 会自动处理推送通知，从而避免了手动通知处理。
Firebase 集成示例
如果您需要自定义 Firebase 消息处理逻辑，请实现一个监听器并将通知数据转发给 Singular。
using UnityEngine;
using Singular;
using Firebase.Messaging;
using System.Collections.Generic;
public class AndroidPushHandler : MonoBehaviour
{
void Start()
{
// Subscribe to Firebase messaging events
Firebase.Messaging.FirebaseMessaging.MessageReceived += OnMessageReceived;
Firebase.Messaging.FirebaseMessaging.TokenReceived += OnTokenReceived;
}
private void OnMessageReceived(object sender, MessageReceivedEventArgs e)
{
Debug.Log("Received a new Firebase message");
// Convert message data to dictionary
var pushDataDictionary = new Dictionary<string, string>(e.Message.Data);
// Forward to Singular SDK for attribution
SingularSDK.HandlePushNotification(pushDataDictionary);
// Your custom handling logic
ProcessNotificationContent(e.Message);
}
private void OnTokenReceived(object sender, TokenReceivedEventArgs token)
{
Debug.Log($"FCM Token received: {token.Token}");
// Store or use token as needed
// Note: Singular automatically handles token registration
}
private void ProcessNotificationContent(FirebaseMessage message)
{
// Your custom notification display or routing logic
string title = message.Notification?.Title ?? "Notification";
string body = message.Notification?.Body ?? "";
Debug.Log($"Notification: {title} - {body}");
}
}验证指南
验证启动会话中的有效载荷
通过检查启动会话 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=com.yourcompany.app
&s=1740905574084
&sdk=Singular/Unity-v1.0.0替代验证：使用 Singular SDK 控制台验证推送通知跟踪。 检查Deeplink URL字段，确认跟踪链接已正确捕获。
高级配置
ESP 域配置
如果您在电子邮件服务提供商（ESP）或其他第三方域中封装 Singular 链接，请配置外部域。
// Configure ESP domains for wrapped Singular links
SingularConfig config = new SingularConfig("SDK_KEY", "SDK_SECRET")
.WithESPDomains(new List<string> { "sl.esp.link", "custom.domain.com" });
SingularSDK.InitializeSingularSDK();
安全提示：默认情况下，只允许在 "Singular 管理链接 "页面中预定义sng.link域。如果使用封装链接，请明确配置 ESP 域。
动态深度链接路由
通过配置一个具有动态重定向重写功能的 Singular 跟踪链接，从单个通知中实现多个深度链接目的地。
用例示例：具有多个操作选项的突发新闻通知
-
阅读最新新闻：
newsapp://article?id=12345 -
热门话题
newsapp://trending -
体育：
newsapp://sports
与其创建多个跟踪链接，不如使用一个单一链接，并根据用户选择动态覆盖重定向。有关实施详情，请参阅在奇异跟踪链接中覆盖重定向。
重要注意事项
实施注意事项
-
无回调处理程序：与
SetSingularLinkHandler不同，推送通知功能不提供有效载荷回调。请实施您自己的深度链接逻辑，将用户引导至您应用中的特定内容。 - 归属流：当用户点击通知时，Singular 会检索有效载荷，并将其包含在 SDK 初始化触发的启动会话事件中。后台会处理这些数据，对推送通知接触点进行归因，并注册重新参与跟踪。
-
域限制：默认情况下，只允许使用 "管理链接 "页面上的单链接域 (
sng.link)。请使用WithESPDomains()为封装链接明确配置 ESP 域。 -
平台差异：iOS 自动处理终止状态通知，而 Android 需要扩展
SingularUnityActivity才能自动处理
成功：通过这些步骤，您的应用程序现在可以通过 Singular 跟踪推送通知互动，从而提高活动性能洞察力并确保准确的再参与归因。