发送应用包名通知
App 用户可以向 App 下指定应用包名的全部用户发送系统会话消息,该功能称为「应用包名通知」。
例如,客户通过控制台创建了一个应用,该应用下有两个客户端:学生端、教师端(通过创建两个应用包名实现),当需要给所有使用学生端或教师端的用户发送运营消息时,可使用此功能接口实现。
该功能使用 /push.json
接口。
- 支持发送即时通讯服务预定义的消息类型(见消息类型概述)。消息的类型(
objectName
字段)决定了消息是否支持离线推送通知,以及客户端在收到该消息后,是否展示在聊天界面、会话列表,是否存入本地数据库。 - 支持发送客户自定义类型的消息。客户端在收到自定义消息后,是否展示在聊天界面、会话列表,是否存入本地数据库取决于客户端注册的自定义消息类型定义。
- 只能通过即时通讯服务端 API 进行发送,会话类型为 SYSTEM。该类型的会话不支持终端用户在收到消息后进行回复。
假设发送一条文本消息(objectName
为 RC:TxtMsg
,属于客户端 SDK 会存储的内置消息类型,且可触发离线推送),效果如下:
- 客户端如果在线,会即时收到一条消息,所在会话的 Target ID 为调用接口时传入的
fromUserId
,会话类型为系统会话(类型为 SYSTEM)。 - 客户端如果离线,消息会触发服务端远程推送,客户端如已集成并启用推送服务,则会收到推送通知。
Web 端用户不支持此功能,终端用户收到系统消息后,不支持消息回复功能。
开通服务
使用应用包名通知功能前,请确认已为当前 App Key 开通相关服务。详见全量用户通知服务配置。
如未开通服务,Server API 将返回 1009
错误。注意,在未开通服务时,如果连续请求导致 API 请求频率超过限制,Server API 会返回 HTTP 429 Too Many Requests 错误(错误码为 1008
)。
请求方法
POST: https://数据中心域名/push.json
频率限制:共享 /push.json
的限频配额,即每小时限发送 2 次,每天(自然日)最多发送 3 次。即时通讯服务端按应用包名推送的处理能力为每秒钟 2000 条,即每秒钟可以向 2000 个目标用户下发消息。
签名规则: 所有服务端 API 请求均需要进行规则校验,详见 API 请求签名。
正文参数
HTTP 请求正文数 据格式为 application/json
,包含具有以下结构的 JSON 对象:
参数 | 类型 | 必传 | 说明 |
---|---|---|---|
platform | String[] | 是 | 目标操作系统,iOS、Android 最少传递一个。如果需要给两个系统推送消息时,则需要全部填写,发送时如目标用户在 Web 端登录也会收到此条消息。 |
fromuserid | String | 是 | 发送人用户 ID。 注意:发送消息所使用的用户 ID 必须已获取过用户 Token,否则消息一旦触发离线推送,通知内无法正确显示发送者的用户信息。 |
audience | String | 是 | 推送条件。使用「应用包名用户通知」时,请设置为 packageName 。 |
audience.tag | String[] | 否 | 用户标签,每次发送时最多发送 20 个标签,标签之间为 AND 的关系,is_to_all 为 true 时参数无效。 |
audience.tag_or | String[] | 否 | 用户标签,每次发送时最多发送 20 个标签,标签之间为 OR 的关系,is_to_all 为 true 时参数无效,tag_or 同 tag 参数可以同时存在。 |
audience.userid | String[] | 否 | 用户 ID,每次发送时最多发送 1000 个用户,如果 tag 和 userid 两个条件同时存在时,则以 userid 为准,如果 userid 有值时,则 platform 参数无效,is_to_all 为 true 时参数无效。 |
audience.packageName | String | 否 | 应用包名,is_to_all 为 true 时,此参数无效。与 tag、tag_or 同时存在时为 And 的关系,向同时满足条件的用户推送。与 userid 条件同时存在时,以 userid 为准进行推送。 |
audience.is_to_all | Boolean | 是 | 是否全部推送,false 表示按 tag 、tag_or 或 userid 条件推送,true 表示向所有用户推送,tag、tag_or 和 userid 条件无效。 |
message.content | String | 是 | 所发送消息的内容,单条消息最大 128k。
|
message.objectName | String | 是 | 消息类型,接受内置消息类型(见消息类型概述)或自定义消息的消息类型值。 注意:在自定义消息时,消息类型不可以 “RC:” 开头,以免与系统内置消息类型重名;消息类型长度不可超过 32 个字符。SDK 中必须已注册过该自定义消息,否则 SDK 收到该消息后将无法解析。 |
notification | Object | 是 | 按操作系统类型推送通知内容,如 platform 中设置了给 iOS 和 Android 系统推送消息,而在 notification 中只设置了 iOS 的推送内容,则 Android 的推送内容为最初 alert 设置的内容。 |
notification.title | String | 否 | 通知栏显示标题,最长不超过 50 个字符。 |
notification.forceShowPushContent | Int | 否 | 是否越过客户端配置,强制在推送通知内显示通知内容(pushContent )。默认值 0 表示不强制,1 表示强制。说明:客户端设备可设置在接收推送通知时仅显示类似「您收到了一条通知」的提醒。从服务端发送消息时,可通过设置 forceShowPushContent 为 1 越过该配置,强制客户端针在此条消息的推送通知中显示推送内容。 |
notification.alert | String | 否 | 推送通知内容。注意,如果此处 notification.alert 不传,则必须在 notification.ios.alert 和 notification.android.alert 分别指定 iOS 和 Android 下的推送通知内容,否则无法正常推送。一旦指定了各平台推送内容,则推送内容以对应平台系统的 alert 为准。如果都不填写,则无法发起推送。 |
notification.ios | Object | 否 | 设置 iOS 平台下的推送及附加信息。详细查看 ios 参数结构说明。 |
notification.android | Object | 否 | 设置 Android 平台下的推送及附加信息。详细查看 android 参数结构说明。 |
notification.harmonyOS | Object | 否 | 设置鸿蒙平台下的推送及附加信息。详见下方 harmonyOS 结构说明。 |
-
notification.ios
参数结构说明参数 类型 必传 说明 title String 否 通知栏显示的推送标题,仅针对 iOS 平台,支持 iOS 8.2 及以上版本。该属性优先级高于 notification.title
。contentAvailable Int 否 针对 iOS 平台,静默推送是 iOS7 之后推出的一种推送方式。 允许应用在收到通知后在后台运行一段代码,且能够马上执行。详情请查看知识库文档。1 表示为开启,0 表示为关闭,默认为 0 alert String 否 推送通知内容,传入后默认的推送通知内容失效。 badge int 否 应用角标,仅针对 iOS 平台;不填时,表示不改变角标数;为 0 或负数时,表示 App 角标上的数字清零;否则传相应数字表示把角标数改为指定的数字,最大不超过 9999,参数在 ios
节点下设置,详细可参考“设置 iOS 角标数 HTTP 请求示例”。thread-id String 否 iOS 平台通知栏分组 ID,相同的 thread-id 推送分一组,单组超过 5 条推送会折叠展示 apns-collapse-id String 否 iOS 平台,从 iOS10 开始支持,设置后设备收到有相同 ID 的消息,会合并成一条 category String 否 iOS 富文本推送的类型开发者自己定义,自己在 App 端进行解 析判断,与 richMediaUri 一起使用,当设置 category 后,推送时默认携带 mutable-content 进行推送,属性值为 1。 richMediaUri String 否 iOS 富文本推送内容的 URL,与 category 一起使用。 interruption-level String 否 适用于 iOS 15 及之后的系统。取值为 passive
,active
(默认),time-sensitive
,或critical
,取值说明详见对应的 APNs 的 interruption-level 字段。在 iOS 15 及以上版本中,系统的 “定时推送摘要”、“专注模式” 都可能导致重要的推送通知(例如余额变化)无法及时被用户感知的情况,可考虑设置该字段。extras JSONObject 否 附加信息,如果开发者自己需要,可以自己在 App 端进行解析。 notification.android
结构说明
参数 类型 必传 说明 alert String 否 Android 平台下推送通知内容,传入后默认的推送通知内容失效。 honor.importance String 否 荣耀通知栏消息优先级,取值: - NORMAL(服务与通讯类消息)
- LOW(咨询营销类消息)。若资讯营销类消息发送时带图片,图片不会展示。
honor.image String 否 荣耀推送自定义通知栏消息右侧的大图标 URL,若不设置,则不展示通知栏右侧图标。 - URL 使用的协议必须是 HTTPS 协议,取值样例:
https://example.com/image.png
。 - 图标文件须小于 512KB,图标建议规格大小:40dp x 40dp,弧角大小为 8dp。
超出建议规格大小的图标会存在图片压缩或显示不全的情况。
hw.channelId String 否 华为推送通知渠道的 ID。详见自定义通知渠道。 hw.importance String 否 华为推送通知栏消息优先级,取值 NORMAL、LOW,默认为 NORMAL 重要消息。 hw.image String 否 华为推送自定义的通知栏消息右侧大图标 URL,如果不设置,则不展示通知栏右侧图标。URL 使用的协议必须是 HTTPS 协议,取值样例: https://example.com/image.png
。图标文件须小于 512KB,图标建议规格大小:40dp x 40dp,弧角大小为 8dp,超出建议规格大小的图标会存在图片压缩或显示不全 的情况。hw.category String 否 华为推送通道的消息自分类标识,category 取值必须为大写字母,例如 IM
。App 根据华为要求完成自分类权益申请 或 申请特殊权限 后可传入该字段有效。详见华为推送官方文档消息分类标准。该字段优先级高于控制台为 App Key 下的应用标识配置的华为推送 Category。mi.channelId String 否 小米推送通知渠道的 ID。详见小米推送消息分类新规。 mi.large_icon_uri String 否 小米推送自定义的通知栏消息右侧图标 URL,如果不设置,则不展示通知栏右侧图标。国内版仅 MIUI12 以上版本支持,以下版本均不支持;国际版支持。图片要求:大小120 * 120px,格式为 png 或者 jpg 格式。 oppo.channelId String 否 oppo 推送通知渠道的 ID。详 见推送私信通道申请。 oppo.category String 否 推送内容分类。详见OPUSH消息分类细则。 oppo.notify_level Number 否 通知提醒类型,1 通知栏、2 通知栏+锁屏、16 通知栏+锁屏+横幅+震动+铃声;设置 category 后此字段有效。详见OPUSH消息分类细则。 vivo.classification String 否 VIVO 推送服务的消息类别。可选值 0
(运营消息,默认值) 和1
(系统消息)。该参数对应 VIVO 推送服务的classification
字段,见 VIVO 推送消息分类说明 。该字段优先级高于控制台为 App Key 下的应用标识配置的 VIVO 推送通道类型。vivo.category String 否 VIVO 推送服务的消息二级分类。例如 IM
(即时消息)。该参数对应 VIVO 推送服务的category
字段。详细的 category 取值请参见 VIVO 推送消息分类说明 。 如果指定category
,必须同时传入与当前二级分类匹配的classification
字段的值(系统消息场景或运营消息场景)。请注意遵照 VIVO 官方要求,确保二级分类(category
)取值属于 VIVO 系统消息场景或运营消息场景下允许发送的内容。该字段优先级高于控制台为 App Key 下的应用标识配置的 VIVO 推送 Category。fcm.channelId String 否 Google FCM 推送通知渠道的 ID。应用程序必须先创建一个具有此频道 ID 的频道,然后才能收到具有此频道 ID 的任何通知。更多信息请参见 Android 官方文档。 fcm.collapse_key String 否 Google FCM 推送中可以折叠的一组消息的标识符,以便在可以恢复传递时仅发送最后一条消息。 fcm.imageUrl String 否 Google FCM 推送自定义的通知栏消息右侧图标 URL,如果不设置,则不展示通知栏右侧图标。 - 图片的大小上限为 1MB。
- 要求控制台 FCM 推送配置为证书与通知消息方式。
extras JSONObject 否 附加信息,如果开发者自己需要,可以自己在 App 端进行解析。 -
notification.harmonyOS
结构说明参数 类型 必传 说明 alert String 否 鸿蒙平台下推送消息内容,传入后默认的推送消息内容失效。 ohos.category String 否 鸿蒙系统场景化推送的通知消息类别。完成自分类权益申请后,用于标识通知消息类型,不同的通知消息类型影响消息展示和提醒方式。字段取值见请求提参数说明。 ohos.image String 否 通知右侧大图标URL,URL使用的协议必须是HTTPS协议,取值样例: https://example.com/image.png
。
说明:支持图片格式为png、jpg、jpeg、bmp,图片长宽建议小于 128128 像素,若超过 49152 像素,则图片不展示。extras JSONObject 否 附加信息,如果开发者自己需要,可以自己在 App 端进行解析。
请求示例
POST /push.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"],
"fromuserid": "fromuseId1",
"audience":{
"packageName":"xxx.rong.xxx",
"is_to_all":false
},
"message": {
"content": "{\"content\":\"1111\",\"extra\":\"aa\"}",
"objectName": "RC:TxtMsg"
},
"notification":{
"title":"标题",
"forceShowPushContent":0,
"alert":"this is a push",
"ios":
{
"alert": "override alert",
"thread-id":"223",
"apns-collapse-id":"111",
"extras": {"id": "1","name": "2"}
},
"android": {
"alert": "override alert",
"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",
"category": "IM",
"notify_level": 2
},
"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 对象:
返回值 | 返回类型 | 说明 |
---|---|---|
code | Number | 返回码,200 为正常。 |
id | String | 推送唯一标识,和 messageUID 一致。 |
messageUID | String | 返回消息 ID。 |
返回结果示例
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"code": 200,
"id": "XXXX-JJJJ-KKK-LLLL",
"messageUID": "XXXX-JJJJ-KKK-LLLL"
}