跳到主要内容

发送全量用户不落地通知

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

该功能使用 /push.json 接口。

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

开通服务​

使用全量用户不落地通知功能前，请确认已为当前 App Key 开通相关服务。详见全量用户通知服务配置。

如未开通服务，Server API 将返回 1009 错误。注意，在未开通服务时，如果连续请求导致 API 请求频率超过限制，Server API 会返回 HTTP 429 Too Many Requests 错误（错误码为 1008）。

请求方法​

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

频率限制： 共享 /push.json 的限频配额，即每小时限发送 2 次，每天（自然日）最多发送 3 次。

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

正文参数​

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

参数类型必传说明
platformString[]是目标操作系统，iOS、Android 最少传递一个。如果需要给两个系统推送消息时，则需要全部填写。
audienceObject是推送条件，包括：tag、userid 、packageName 、 is_to_all。
audience.tagString[]否用户标签。每次发送时最多发送 20 个标签，标签之间为 AND 的关系，is_to_all 为 true 时参数无效。
audience.tag_orString[]否用户标签。每次发送时最多发送 20 个标签，标签之间为 OR 的关系，is_to_all 为 true 时参数无效，tag_or 同 tag 参数可以同时存在。
audience.useridString[]否用户 ID，每次发送时最多发送 1000 个用户，如果 tag 和 userid 两个条件同时存在时，则以 userid 为准，如果 userid 有值时，则 platform 参数无效，is_to_all为 true 时参数无效。
audience.packageNameString否应用包名，is_to_all 为 true 时，此参数无效。与 tag、tag_or 同时存在时为 And 的关系，向同时满足条件的用户推送。与 userid 条件同时存在时，以 userid 为准进行推送。
audience.is_to_allBoolean是是否全部推送，false 表示按 tag 、tag_or 或 userid 条件推送，true 表示向所有用户推送，tag、tag_or 和 userid 条件无效。
notificationObject是按操作系统类型推送消息内容，如 platform 中设置了给 iOS 和 Android 系统推送消息，而在 notification 中只设置了 iOS 的推送内容，则 Android 的推送内容为最初 alert 设置的内容，详细查看 notification 参数结构说明。
notification.titleString否通知栏显示标题，最长不超过 50 个字符。
notification.forceShowPushContentInt否是否越过客户端配置，强制在推送通知内显示通知内容（pushContent）。默认值 0 表示不强制，1 表示强制。

说明：客户端设备可设置在接收推送通知时仅显示类似「您收到了一条通知」的提醒。从服务端发送消息时，可通过设置forceShowPushContent 为 1 越过该配置，强制客户端针在此条消息的推送通知中显示推送内容。
notification.alertString否默认推送通知内容。如填写了 iOS 或 Android 下的 alert 时，则推送内容以对应平台系统的 alert 为准。
notification.iosObject否设置 iOS 平台下的推送及附加信息。详细查看 ios 参数结构说明。
notification.androidObject否设置 Android 平台下的推送及附加信息。详细查看 android 参数结构说明。
notification.harmonyOSObject否设置鸿蒙平台下的推送及附加信息。详见下方 harmonyOS 结构说明。

  • notification.ios 参数结构说明

    参数类型必传说明
    titleString否通知栏显示的推送标题，仅针对 iOS 平台，支持 iOS 8.2 及以上版本。该属性优先级高于 notification.title。
    contentAvailableInt否针对 iOS 平台，静默推送是 iOS7 之后推出的一种推送方式。 允许应用在收到通知后在后台运行一段代码，且能够马上执行。详情请查看知识库文档。1 表示为开启，0 表示为关闭，默认为 0
    alertString否推送消息内容，传入后默认的推送消息内容失效，不能为空。
    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 结构说明

    参数类型必传说明
    alertString否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.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":["北京","上海"],
    "userid":["123","456"],
    "is_to_all":true
  },
  "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"
        },
        "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 对象：

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

返回结果示例​

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

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