消息覆盖和撤回最佳实践

消息覆盖和消息撤回都可以用于处理已经创建的推送任务，但两者的目标不同：

• 消息覆盖：使用一条新的推送覆盖上一条推送，适合更新通知内容。
• 消息撤回：撤销一条已经发出的推送，适合终止错误、过期或不应继续展示的通知。

在设计业务流程时，建议先判断用户是否还需要看到这条通知。如果只是内容发生变化，优先使用消息覆盖；如果通知本身不应继续触达或展示，使用消息撤回。

能力对比

消息覆盖

适合使用覆盖的场景

消息覆盖适合“同一业务事件持续更新”的场景。典型例子：

• 订单状态从“已接单”更新为“配送中”。
• 排队、叫号、进度类通知需要刷新最新状态。
• 活动通知文案或跳转参数需要修正，但仍希望用户收到最新内容。
• 离线用户上线后只需要看到最终状态，不需要收到多条历史状态通知。

Android 覆盖实现方式

Android 平台调用 Push API v3 发送新消息时，在 options.override_msg_id 中填写上一条推送返回的 msg_id。

          {
  "platform": "android",
  "audience": {
    "registration_id": ["1104a89792xxxxxx"]
  },
  "notification": {
    "android": {
      "alert": "您的订单正在配送中",
      "title": "订单状态更新"
    }
  },
  "options": {
    "override_msg_id": 1234567890
  }
}

        

Android 注意事项

• override_msg_id 填写的是要覆盖的上一条推送的 msg_id。
• 覆盖功能有效期为 1 天；如果在有效期内找不到对应 msg_id，会返回 1003，当前消息不会被推送。
• override_msg_id 对 Android 有效。
• 当前仅支持极光通道、小米通道、OPPO 通道、vivo 通道、FCM 通道、荣耀通道、华为通道（EMUI 10 及以上设备）和鸿蒙通道。
• 对离线用户，最终收到的是覆盖后的消息内容。
• 对 Android 端已收到的通知，如果通知栏还未清除，新消息内容会覆盖之前的通知。

iOS 覆盖实现方式

iOS 平台使用 options.apns_collapse_id 作为更新 iOS 通知的标识符。APNs 新通知如果匹配到当前通知中心有相同 apns-collapse-id 字段的通知，则会用新通知内容来更新它，并使其置于通知中心首位。

          {
  "platform": "ios",
  "audience": {
    "registration_id": ["1104a89792xxxxxx"]
  },
  "notification": {
    "ios": {
      "alert": "您的订单正在配送中",
      "sound": "default"
    }
  },
  "options": {
    "apns_production": true,
    "apns_collapse_id": "order_202607280001"
  }
}

        

iOS 注意事项

• apns_collapse_id 用于标识需要被更新的同一类通知，建议按业务对象生成稳定值，例如订单号、排队号、任务 ID 等。
• 多次推送使用相同 apns_collapse_id 时，APNs 会尝试用新通知更新通知中心内相同标识的旧通知。
• apns_collapse_id 长度不可超过 64 bytes。
• iOS 覆盖效果依赖 APNs 和系统通知中心处理结果，建议同时在业务落地页做状态校验。

消息撤回

适合使用撤回的场景

消息撤回适合“这条通知不应继续存在”的场景。典型例子：

• 活动、券、任务已经过期，不希望用户继续点击。
• 误发通知或通知内容存在错误，需要尽快停止继续触达。
• 风险、审核或运营策略变化，需要撤销已发出的提醒。
• 对已展示但未点击的通知，希望尽量从设备通知栏移除。

实现方式

调用推送撤销 API，使用要撤回消息的 msgid 作为路径参数。

          DELETE /v3/push/{msgid}
Authorization: Basic (base64 auth string)
Content-Type: text/plain
Accept: application/json

        

完整调用地址：

          DELETE https://api.jpush.cn/v3/push/{msgid}

        

成功时返回 HTTP 200，且响应体为空。

如果撤回失败，可能返回 HTTP 400 和错误原因。例如：

          {
  "error": {
    "code": 1003,
    "message": "msgid doesn't exist"
  }
}

        

撤回效果说明

撤回操作会先从服务端尝试撤销：

• Android 消息处于排队中或发送中状态时，可以服务端撤销。
• iOS 消息处于排队中状态时，可以服务端撤销。

对于已展示在设备端但未被点击的消息，Push SDK 会尝试从设备端撤销：

• Android 需 JPush Android SDK v3.5.0 及以上。
• iOS 需 JPush iOS SDK v3.2.8 及以上。
• Android 厂商侧目前主要支持并已适配小米、vivo。

注意事项

• 推送撤销 API 的调用频率与 Push API v3 共用，会互相影响和消耗。
• 撤回能力受消息状态、SDK 版本、厂商能力和终端状态影响，不保证所有已展示通知都能被移除。
• 对已经被用户点击、清除或系统处理过的通知，设备端撤回可能不再生效。
• 如果业务要求强一致的“不可访问”，还应在落地页、活动页或服务端业务接口增加状态校验，避免用户通过历史链接继续访问。

选择建议

优先使用消息覆盖

当业务目标是“让用户看到最新内容”时，优先使用消息覆盖。例如订单状态、配送进度、排队进度、待办状态更新等。

建议做法：

• Android：保存首次推送返回的 msg_id，后续同一业务事件更新时，将上一条 msg_id 写入 options.override_msg_id。
• iOS：为同一业务事件生成稳定的 apns_collapse_id，后续更新通知时继续使用同一个值。
• 如果 Android 覆盖返回 1003，说明无法完成有效覆盖，可根据业务需要重新发送一条普通推送。

优先使用消息撤回

当业务目标是“让用户尽量不要再看到或点击这条消息”时，优先使用消息撤回。例如误发、过期、取消、风控拦截等。

建议做法：

• 保存需要撤回的 msgid。
• 尽早调用推送撤销 API，越早撤回，服务端撤销成功概率越高。
• 对重要业务增加兜底校验，例如落地页状态检查、活动有效期校验、订单状态校验等。

推荐业务流程

1. 发送第一条业务通知，并保存返回的 msg_id 与业务单号的映射关系。
2. 业务状态发生变化时，判断是“更新内容”还是“取消通知”。
3. 更新内容时，调用 Push API v3。Android 设置 options.override_msg_id；iOS 设置 options.apns_collapse_id。
4. 取消通知时，调用推送撤销 API。
5. 对通知落地页或业务接口增加状态校验，确保用户点击历史通知时仍能看到正确结果。

相关文档

• Push API v3 - override_msg_id
• Push API v3 - apns_collapse_id
• Push API v3 高级功能 - 推送撤销 API