推送通知

在应用关闭时投递客服回复和营销活动，并通过深度链接直达对应的对话。推送子系统由您的应用掌控；SDK 负责注册令牌并打开对话。

Respondo 会发送什么#

消息推送 —— 访客所参与对话中，客服或 AI 的回复。
营销推送 —— 外呼式推送营销活动，同时会上报一次打开信标（open beacon）。

消息推送始终携带一个形如 respondo://conversation/<id> 的深度链接。营销推送携带的是在营销活动上配置的深度链接——它是可选的，未设置时推送不包含深度链接。

Apple（APNs）#

iOS 推送直接走 APNs——不依赖 Firebase。请从您的 Apple Developer 账户获取：

一个 APNs Auth Key（.p8 token key）。
该密钥的 Key ID。
您的 Team ID。
应用的 bundle id。

Google（FCM）#

Android 推送通过 Firebase Cloud Messaging。请从您的 Firebase 项目获取：

一个具备 Cloud Messaging 角色的 service account JSON。
Firebase 项目 ID（Firebase 控制台 → Project settings）——在控制台的推送表单中作为独立字段填写，与 service-account JSON 并列。
Android 应用的 package name，并将应用连接到同一个 Firebase 项目（google-services.json）。

在 Respondo 中配置#

在控制台中把 APNs 密钥以及 FCM service account 连同其项目 ID 添加到您的挂件渠道。这就是 Respondo 向两个平台发送推送所需的全部内容。

通过 API 设置凭据以及完整的字段说明，都在随您的 SDK 访问权限一并提供的推送配置指南中。

Payload 格式#

payload 始终位于根级的 respondo 键下—— SDK 正是通过它是否存在来区分自己的推送与其他推送（在 iOS 上位于 userInfo 中，在 Android 上作为 JSON 字符串位于 data["respondo"] 中）。

respondo payloadjson

{
  "respondo": {
    "type": "message",
    "conversation_id": "a1c4e7b2-5d38-4f6a-9e10-3b7c2d5f8a90",
    "message_id": "e9a3c1f6-4b8d-4e0a-b5f3-1d7b2a4e9c63",
    "deep_link": "respondo://conversation/a1c4e7b2-5d38-4f6a-9e10-3b7c2d5f8a90"
  }
}

所有值都是扁平的字符串。通知的标题和正文由平台传输通道投递——APNs 上的 aps.alert 和 FCM 上的 message.notification——而不在 respondo 对象内部。

营销推送还会包含一个 delivery_id，用于上报打开信标，并且可能携带来自营销活动推送数据的额外扁平字符串键。

处理点击与前台#

在通知被点击时，把原始 payload 交给 SDK。它会解析 payload 并打开对应的对话，如果该推送不是 Respondo 推送则返回 false（此时请您自行处理）。

处理点击（各平台）text

Android:  RespondoPushPayload.from(data)?.let { Respondo.handlePush(it) }
iOS:      Respondo.handlePush(userInfo: userInfo)
Flutter:  Respondo.handlePushData(message.data)

重复项会按 message_id 合并去重，并且当同一个对话正在前台打开时，系统通知会被抑制——这两点 SDK 都会自动处理。

注册设备令牌#

您的应用从其推送子系统获取设备令牌，并将其传给 setPushToken。退出登录时调用 clearPushToken。

该传哪个令牌。后端按平台路由每一次投递——iOS 直接走 APNs，Android 走 FCM—— 因此您必须注册该平台原生传输通道的令牌，而不是您的推送库恰好返回给您的那个：

Android —— 来自 FirebaseMessaging.getToken() 的 FCM 注册令牌。
iOS（原生） —— 来自 didRegisterForRemoteNotificationsWithDeviceToken 的 APNs 设备令牌（十六进制）。
通过 Flutter 的 iOS（firebase_messaging）—— 请使用 getAPNSToken()，而不是 getToken()。在 iOS 上传入 FCM 令牌会把它发到 APNs，而它在那里并不是有效的设备令牌，推送将永远不会送达。 getAPNSToken() 在启动后的最初片刻可能为 null——若是如此，请稍后短暂延迟后重试。

Android — FirebaseMessagingServicekotlin

override fun onNewToken(token: String) {
    Respondo.setPushToken(token)
}

iOS — AppDelegateswift

func application(
    _ application: UIApplication,
    didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data
) {
    let token = deviceToken.map { String(format: "%02x", $0) }.joined()
    Respondo.setPushToken(token)
}

Flutter — firebase_messagingdart

// iOS 需要 APNs 令牌；Android 需要 FCM 令牌。
final token = Platform.isIOS
    ? await FirebaseMessaging.instance.getAPNSToken()
    : await FirebaseMessaging.instance.getToken();
if (token != null) Respondo.setPushToken(token);

// FCM 会轮换其注册令牌；保持 Android 端同步。
if (!Platform.isIOS) {
  FirebaseMessaging.instance.onTokenRefresh.listen(Respondo.setPushToken);
}