跳到主要内容

推送 Plus

概述

推送 Plus 是为高频、并发推送需求提供的增值推送服务。支持推送文本、富媒体、自定义消息等,适用于社交互动、交易状态同步、系统升级、帐号唤醒拉活、活动通知等推送运营服务场景,并支持推送数据统计。

推送 Plus 独享推送通道,具备更高的并发处理能力,可毫秒级触达目标用户。推送 Plus 数据统计提供推送成功、失败、到达、点击数据统计能力。开发者可通过 API 或控制台获取相关数据。

推送 Plus 需要付费开通后才能使用。欢迎访问官网推送 Plus 产品介绍页,或直接前往控制台开通推送 Plus

该功能开发环境下可免费使用。生产环境下,需要在控制台开通推送 Plus 服务后才能使用。

注意事项

  • 手机厂商推送通道是从系统层维护的长连接通道,比即时通讯服务自建推送通道 RongPush 更省电,到达率更高。希望使用推送 Plus 的客户,应尽量集成第三方厂商推送通道。
  • 华为推送通道上报推送点击数据,要求客户端使用 5.1.4 或更高版本的 SDK。从 5.2.3 版本开始无需客户端手动上报。
  • Google FCM 支持统计推送点击数据和 透传消息方式 的推送到达数据,5.3.0 版本前的客户端需手动上报推送到达数据。
  • APNs 推送通道无法直接获取推送到达、点击数据。iOS 客户端需要主动上报推送到达数据与推送点击数据,且必须使用 5.1.4 或更高版本的 SDK。
  • 如需按用户标签推送,请确保已通过设置用户标签批量设置用户标签 接口给 App Key 下用户设置了标签。

基本流程

  1. 在控制台开通推送 Plus
  2. 因第三方推送服务设计差异,客户端 SDK 无法直接获取全部推送平台的推送到达、点击通知数据。需要您前往厂商推送平台进行设置或通过客户端 SDK 主动上报:
  3. 使用推送 Plus 专用推送接口,发送全量用户不落地通知。
  4. 使用控制台与服务端 API 获取推送成功、到达、点击数据。

推送 Plus 专用推送接口

推送 Plus 服务支持高并发发送不落地通知。开通推送 Plus 后,请使用专用的服务端 API 接口发送全量用户不落地通知。

提示

从即时通讯服务端发送不落地通知时,无论用户是否正在使用 App,都会向用户发送通知。通知仅展示在通知栏。区别于落地通知,不落地通知不携带聊天会话消息,即用户登录 App 后不会在聊天页面看到该内容,不会存储到本地数据库。​

即时通讯服务将 30 天内连接过 IM 服务的设备作为推送的目标。30 天内未打开过应用的设备,被视为应用已被卸载。

请求方法

POST :https://数据中心域名/push/custom.json

频率限制: 每天(自然日)限发送 100 次,每小时最多发送 20 次。如需要调整发送频率,可联系销售咨询,电话 13161856839。

签名规则: 所有服务端 API 请求均需要进行规则校验,详见 API 请求签名

正文参数

HTTP 请求正文数据格式为 application/json,包含具有以下结构的 JSON 对象:

提示

audience 字段使用须知

  • 如果 audience 中指定了 is_to_alltrue,则忽略其他推送条件(tagtag_orpackageName)。
  • audiencetagtag_or 共存时,两个数组之间为逻辑与(AND)关系。
  • audience 中包含 packageName 时,packageNametagtag_or 为逻辑与(AND)关系。例如三者共存时关系为 tag AND tag_or AND packageName
  • audience 中包含 tagItemstagItems 包含有效数据时, 服务端不会使用 tagtag_or 字段传入的值。
