如何实现消息覆盖和撤回

支持通道

平台	消息覆盖	消息撤回
Android	极光通道小米通道魅族通道 OPPO 通道 FCM 通道华为通道（EMUI10 及以上的设备）	极光通道小米通道
iOS	APNs 通道	-
HarmonyOS	鸿蒙通道	极光通道鸿蒙通道

消息覆盖

说明

JPush Android 基于 override_msg_id ，iOS 基于 apns_collapse_id 来定义消息覆盖逻辑。
即对于同一个应用，如果新的一条消息其 override_msg_id 或 apns_collapse_id 存在并与老的一条消息相同，则会被认为是要覆盖老的消息。
这个情况对于是否保存离线消息有所不同：

如果客户端已经收到，用户已经点击打开通知：则新的消息（override_msg_id 存在的消息）还是会显示在通知栏，用户看到的是有新的一条消息。
如果客户端已经收到，但还在通知栏：则新的消息会在通知栏上覆盖老的消息。用户看到新的消息内容。
如果 Android 客户端还未收到，消息还在离线消息里，则：新的消息会覆盖老的消息，用户不会收到老的消息。
如果 iOS 客户端还未收到，由于 Apple 服务器仅保留一条 apns 消息，所以上线后用户也不会收到老的消息。

服务端使用

下发时在 options 字段下配置 override_msg_id 和 apns_collapse_id 参数，可以实现消息覆盖。

关键字	类型	选项	含义	说明
override_msg_id	long	可选	要覆盖的消息 ID	如果当前的推送要覆盖之前的一条推送，这里填写前一条推送的 msg_id 就会产生覆盖效果，即：该 msg_id 离线收到的消息是覆盖后的内容，即使该 msg_id Android 端用户已经收到，如果通知栏还未清除，则新的消息内容会覆盖之前这条通知。覆盖功能起作用的时限是：1 天，如果在覆盖指定时限内该 msg_id 不存在，则返回 1003 错误，提示不是一次有效的消息覆盖操作，当前的消息不会被推送。该字段仅对 Android 有效仅支持极光通道、小米通道、OPPO 通道、FCM 通道、魅族通道和华为通道（EMUI10 及以上的设备）。
apns_collapse_id	string	可选	更新 iOS 通知的标识符	APNs 新通知如果匹配到当前通知中心有相同 apns_collapse_id 字段的通知，则会用新通知内容来更新它，并使其置于通知中心首位。 collapse id 长度不可超过 64 bytes。

Android 示例

{ "platform": "all", "audience": { "registration_id": [ "1507bfd3f710de7a40a" ] }, "notification": { "android": { "alert": "Hi, JPush!fvdgtredfgerg", "title": "Send to androidre" } }, "options": { "override_msg_id": 67554224848096790,//要覆盖的消息 ID "third_party_channel": { "oppo": { "distribution": "jpush" } } } }

          {
    "platform": "all",
    "audience": {
        "registration_id": [
            "1507bfd3f710de7a40a"
        ]
    },
    "notification": {
        "android": {
            "alert": "Hi, JPush!fvdgtredfgerg",
            "title": "Send to androidre"
        }
    },
    "options": {
        "override_msg_id": 67554224848096790,//要覆盖的消息 ID
        "third_party_channel": {
            "oppo": {
                "distribution": "jpush"
            }
        }
    }
}

此代码块在浮窗中显示

iOS 示例

{ "platform": "all", "audience": { "registration_id": [ "101d855909917e5faf8" ] }, "notification": { "ios": { "alert": "Hi, JPush!!!", "sound": "default", "badge": "+1", "thread-id": "default", "extras": { "key": "my_extra1" } } }, "options": { "apns_production": false, "apns_collapse_id": "12345"//需要与覆盖的消息使用相同的id,APNs 新通知如果匹配到当前通知中心有相同 apns_collapse_id 字段的通知，则会用新通知内容来更新它，并使其置于通知中心首位。 } }

          {
    "platform": "all",
    "audience": {
        "registration_id": [
            "101d855909917e5faf8"
        ]
    },
    "notification": {
        "ios": {
            "alert": "Hi, JPush!!!",
            "sound": "default",
            "badge": "+1",
            "thread-id": "default",
            "extras": {
                "key": "my_extra1"
            }
        }
    },
    "options": {
        "apns_production": false,
        "apns_collapse_id": "12345"//需要与覆盖的消息使用相同的id,APNs 新通知如果匹配到当前通知中心有相同 apns_collapse_id 字段的通知，则会用新通知内容来更新它，并使其置于通知中心首位。
    }
}

此代码块在浮窗中显示

HarmonyOS 示例

{ "platform": "all", "audience": { "registration_id": [ "1507bfd3f710de7a40a" ] }, "notification": { "hmos": { "alert": "Hi, JPush!fvdgtredfgerg", "title": "Send to androidre" } }, "options": { "override_msg_id": 67554224848096790,//要覆盖的消息 ID } }

          {
    "platform": "all",
    "audience": {
        "registration_id": [
            "1507bfd3f710de7a40a"
        ]
    },
    "notification": {
        "hmos": {
            "alert": "Hi, JPush!fvdgtredfgerg",
            "title": "Send to androidre"
        }
    },
    "options": {
        "override_msg_id": 67554224848096790,//要覆盖的消息 ID
    }
}

此代码块在浮窗中显示

消息撤回

撤销操作首先会从服务端尝试撤销（Android消息，排队中/发送中状态可以服务端撤销；iOS消息，排队中状态可以服务端撤销）；其次，针对 Push SDK（JPush Android SDK v3.5.0 及以上），会尝试从设备端撤销已展示但未被点击的消息。

注意：仅安卓极光通道和小米通道支持消息撤回。

调用地址

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

请求示例

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

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

此代码块在浮窗中显示

请求响应

成功响应

HTTP/1.0 200 Content-Type: application/json Content-Length: 0

          HTTP/1.0 200 
  Content-Type: application/json
  Content-Length: 0

此代码块在浮窗中显示

失败响应

HTTP/1.0 400 Content-Type: application/json Content-Length: 0

          HTTP/1.0 400 
  Content-Type: application/json
  Content-Length: 0

此代码块在浮窗中显示

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

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

此代码块在浮窗中显示