自定义消息转厂商通知最佳实践

自定义消息通常依赖 App 与极光服务之间的长连接。Android、iOS、HarmonyOS 设备在 App 长连接不在线时，自定义消息无法及时下发。对于 IM、待办、工单、告警、订单状态等重要自定义消息，可以使用“自定义消息转厂商通知”能力，在用户离线时通过厂商通道补发通知，提升及时提醒能力。

本文基于 Push API v3 的 notification_3rd 能力，帮助您设计“在线走自定义消息、离线转厂商通知”的稳定链路。

适用场景

如需使用此能力，需要开通对应厂商通道能力；具体权限可联系极光商务或技术支持确认。

核心原则

• message 负责业务数据，notification_3rd 负责离线时展示给用户的通知内容。
• 推荐直接使用 v2 版本：在 options.notification_3rd_ver 中设置 "v2"。
• notification_3rd 只针对开通厂商通道的用户生效。
• notification 和 notification_3rd 不能同时有内容，否则请求会返回错误。
• 只有 message 部分有内容时，才允许传递 notification_3rd。
• 不要把普通营销内容包装成重要自定义消息，应遵守厂商消息分类和运营消息频控规则。
• 点击通知后的业务页必须做状态校验，避免用户点击过期通知看到错误结果。

v2 与 v1 选择

新接入建议统一使用 v2，避免后续多平台扩展时重新调整协议。

推荐接入流程

1. 客户端完成极光 SDK 集成，并能正常获取 Registration ID。
2. Android 和 HarmonyOS 按需完成厂商通道集成，确认厂商 token 正常回调。
3. iOS 确认 APNs 证书或 Token Authentication、Bundle ID、生产/开发环境配置正确。
4. 服务端定义业务消息协议，放入 message.msg_content 或 message.extras。
5. 服务端定义离线提醒文案、标题、点击跳转和扩展字段，放入 notification_3rd。
6. API 请求中设置 options.notification_3rd_ver="v2"。
7. 根据业务重要程度设置 options.classification、time_to_live、厂商分类字段和下发策略。
8. 通过推送记录、消息查询、统计 API 和回执 API 验证在线、离线两类设备的实际效果。

API 示例

以下示例展示一条待办提醒：App 在线时收到自定义消息并处理业务协议；App 长连接不在线时，通过厂商通知提醒用户。

          {
  "platform": "all",
  "audience": {
    "registration_id": ["1104a89792xxxxxx"]
  },
  "message": {
    "msg_content": "new_todo",
    "extras": {
      "todo_id": "todo_202607280001",
      "action": "open_todo_detail"
    }
  },
  "notification_3rd": {
    "android": {
      "alert": "您有一条新的待办需要处理",
      "title": "待办提醒",
      "channel_id": "todo_reminder",
      "intent": {
        "url": "intent:#Intent;component=com.example.app/com.example.app.TodoDetailActivity;S.todo_id=todo_202607280001;end"
      },
      "extras": {
        "todo_id": "todo_202607280001"
      }
    },
    "ios": {
      "alert": "您有一条新的待办需要处理",
      "sound": "default",
      "badge": "+1",
      "thread-id": "todo",
      "extras": {
        "todo_id": "todo_202607280001"
      }
    },
    "hmos": {
      "alert": "您有一条新的待办需要处理",
      "title": "待办提醒",
      "intent": {
        "url": "scheme://todo/detail?todo_id=todo_202607280001"
      },
      "category": "IM",
      "test_message": false,
      "extras": {
        "todo_id": "todo_202607280001"
      }
    }
  },
  "options": {
    "notification_3rd_ver": "v2",
    "classification": 1,
    "time_to_live": 86400
  }
}

        

示例中的分类、channel、category、intent 仅用于说明字段位置，实际值应以您的应用、厂商审核结果和客户端页面配置为准。

客户端设计建议

在线处理

• 客户端收到自定义消息后，应按业务协议处理，不要依赖通知栏展示。
• 对同一业务事件建议使用业务 ID 去重，例如会话 ID、工单 ID、订单 ID、告警 ID。
• 如果在线时已经展示了应用内提醒，后续打开离线通知落地页时仍要检查状态，避免重复处理。

离线通知点击

• Android API 推送时建议填写 intent，否则点击通知可能没有跳转动作。
• OPPO 和 FCM 通道对跳转参数有特殊要求，需按 Android 通知点击跳转文档配置。
• iOS 使用 extras、thread-id 等字段承载业务参数和通知分组。
• HarmonyOS 使用 intent.url 和 extras 承载跳转与业务参数。
• 落地页必须根据业务 ID 查询最新状态，不要只相信通知内容本身。

消息分类与频控

自定义消息转厂商通知最终会以通知形式展示给用户，因此也需要遵守通知相关规则：

• 订单、待办、工单、账号安全等用户强相关消息，可按系统消息或服务类消息申请厂商分类。
• 内容推荐、活动、营销、平台公告等应按运营消息处理。
• Android API 下发时优先设置 options.classification，1 表示系统消息，0 表示运营消息。
• 如果补发通知属于运营消息，应同时配置极光频控和厂商运营消息策略，避免过度打扰。
• 如果消息内容会持续更新，可结合 Android override_msg_id 或 iOS apns_collapse_id 减少重复通知。

排查建议

如果自定义消息或补发通知未达到预期，建议按以下顺序排查：

1. 检查 Push API 是否返回成功，并保存 msg_id。
2. 检查请求中是否只有 message 和 notification_3rd，没有同时传 notification。
3. 检查 options.notification_3rd_ver 是否设置为 "v2"。
4. 检查目标设备是否开通并成功注册厂商通道。
5. 使用设备查询确认 Registration ID、在线状态、通知权限和厂商 token。
6. 使用消息查询查看 Message ID + Registration ID 的生命周期。
7. 检查点击跳转参数是否与客户端 Activity、deeplink 或页面路由一致。
8. 使用统计 API 和回执 API 观察送达、未送达和点击数据。

相关文档

• Push API v3 - notification_3rd：自定义消息转厂商通知
• Push API v3
• 如何设置通知下发策略
• Android 通知点击跳转
• iOS 通知点击跳转
• 厂商消息分类使用指南
• 厂商限额及 QPS 限制
• 推送排查最佳实践