参数类型必传说明
platformString[]目标平台(操作系统),可以为 iosandroid 其中一个或全部。全部填写时给给 Android、iOS 两个平台推送消息。
audienceObject推送条件。支持按用户 ID 推送,按用户标签推送(tagtag_ortagItems)、按应用包名推送(packageName)和按指定平台全部推送(is_to_all)。注意:如果推送条件中 is_to_alltrue,则忽略其他推送条件。
audience.useridString[]用户 ID 数组。如果 userid 有值,则 platformtagtagItems 均无效。如果 is_to_alltrue,则当前参数无效。每次发送时最多发送 1000 个用户。
audience.tagString[]用户标签数组,标签之间为 AND 关系。数组中最多包含 20 个标签。
audience.tag_orString[]用户标签数组,标签之间为 OR 关系。数组中最多包含 20 个标签。
audience.packageNameString应用包名。与 tagtag_or 为逻辑与(AND)关系。
audience.is_to_allBoolean是否按指定平台(操作系统)全部推送。true 表示全部推送,此时其他推送条件字段均无效。false 表示按其他推送条件进行推送。
audience.tagItemsArray of Objects在按用户标签推送场景下,可通过 tagItems 实现复杂与或非逻辑。在 tagItems 包含有效内容的情况下,tagtag_or 字段无效。详见下方 tagItems 结构说明
notificationObject按平台(操作系统)指定推送内容。
notification.titleString通知栏显示标题,最长不超过 50 个字符。
notification.alertString默认推送通知内容。
notification.iosObject设置 iOS 平台下的推送及附加信息。详见下方 notification.ios 结构说明
notification.androidObject设置 Android 平台下的推送及附加信息。详见下方 notification.android 结构说明
notification.androidObject设置 Android 平台下的推送及附加信息。详见下方 notification.android 结构说明
notification.harmonyOSObject设置鸿蒙平台下的推送及附加信息。详见下方 notification.harmonyOS 结构说明
  • audience.tagItems 结构说明

    参数类型必传说明
    tagsArray of strings用户标签数组。
    isNotBoolean是否对 tags 数组的运算结果进行非运算。默认为 false
    tagsOperatorStringtags 数组内标签之间的运算符。
    itemsOperatorStringtagItems 数组内当前 Object 与上一个 Object 之间的运算符。注意:首个 Object 内的 itemsOperator 未被使用,为无效字段。

    tagItems 运算优先级

    tagItems 节点之间由 itemsOperator 控制关系。tagItems 各个节点之间存在计算优先级关系。例如,tagItems 内存在四个节点,节点的 itemsOperator 分别为 and、or、and、or。第一个运算符 and 无效可忽略。那么这四个节点的计算逻辑为:(((1 or 2) and 3) or 4)。

  • notification.ios 结构说明

    参数类型必传说明
    titleString通知栏显示的推送标题,仅针对 iOS 平台,支持 iOS 8.2 及以上版本,参数在 ios 节点下设置,详细可参考“设置 iOS 推送标题请求示例”,此属性优先级高于 notification 下的 title。
    contentAvailableInt针对 iOS 平台,静默推送是 iOS7 之后推出的一种推送方式。 允许应用在收到通知后在后台运行一段代码,且能够马上执行。详情请查看知识库文档。1 表示为开启,0 表示为关闭,默认为 0
    badgeint应用角标,仅针对 iOS 平台;不填时,表示不改变角标数;为 0 或负数时,表示 App 角标上的数字清零;否则传相应数字表示把角标数改为指定的数字,最大不超过 9999,参数在 ios 节点下设置,详细可参考“设置 iOS 角标数 HTTP 请求示例”。
    thread-idStringiOS 平台通知栏分组 ID,相同的 thread-id 推送分一组,单组超过 5 条推送会折叠展示
    apns-collapse-idStringiOS 平台,从 iOS10 开始支持,设置后设备收到有相同 ID 的消息,会合并成一条
    categoryStringiOS 富文本推送的类型开发者自己定义,自己在 App 端进行解析判断,与 richMediaUri 一起使用,当设置 category 后,推送时默认携带 mutable-content 进行推送,属性值为 1。
    richMediaUriStringiOS 富文本推送内容的 URL,与 category 一起使用。
    interruption-levelString适用于 iOS 15 及之后的系统。取值为 passiveactive(默认),time-sensitive,或 critical,取值说明详见对应的 APNs 的 interruption-level 字段。在 iOS 15 及以上版本中,系统的 “定时推送摘要”、“专注模式” 都可能导致重要的推送通知(例如余额变化)无法及时被用户感知的情况,可考虑设置该字段。
    extrasJSONObject附加信息,如果开发者自己需要,可以自己在 App 端进行解析。
  • notification.android 结构说明

    参数类型必传说明
    honor.importanceString荣耀通知栏消息优先级,取值:
    • NORMAL(服务与通讯类消息)
    • LOW(咨询营销类消息)。若资讯营销类消息发送时带图片,图片不会展示。
    honor.imageString荣耀推送自定义通知栏消息右侧的大图标 URL,若不设置,则不展示通知栏右侧图标。
    • URL 使用的协议必须是 HTTPS 协议,取值样例:https://example.com/image.png
    • 图标文件须小于 512KB,图标建议规格大小:40dp x 40dp,弧角大小为 8dp。
      超出建议规格大小的图标会存在图片压缩或显示不全的情况。
    hw.channelIdString华为推送通知渠道的 ID。详见自定义通知渠道
    hw.importanceString华为推送通知栏消息优先级,取值 NORMAL、LOW,默认为 NORMAL 重要消息。
    hw.imageString华为推送自定义的通知栏消息右侧大图标 URL,如果不设置,则不展示通知栏右侧图标。URL 使用的协议必须是 HTTPS 协议,取值样例:https://example.com/image.png。图标文件须小于 512KB,图标建议规格大小:40dp x 40dp,弧角大小为 8dp,超出建议规格大小的图标会存在图片压缩或显示不全的情况。
    hw.categoryString华为推送通道的消息自分类标识,category 取值必须为大写字母,例如 IM。App 根据华为要求完成自分类权益申请申请特殊权限 后可传入该字段有效。详见华为推送官方文档消息分类标准。该字段优先级高于控制台为 App Key 下的应用标识配置的华为推送 Category。
    mi.channelIdString小米推送通知渠道的 ID。详见小米推送消息分类新规
    mi.large_icon_uriString小米推送自定义的通知栏消息右侧图标 URL,如果不设置,则不展示通知栏右侧图标。国内版仅 MIUI12 以上版本支持,以下版本均不支持;国际版支持。图片要求:大小120 * 120px,格式为 png 或者 jpg 格式。
    oppo.channelIdStringoppo 推送通知渠道的 ID。详见推送私信通道申请
    vivo.classificationStringVIVO 推送服务的消息类别。可选值 0(运营消息,默认值) 和 1(系统消息)。该参数对应 VIVO 推送服务的 classification 字段,见 VIVO 推送消息分类说明 。该字段优先级高于控制台为 App Key 下的应用标识配置的 VIVO 推送通道类型。
    vivo.categoryStringVIVO 推送服务的消息二级分类。例如 IM(即时消息)。该参数对应 VIVO 推送服务的 category 字段。详细的 category 取值请参见 VIVO 推送消息分类说明 。如果指定 category ,必须同时传入与当前二级分类匹配的 classification 字段的值(系统消息场景或运营消息场景)。请注意遵照 VIVO 官方要求,确保二级分类(category)取值属于 VIVO 系统消息场景或运营消息场景下允许发送的内容。该字段优先级高于控制台为 App Key 下的应用标识配置的 VIVO 推送 Category。
    fcm.channelIdStringGoogle FCM 推送通知渠道的 ID。应用程序必须先创建一个具有此频道 ID 的频道,然后才能收到具有此频道 ID 的任何通知。更多信息请参见 Android 官方文档
    fcm.collapse_keyStringGoogle FCM 推送中可以折叠的一组消息的标识符,以便在可以恢复传递时仅发送最后一条消息。
    fcm.imageUrlStringGoogle FCM 推送自定义的通知栏消息右侧图标 URL,如果不设置,则不展示通知栏右侧图标。
    • 图片的大小上限为 1MB。
    • 要求控制台 FCM 推送配置为证书通知消息方式
    extrasJSONObject附加信息,如果开发者自己需要,可以自己在 App 端进行解析。
  • notification.harmonyOS 结构说明

    参数类型必传说明
    alertString鸿蒙平台下推送消息内容,传入后默认的推送消息内容失效。
    ohos.categoryString鸿蒙系统场景化推送的通知消息类别。完成自分类权益申请后,用于标识通知消息类型,不同的通知消息类型影响消息展示和提醒方式。字段取值见请求提参数说明
    ohos.imageString通知右侧大图标URL,URL使用的协议必须是HTTPS协议,取值样例:https://example.com/image.png
    说明:支持图片格式为png、jpg、jpeg、bmp,图片长宽建议小于 128128 像素,若超过 49152 像素,则图片不展示。
    extrasJSONObject附加信息,如果开发者自己需要,可以自己在 App 端进行解析。

