发送指定用户不落地通知
App 业务端可以向指定用户发送「推送通知」,本质上是直接通过第三方或即时通讯服务自建的推送通道向 App 用户推送一条通知。该功能只触发推送,不发送消息,不产生会话,称为「单个用户不落地通知」。
- 只能通过即时通讯服务端 API 进行发送。单次最多同时向 100 人发送推送。
- 「推送通知」的所有内容仅展现在通知栏。无论客户端 App 是否在前台,始终以通知形式展示在系统通知栏中。该功能不发送消息,不产生会话,因此用户无法在任何聊天会话中看到不落地通知的内容。
- 客户端不会存储不落地通知。
- 始终使用推送通道,因此不受客户端与即时通讯服务端之间的连接状态的影响。即使客户端不在前台、不在线(例如 App 被杀死),只要可正常接收推送,就可以收到不落地通知。
提示
- 即时通讯服务将 30 天内连接过 IM 服务的设备作为推送的目标。30 天内未打开过应用的设备,被视为应用已被卸载。
- 如果客户端设备不允许推送(断开连接时设置不允许推送),或遇到其他原因导致推送失败,则无法接收到不落地通知。
请求方法
POST: https://数据中心域名/push/user.json
频率限制: 每秒钟限推送 100 条消息,每次最多同时向 100 人发送,如:一次发送 100 人时,视为 100 条消息。
签名规则: 所有服务端 API 请求均需要进行规则校验,详见 API 请求签名。
正文参数
HTTP 请求正文数据格式为 application/json
,包含具有以下结构的 JSON 对象:
参数 | 类型 | 必传 | 说明 |
---|---|---|---|
userIds | String[] | 是 | 用户 ID,每次发送时最多发送 100 个用户。 |
notification | Object | 是 | 按操作系统类型推送消息内容。 |
notification.title | String | 否 | 通知栏显示标题,最长不超过 50 个字符。 |
notification.pushContent | String | 是 | 推送消息内容。 |
notification.ios | Object | 否 | 设置 iOS 平台下的推送及附加信息,详见 ios 结构说明。 |
notification.android | Object | 否 | 设置 Android 平台下的推送及附加信息,详见 android 结构说明。 |
notification.harmonyOS | Object | 否 | 设置鸿蒙平台下的推送及附加信息。详见下方 harmonyOS 结构说明。 |
-
notification.ios
结构说明:参数 类型 必传 说明 contentAvailable Int 否 针对 iOS 平台,静默推送是 iOS7 之后推出的一种推送方式。 允许应用在收到通知后在后台运行一段代码,且能够马上执行。详情请查看知识库文档。1 表示为开启,0 表示为关闭,默认为 0 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
结构说明参数 类型 必传 说明 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。详见推送私信通道申请。 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/user.json HTTP/1.1
Host: api.rong-api.com
App-Key: uwd1c0sxdlx2
Nonce: 14314
Timestamp: 1585127132438
Signature: 890b422b75c1c5cb706e4f7921df1d94e69c17f4
Content-Type: application/json
{
"userIds":["123","456"],
"notification":{
"title":"标题",
"pushContent":"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 对象:
返回值 | 返回类型 | 说明 |
---|---|---|
code | Int | 返回码,200 为正常。 |
返回结果示例
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{"code":200}