跳到主要内容

发送指定用户不落地通知

App 业务端可以向指定用户发送「推送通知」，本质上是直接通过第三方或即时通讯服务自建的推送通道向 App 用户推送一条通知。该功能只触发推送，不发送消息，不产生会话，称为「单个用户不落地通知」。

  • 只能通过即时通讯服务端 API 进行发送。单次最多同时向 100 人发送推送。
  • 「推送通知」的所有内容仅展现在通知栏。无论客户端 App 是否在前台，始终以通知形式展示在系统通知栏中。该功能不发送消息，不产生会话，因此用户无法在任何聊天会话中看到不落地通知的内容。
  • 客户端不会存储不落地通知。
  • 始终使用推送通道，因此不受客户端与即时通讯服务端之间的连接状态的影响。即使客户端不在前台、不在线（例如 App 被杀死），只要可正常接收推送，就可以收到不落地通知。
提示
  • 即时通讯服务将 30 天内连接过 IM 服务的设备作为推送的目标。30 天内未打开过应用的设备，被视为应用已被卸载。
  • 如果客户端设备不允许推送（断开连接时设置不允许推送），或遇到其他原因导致推送失败，则无法接收到不落地通知。

请求方法​

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

频率限制： 每秒钟限推送 100 条消息，每次最多同时向 100 人发送，如：一次发送 100 人时，视为 100 条消息。

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

正文参数​

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

参数类型必传说明
userIdsString[]是用户 ID，每次发送时最多发送 100 个用户。
notificationObject是按操作系统类型推送消息内容。
notification.titleString否通知栏显示标题，最长不超过 50 个字符。
notification.pushContentString是推送消息内容。
notification.iosObject否设置 iOS 平台下的推送及附加信息，详见 ios 结构说明。
notification.androidObject否设置 Android 平台下的推送及附加信息，详见 android 结构说明。
notification.harmonyOSObject否设置鸿蒙平台下的推送及附加信息。详见下方 harmonyOS 结构说明。

  • notification.ios 结构说明：

    参数类型必传说明
    contentAvailableInt否针对 iOS 平台，静默推送是 iOS7 之后推出的一种推送方式。 允许应用在收到通知后在后台运行一段代码，且能够马上执行。详情请查看知识库文档。1 表示为开启，0 表示为关闭，默认为 0
    badgeint否应用角标，仅针对 iOS 平台；不填时，表示不改变角标数；为 0 或负数时，表示 App 角标上的数字清零；否则传相应数字表示把角标数改为指定的数字，最大不超过 9999，参数在 ios 节点下设置，详细可参考“设置 iOS 角标数 HTTP 请求示例”。
    thread-idString否iOS 平台通知栏分组 ID，相同的 thread-id 推送分一组，单组超过 5 条推送会折叠展示
    apns-collapse-idString否iOS 平台，从 iOS10 开始支持，设置后设备收到有相同 ID 的消息，会合并成一条
    categoryString否iOS 富文本推送的类型开发者自己定义，自己在 App 端进行解析判断，与 richMediaUri 一起使用，当设置 category 后，推送时默认携带 mutable-content 进行推送，属性值为 1。
    richMediaUriString否iOS 富文本推送内容的 URL，与 category 一起使用。
    interruption-levelString否适用于 iOS 15 及之后的系统。取值为 passive，active（默认），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.channelIdString否oppo 推送通知渠道的 ID。详见推送私信通道申请。
    vivo.classificationString否VIVO 推送服务的消息类别。可选值 0（运营消息，默认值） 和 1（系统消息）。该参数对应 VIVO 推送服务的 classification 字段，见 VIVO 推送消息分类说明 。该字段优先级高于控制台为 App Key 下的应用标识配置的 VIVO 推送通道类型。
    vivo.categoryString否VIVO 推送服务的消息二级分类。例如 IM（即时消息）。该参数对应 VIVO 推送服务的 category 字段。详细的 category 取值请参见 VIVO 推送消息分类说明 。如果指定 category ，必须同时传入与当前二级分类匹配的 classification 字段的值（系统消息场景或运营消息场景）。请注意遵照 VIVO 官方要求，确保二级分类（category）取值属于 VIVO 系统消息场景或运营消息场景下允许发送的内容。该字段优先级高于控制台为 App Key 下的应用标识配置的 VIVO 推送 Category。
    fcm.channelIdString否Google FCM 推送通知渠道的 ID。应用程序必须先创建一个具有此频道 ID 的频道，然后才能收到具有此频道 ID 的任何通知。更多信息请参见 Android 官方文档。
    fcm.collapse_keyString否Google FCM 推送中可以折叠的一组消息的标识符，以便在可以恢复传递时仅发送最后一条消息。
    fcm.imageUrlString否Google 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 端进行解析。

请求示例​

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 对象：

返回值返回类型说明
codeInt返回码，200 为正常。

返回结果示例​

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

{"code":200}
编辑此页
最后由 zhangkailiang 于 更新