支持推送通知

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

请遵循以下实施指南,确保通知数据正确传递给 Singular SDK,以便进行正确的归因。

实施指南

处理 FCM 通知

在您的 FirebaseMessagingService 中重写 onMessageReceived() 方法,以便在推送消息到达时捕获通知数据。

override fun onMessageReceived(message: RemoteMessage) {
    super.onMessageReceived(message)
    var title = ""
    var body = ""

    message.notification?.let {
        Log.d("singular-app", it.toString())
        title = it.title ?: ""
        body = it.body ?: ""
    }

    val data: Map<String, String> = message.data
    if (data.isNotEmpty()) {
        Log.d("singular-app", data.toString())
    }

    // Forward payload data to intent
    processNotification(title, body, data)
}

@Override
public void onMessageReceived(@NonNull RemoteMessage message) {
    super.onMessageReceived(message);
    String title = "";
    String body = "";

    if (message.getNotification() != null) {
        Log.d("singular-app", message.getNotification().toString());
        title = message.getNotification().getTitle();
        body = message.getNotification().getBody();
    }

    Map<String, String> data = message.getData();
    if (!data.isEmpty()) {
        Log.d("singular-app", data.toString());
    }

    // Forward payload data to intent
    processNotification(title, body, data);
}

处理并转发通知数据

创建一个 intent,将通知 payload 附加到该 intent 后启动 MainActivity, 确保 Singular 接收到跟踪数据。

private fun processNotification(title: String, body: String, data: Map<String, String>) {
    val intent = Intent(this, MainActivity::class.java).apply {
        flags = Intent.FLAG_ACTIVITY_NEW_TASK or Intent.FLAG_ACTIVITY_CLEAR_TASK

        // Attach notification data to the intent
        data.forEach { (key, value) ->
            putExtra(key, value)
        }
    }

    val pendingIntent = PendingIntent.getActivity(
        this,
        0,
        intent,
        PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE
    )

    val notificationBuilder = NotificationCompat.Builder(this, "your_channel_id")
        .setSmallIcon(R.drawable.ic_notification)
        .setContentTitle(title)
        .setContentText(body)
        .setPriority(NotificationCompat.PRIORITY_HIGH)
        .setAutoCancel(true)
        .setContentIntent(pendingIntent)

    val notificationManager = getSystemService(Context.NOTIFICATION_SERVICE) as? NotificationManager
    notificationManager?.notify(0, notificationBuilder.build())
}

private void processNotification(String title, String body, Map<String, String> data) {
    Intent intent = new Intent(this, MainActivity.class);
    intent.setFlags(Intent.FLAG_ACTIVITY_NEW_TASK | Intent.FLAG_ACTIVITY_CLEAR_TASK);

    // Attach notification data to the intent
    for (Map.Entry<String, String> entry : data.entrySet()) {
        intent.putExtra(entry.getKey(), entry.getValue());
    }

    PendingIntent pendingIntent = PendingIntent.getActivity(
            this,
            0,
            intent,
            PendingIntent.FLAG_UPDATE_CURRENT | PendingIntent.FLAG_IMMUTABLE
    );

    NotificationCompat.Builder notificationBuilder = new NotificationCompat.Builder(this, "your_channel_id")
            .setSmallIcon(R.drawable.ic_notification)
            .setContentTitle(title)
            .setContentText(body)
            .setPriority(NotificationCompat.PRIORITY_HIGH)
            .setAutoCancel(true)
            .setContentIntent(pendingIntent);

    NotificationManager notificationManager = (NotificationManager) getSystemService(Context.NOTIFICATION_SERVICE);
    if (notificationManager != null) {
        notificationManager.notify(0, notificationBuilder.build());
    }
}

为推送 payload 配置 SDK

将推送通知 payload 选择器添加到您的 SDK 配置中, 以指定 Singular 链接在通知数据结构中的位置。

val pushSelectors = arrayOf(
    arrayOf("sng_link"),
    arrayOf("rootObj", "nestedObj", "anotherNested", "singularLink")
)

val config = SingularConfig("SDK_KEY", "SDK_SECRET")
    .withPushNotificationPayload(intent, pushSelectors)

Singular.init(applicationContext, config)

String[][] pushSelectors = {
    {"sng_link"},
    {"rootObj", "nestedObj", "anotherNested", "singularLink"}
};

SingularConfig config = new SingularConfig("SDK_KEY", "SDK_SECRET")
    .withPushNotificationPayload(getIntent(), pushSelectors);

Singular.init(getApplicationContext(), config);

选择器配置:

• 简单键: 对 payload 中的顶层键使用 arrayOf("sng_link") 。
• 嵌套键: 使用 arrayOf("rootObj", "nestedObj", "key") 遍历嵌套的 JSON 结构。
• 多条路径: 定义多个选择器数组, 以检查 Singular 链接可能出现的不同位置。

验证指南

在 Start Session 中验证 payload

通过检查 Start Session API 调用,确认推送通知链接已正确传递给 Singular。

当用户点击通知时,Singular SDK 会在 Start Session 请求的 singular_link 参数中包含推送通知 payload。

Start Session 请求使用示例:

https://sdk-api-v1.singular.net/api/v1/start?
a=<SDK-Key>
&singular_link=https://singularassist2.sng.link/C4nw9/r1m0?_dl=singular://test&_smtype=3
&i=net.singular.singularsampleapp
&s=1740905574084
&sdk=Singular/v12.6.2

高级配置

ESP 域名配置

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

val config = SingularConfig("SDK_KEY", "SDK_SECRET")
    .withESPDomains(listOf("sl.esp.link", "custom.domain.com"))

SingularConfig config = new SingularConfig("SDK_KEY", "SDK_SECRET")
    .withESPDomains(Arrays.asList("sl.esp.link", "custom.domain.com"));

动态深度链接路由

通过为一个 Singular 跟踪链接配置动态再营销覆盖, 可以从单条通知实现多个深度链接目标。

使用示例: 包含多种操作选项的突发新闻通知

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

不必创建多个跟踪链接,只需使用一条 Singular 链接,根据用户的选择动态地覆盖再营销。实现细节请参见 在 Singular 跟踪链接中覆盖再营销 。

重要注意事项

实施注意事项

• 无回调处理程序: 与 withSingularLink 不同,推送通知功能不提供 payload 回调。请实现您自己的深度链接逻辑, 以将用户导向应用内的特定内容。
• 归因流程: 当用户点击通知时, Singular 会获取 payload 并将其包含在由 Singular.init() 触发的 Start Session 事件中。后端处理这些数据, 以归因推送通知触点并登记再互动跟踪。
• 域名限制: 默认情况下,仅允许 Manage Links 页面中的 Singular 链接域名 ( sng.link )。如果使用封装链接,请使用 withESPDomains() 显式配置 ESP 域名。