请求示例

  • 示例 1:按用户标签推送(同时使用 audience.tagaudience.tag_or

    POST /push/custom.json HTTP/1.1
    Host: api.rong-api.com
    App-Key: uwd1c0sxdlx2
    Nonce: 14314
    Timestamp: 1585127132438
    Signature: 890b422b75c1c5cb706e4f7921df1d94e69c17f4
    Content-Type: application/json

    {
    "platform":["ios","android"],
    "audience":{
    "tag":["女","年轻"],
    "tag_or":["北京","上海"],
    "is_to_all":false
    },
    "notification":{
    "title":"标题",
    "alert":"this is a push",
    "ios":
    {
    "thread-id":"223",
    "apns-collapse-id":"111",
    "extras": {"id": "1","name": "2"}
    },
    "android": {
    "hw":{
    "channelId":"NotificationKanong",
    "importance": "NORMAL",
    "image":"https://example.com/image.png"
    },
    "mi":{
    "channelId":"rongcloud_kanong",
    "large_icon_uri":"https://example.com/image.png"
    },
    "oppo":{
    "channelId":"rc_notification_id"
    },
    "vivo":{
    "classification":"0"
    },
    "extras": {"id": "1","name": "2"}
    },
    "harmonyOS": {
    "ohos":{
    "category":"IM",
    "image":"https://example.com/image.png"
    },
    "extras": {"id": "1","name": "2"}
    }
    }
    }
  • 示例 2:按用户标签推送(使用 audience.tagItems

    POST /push/custom.json HTTP/1.1
    Host: api.rong-api.com
    App-Key: uwd1c0sxdlx2
    Nonce: 14314
    Timestamp: 1585127132438
    Signature: 890b422b75c1c5cb706e4f7921df1d94e69c17f4
    Content-Type: application/json

    {
    "platform":["ios","android"],
    "audience":{
    "tagItems":[
    {
    "tags":[
    "guangdong",
    "hunan"
    ],
    "isNot":false,
    "tagsOperator":"OR",
    "itemsOperator":"OR"
    },
    {
    "tags":[
    "20200408"
    ],
    "isNot":true,
    "tagsOperator":"OR",
    "itemsOperator":"AND"
    },
    {
    "tags":[
    "male",
    "female"
    ],
    "isNot":false,
    "tagsOperator":"OR",
    "itemsOperator":"OR"
    }
    ],
    "userid":[
    "123",
    "456"
    ],
    "is_to_all":false
    }
    "notification":{
    "title":"标题",
    "alert":"this is a push",
    "ios":
    {
    "thread-id":"223",
    "apns-collapse-id":"111",
    "extras": {"id": "1","name": "2"}
    },
    "android": {
    "hw":{
    "channelId":"NotificationKanong",
    "importance": "NORMAL",
    "image":"https://example.com/image.png"
    },
    "mi":{
    "channelId":"rongcloud_kanong",
    "large_icon_uri":"https://example.com/image.png"
    },
    "oppo":{
    "channelId":"rc_notification_id"
    },
    "vivo":{
    "classification":"0"
    },
    "extras": {"id": "1","name": "2"}
    },
    "harmonyOS": {
    "ohos":{
    "category":"IM",
    "image":"https://example.com/image.png"
    },
    "extras": {"id": "1","name": "2"}
    }
    }
    }

返回结果

HTTP 响应正文包含具有以下结构的 JSON 对象:

返回值返回类型说明
codeInt返回码,200 为正常。
idString推送唯一标识。

返回结果示例

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{"code":200,"id":"BRBL-IQ6N-80CO-D5U5"}

获取推送聚合统计数据

提示

生产环境下,需要在控制台开通推送 Plus 版本后才能使用。

查询某天应用全量推送数据统计,最多可查询 30 天内的推送数据,当天数据次日支持查询。

推送聚合统计数据也可以在控制台-数据统计中查看。 ​

请求方法

GEThttp://api.developer.rongcloud.cn/stat/getDayPushData?date={date}

签名规则:所有服务端 API 请求均需要进行规则校验,详见 API 请求签名

频率限制: 每秒钟限 1 次

路径参数

参数类型必传说明
dateString查询日期,非必填,默认查询昨天的推送统计数据,最多支持查询 30 天内的数据情况,如:20210811

请求示例

每次请求 API 接口时,均需要提供 4 个 HTTP Request Header。详见 API 请求签名

GET http://api.developer.rongcloud.cn/stat/getDayPushData?date=20210802 HTTP/1.1
App-Key: e0x9wycfev2lq
Nonce: 66583
Timestamp: 1629275060000
Signature: af590f4963f24e2d862b5f82d2170320e39c5477

返回结果

HTTP 响应正文包含具有以下结构的 JSON 对象:

返回值返回类型说明
codeInt返回码,2000 为正常。
dataString按推送平台,返回的推送统计数据,支持平台包括:IM、HW、OPPO、VIVO、MEIZU、FCM、APNs、RongPush(即时通讯自建推送)
allcntInt单日推送总量
succcntInt单日推送成功总量
arrcntInt单日推送成功到达设备总量,华为、魅族平台的推送到达数,需要到厂商平台设置后,才能支持。FCM 暂不支持推送到达数据统计
opencntInt单日推送通知栏点击总量,受厂商平台限制 OPPO 平台不支持推送点击数据统计。FCM 暂不支持推送点击数据统计
failcntInt单日推送失败总量

返回结果示例

{
"code": 2000,
"msg": "success",
"data": {
"MI": {
"allcnt": 1400,
"succcnt": 840,
"arrcnt": 740,
"opencnt": 140,
"failcnt": 241
},
"HW": {
"allcnt": 1400,
"succcnt": 840,
"arrcnt": 740,
"opencnt": 140,
"failcnt": 241
},
"OPPO": {
"allcnt": 1400,
"succcnt": 840,
"arrcnt": 740,
"opencnt": 140,
"failcnt": 0
},
"VIVO": {
"allcnt": 1400,
"succcnt": 840,
"arrcnt": 740,
"opencnt": 140,
"failcnt": 241
},
"MEIZU": {
"allcnt": 1400,
"succcnt": 840,
"arrcnt": 740,
"opencnt": 140,
"failcnt": 241
},
"FCM": {
"allcnt": 1400,
"succcnt": 840,
"arrcnt": 0,
"opencnt": 0,
"failcnt": 241
},
"RongPush": {
"allcnt": 1400,
"succcnt": 840,
"arrcnt": 740,
"opencnt": 140,
"failcnt": 241
},
"APNs": {
"allcnt": 1400,
"succcnt": 840,
"arrcnt": 740,
"opencnt": 140,
"failcnt": 241
}
}
}

获取单次推送统计数据

提示

生产环境下,需要在控制台开通推送 Plus 版本后才能使用。

针对每一次推送,可统计到推送 3 天内的推送到达、点击数据变化情况,如 1 号推送一条消息,2、3 号仍然可以查询到 1 号推送的数据,当日推送数据次日支持查询。

根据推送 ID 查询不落地推送统计,支持通过 /push/custom.json 接口的推送统计查询。

单次推送统计数据也可以在控制台-数据统计中查看。

请求方法

GEThttp://api.developer.rongcloud.cn/stat/getPushIdData?push_id={push_id}

签名规则:所有服务端 API 请求均需要进行规则校验,详见 API 请求签名

频率限制: 每秒钟限 1 次

路径参数

参数类型必传说明
push_idString推送唯一标识,调用 /push/custom.json 接口后返回

请求示例

每次请求 API 接口时,均需要提供 4 个 HTTP Request Header。详见 API 请求签名

GET http://api.developer.rongcloud.cn/stat/getPushIdData?push_id=BR17-PG4T-G3OO-D5U5 HTTP/1.1
App-Key: e0x9wycfev2lq
Nonce: 49166
Timestamp: 1629275088000
Signature: 566e194c1cc2e1ac7d2b30c8b531bc54baf26d6e

返回结果

HTTP 响应正文包含具有以下结构的 JSON 对象:

返回值返回类型说明
codeInt返回码,2000 为正常。
dataString按推送平台,返回的推送统计数据,平台包括:IM、HW、OPPO、VIVO、MEIZU、FCM、APNs、RongPush(即时通讯自建推送)
allcntInt单日推送总量
succcntInt单日推送成功总量
arrcntInt单日推送成功到达设备总量,华为、魅族平台的推送到达数,需要到厂商平台设置后,才能支持。FCM 暂不支持推送到达数据统计
opencntInt单日推送通知栏点击总量,受厂商平台限制 OPPO 平台不支持推送点击数据统计。FCM 暂不支持推送点击数据统计
failcntInt单日推送失败总量

返回结果示例

{
"code": 2000,
"msg": "success",
"data": {
"MI": {
"allcnt": 1400,
"succcnt": 840,
"arrcnt": 740,
"opencnt": 140,
"failcnt": 241
},
"HW": {
"allcnt": 1400,
"succcnt": 840,
"arrcnt": 740,
"opencnt": 140,
"failcnt": 241
},
"OPPO": {
"allcnt": 1400,
"succcnt": 840,
"arrcnt": 740,
"opencnt": 140,
"failcnt": 0
},
"VIVO": {
"allcnt": 1400,
"succcnt": 840,
"arrcnt": 740,
"opencnt": 140,
"failcnt": 241
},
"MEIZU": {
"allcnt": 1400,
"succcnt": 840,
"arrcnt": 740,
"opencnt": 140,
"failcnt": 241
},
"FCM": {
"allcnt": 1400,
"succcnt": 840,
"arrcnt": 0,
"opencnt": 0,
"failcnt": 241
},
"RongPush": {
"allcnt": 1400,
"succcnt": 840,
"arrcnt": 740,
"opencnt": 140,
"failcnt": 241
},
"APNs": {
"allcnt": 1400,
"succcnt": 840,
"arrcnt": 740,
"opencnt": 140,
"failcnt": 241
}
}
}

按应用版本定义推送内容

即时通讯服务端支持按客户端 SDK 上报的 App 版本定义消息推送通知中的内容。开通推送 Plus后可使用该功能。

提示
  • 您需要调用客户端 SDK 接口主动上报 App 版本。要求 Android / iOS 客户端 SDK 版本大于等于 5.2.2。
  • 当前仅支持根据 App 版本订制自定义消息类型的推送通知,不支持即时通讯服务预定义的消息类型。

通过 SDK 将 App 版本信息上报至即时通讯服务后,您可以订制不同版本的 App 所接收的消息推送通知的内容(pushContent)。例如,给低版本 App 的用户订制消息推送通知时,可在推送通知中提示“需要升级 App 才能解析新消息类型”。该功能也可用于按 App 版本、平台、消息类型(仅支持自定义消息类型)订制个性化的推送通知内容。

创建规则

您需要在控制台按版本号推送消息页面创建按 App 版本号推送规则。一条规则仅适用于一个客户端操作系统(Android/iOS),仅包含一个自定义消息类型的标识,可包含多个 App 的版本号。

规则具体包含以下字段:

  • 规则名称:填写规则名称。
  • 消息标识:填写消息类型的唯一标识,一条规则仅支持填写一个标识。仅支持自定义消息类型的标识。不支持内置消息类型(消息类型概述)。
  • Push 消息内容:自定义的推送内容(pushContent)。
  • 平台:Android 或 iOS。
  • 涉及版本号:填写由客户端 SDK 上报的 App 版本号。

开启、关闭服务在设置完成后30分钟后生效。

上报 App 版本号

该功能依赖由客户端手动上报的应用程序版本号(要求 SDK 版本 ≧ 5.2.2)。在 SDK 完成初始化之后,您需要调用 SDK 接口主动上报 App 版本。即时通讯服务端获取规则与客户端 App 版本号后,一旦有符合规则的离线消息触发推送,服务端将替换远程推送通知中的内容为规则中指定的 Push 消息内容

  • Android:

    RongIMClient.getInstance().setAppVer(appVersion);
  • iOS

    [[RCIMClient sharedRCIMClient] setAppVer:app_Version];

注意 App 版本号不可为空,长度小于 20。例如 1.1.0