Unity SDK - 支持推送通知

支持推送通知

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

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

为什么要跟踪推送通知?推送通知能推动用户再互动,但跟踪需要正确的整合。Singular 可确保与通知互动的用户得到正确归因,从而优化营销活动和参与策略。


实施指南

集成 Singular SDK

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


配置推送链接路径

在推送通知有效载荷结构中定义 Singular 跟踪链接所在的 JSON 路径。

使用前冲分隔字符串配置推送链接路径,指定通知数据结构中 Singular 链接的关键路径。

SingularSDKObject 预制件的 Unity Inspector,其中 Push Notifications Link Paths 列表已展开为三个元素。

C#
// Set the paths on the SingularSDK component before the SDK initializes.
// Clear Initialize On Awake in the Inspector so this runs first.
SingularSDK singular = GetComponent<SingularSDK>();

singular.pushNotificationsLinkPaths = new 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 结构
  • 多路径:定义多个路径字符串,以检查Singular链接的不同可能位置

注:Unity 编辑器不支持通过其 Inspector UI 输入列表,因此路径被配置为正向斜线分隔字符串,而不是嵌套数组。

完整的配置说明请参阅pushNotificationsLinkPaths 参考


特定平台处理

iOS 推送通知处理

终止状态(应用程序未运行)

处于终止状态的 iOS 应用程序无需手动操作。Singular iOS 集成会使用SingularAppController 自动处理推送跟踪。

自动处理:当用户在应用程序未运行时点击推送通知,Singular 会在应用程序启动时自动捕获通知有效载荷。

后台状态(应用程序在后台运行)

当应用程序处于后台时收到通知,可使用HandlePushNotification() 将推送数据传递给 SDK。

C#
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,以便在后台和终止状态下自动处理推送通知。

Java
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。

C#
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字段,确认跟踪链接已正确捕获。


高级配置

品牌域名配置

如果推送载荷中的 Singular Links 使用的是您自己的跟踪域名而非 sng.link,请登记这些域名,以便 SDK 将其识别为 Singular Links。

C#
// Set the domains on the SingularSDK component before the SDK initializes
SingularSDK singular = GetComponent<SingularSDK>();

singular.brandedDomains = new string[] { "go.yourcompany.com", "promo.yourcompany.com" };

SingularSDK.InitializeSingularSDK();

默认情况下,SDK 只识别在 Singular Manage Links 页面登记的 sng.link 域名。推送载荷中出现的任何自定义跟踪域名也必须在此登记。

完整的配置说明请参阅brandedDomains 参考


动态深度链接路由

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

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

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

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


重要注意事项

实施注意事项

  • 无回调处理程序:SetSingularLinkHandler 不同,推送通知功能不提供有效载荷回调。请实施您自己的深度链接逻辑,将用户引导至您应用中的特定内容。
  • 归因流:当用户点击通知时,Singular 会检索有效载荷,并将其包含在 SDK 初始化触发的启动会话事件中。后台会处理这些数据,对推送通知接触点进行归因,并注册再互动跟踪。
  • 域名限制:默认情况下,只有 Manage Links 页面中登记的 Singular 链接域名(sng.link)会被识别。推送载荷中出现的任何自定义跟踪域名请添加到 brandedDomains
  • 平台差异:iOS 自动处理终止状态通知,而 Android 需要扩展SingularUnityActivity 才能自动处理

成功:通过这些步骤,您的应用程序现在可以通过 Singular 跟踪推送通知互动,从而提高活动性能洞察力并确保准确的再互动归因。