文档中心 SDK下载 Demo下载 合规指南 开发者社区
极光文档 > 极光推送 > REST API > 推送 API > 创建推送 API
极光文档 > 极光推送 > REST API > 推送 API > 创建推送 API
推送 API
最近更新：2022-08-16
展开全部

推送 API

向某单个设备或者某设备列表推送一条通知、或者消息。
推送的内容只能是 JSON 表示的一个推送对象。

这是 Push API 最近的版本。

相比于 API v2 版本，v3 版本的改进为：

  • 完全基于 https 且支持 http2，不再提供 http 访问；
  • 使用 HTTP Basic Authentication 的方式做访问授权。这样整个 API 请求可以使用常见的 HTTP 工具来完成，比如：curl，浏览器插件等；
  • 推送内容完全使用 JSON 的格式；
  • 支持的功能有所改进：支持多 tag 的与或操作；可单独发送通知或者自定义消息，也可同时推送通知与自定义消息；windows phone 目前只有通知。

调用地址

https://api.jpush.cn/v3/push

调用验证

详情参见 REST API 概述的 鉴权方式 说明。

请求示例

请求头

> POST /v3/push HTTP/1.1 > Authorization: Basic N2Q0MzFlNDJkZmE2YTZkNjkzYWMyZDA0OjVlOTg3YWM2ZDJlMDRkOTVhOWQ4ZjBkMQ==
          > POST /v3/push HTTP/1.1
> Authorization: Basic N2Q0MzFlNDJkZmE2YTZkNjkzYWMyZDA0OjVlOTg3YWM2ZDJlMDRkOTVhOWQ4ZjBkMQ==
此代码块在浮窗中显示

请求体

{ "platform": "all", "audience": { "tag": [ "深圳", "北京" ] }, "notification": { "alert": "Hello, {{content}}！", "alternate_alert": "Hello", "android": { "alert": "Hi, JPush!", "title": "Send to Android", "builder_id": 1, "large_icon": "http://www.jiguang.cn/largeIcon.jpg", "intent": { "url": "intent:#Intent;component=com.jiguang.push/com.example.jpushdemo.SettingActivity;end", }, "extras": { "newsid": 321 } }, "ios": { "alert": "Hi, JPush!", "sound": "default", "badge": "+1", "thread-id": "default", "extras": { "newsid": 321 } }, "voip": { // 此功能需要 JPush iOS SDK v3.3.2 及以上版本支持 "key": "value" // 任意自定义 key/value 对，api 透传下去 }, "quickapp": { "alert": "Hi, JPush!", "title": "Send to QuickApp", "page": "/page1" } }, "message": { "msg_content": "Hi,JPush", "content_type": "text", "title": "msg", "extras": { "key": "value" } }, "sms_message": { "temp_id": 1250, "temp_para": { "code": "123456" }, "delay_time": 3600, "active_filter": false }, "options": { "alternate_set": true, "time_to_live": 60, "apns_production": false, "apns_collapse_id": "jiguang_test_201706011100" }, "callback": { "url": "http://www.bilibili.com", "params": { "name": "joe", "age": 26 }, "type": 3 }, "cid": "8103a4c628a0b98974ec1949-711261d4-5f17-4d2f-a855-5e5a8909b26e" }
          {
    "platform": "all",
    "audience": {
        "tag": [
            "深圳",
            "北京"
        ]
    },
    "notification": {
        "alert": "Hello, {{content}}！",
        "alternate_alert": "Hello",
        "android": {
            "alert": "Hi, JPush!",
            "title": "Send to Android",
            "builder_id": 1,
            "large_icon": "http://www.jiguang.cn/largeIcon.jpg",
            "intent": {
                "url": "intent:#Intent;component=com.jiguang.push/com.example.jpushdemo.SettingActivity;end",
            },
            "extras": {
                "newsid": 321
            }
        },
        "ios": {
            "alert": "Hi, JPush!",
            "sound": "default",
            "badge": "+1",
            "thread-id": "default",
            "extras": {
                "newsid": 321
            }
        },
        "voip": { // 此功能需要 JPush iOS SDK v3.3.2 及以上版本支持
            "key": "value" // 任意自定义 key/value 对，api 透传下去
        },
        "quickapp": {
            "alert": "Hi, JPush!",
            "title": "Send to QuickApp",
            "page": "/page1"
        }
    },
    "message": {
        "msg_content": "Hi,JPush",
        "content_type": "text",
        "title": "msg",
        "extras": {
            "key": "value"
        }
    },
    "sms_message": {
        "temp_id": 1250,
        "temp_para": {
            "code": "123456"
        },
        "delay_time": 3600,
        "active_filter": false
    },
    "options": {
        "alternate_set": true,
        "time_to_live": 60,
        "apns_production": false,
        "apns_collapse_id": "jiguang_test_201706011100"
    },
    "callback": {
        "url": "http://www.bilibili.com",
        "params": {
            "name": "joe",
            "age": 26
        },
        "type": 3
    },
    "cid": "8103a4c628a0b98974ec1949-711261d4-5f17-4d2f-a855-5e5a8909b26e"
}
此代码块在浮窗中显示

推送参数

推送的参数结构体，注意部分参数不能同时使用，详见下表：

关键字 选项 含义
platform 必填 推送平台设置
audience 必填 推送设备指定
notification 可选
  • 通知内容体,是被推送到客户端的内容。
  • 与 message 一起二者必须有其一，可以二者并存。
    		•
    alert 可选 各个平台的通知内容，详见 alert 。
    alternate_alert 可选 alert 的备用文案，当后台查询个性文案的属性值为空时，使用备用文案的值定义 alert，详见 alternate_alert 。
    android 可选 Android 平台上的通知，详见 android 。
    ios 可选 iOS 平台上 APNs 通知结构，详见 ios 。
    quickapp 可选 快应用平台上通知结构，详见 quickapp 。
    voip 可选 iOS VOIP 功能。该类型推送支持和 iOS 的 Notification 通知并存，详见 voip 。
    message 可选
  • 消息内容体,是被推送到客户端的内容。
  • 与 notification 一起二者必须有其一，可以二者并存。
    		•
    inapp_message 可选
  • 面向于通知栏消息类型，对于通知权限关闭的用户可设置启用此功能。
  • 不可与 message 同时并存。
    		•
    live_activity 可选
  • 实时活动内容体。
  • 不可与 notification 或 message 等并存。
    		•
    sms_message 可选 短信渠道补充送达内容体
    options 可选 推送参数
    callback 可选 回调参数
    notification_3rd 可选
  • 自定义消息转厂商通知内容体。
  • 与 message 一起使用。
    		•
    cid 可选 用于防止 api 调用端重试造成服务端的重复推送而定义的一个标识符。

    platform：推送平台

    JPush 当前支持 Android, iOS, QuickApp，Windows Phone 四个平台的推送。其关键字分别为："android", "ios", "quickapp"。

    如果目标平台为 iOS 平台，推送 Notification 时需要在 options 中通过 apns_production 字段来设定推送环境。True 表示推送生产环境，False 表示要推送开发环境； 如果不指定则为推送生产环境；一次只能推送给一个环境。


    推送到所有平台：

    {"platform" : "all"}
              {"platform" : "all"}
    此代码块在浮窗中显示

    指定特定推送平台：

    {"platform" : ["android", "ios","quickapp"] }
              {"platform" : ["android", "ios","quickapp"] }
    此代码块在浮窗中显示

    audience：推送目标

    推送设备对象，表示一条推送可以被推送到哪些设备列表。确认推送设备对象，JPush 提供了多种方式，比如：别名、标签、注册 ID、分群、广播等。

    推送目标

    广播外的设备选择方式，有如下几种：

    关键字 类型 含义 说明 备注
    all String 发广播 给全部设备进行推送
  • 基于业务优化的需求，极光于 2020 年 3 月 10 日对「广播推送」的频率进行限制，调整为 10 次每天，超过调用限制时将返回报错码 2008，官网控制台将与 Push API 同步调整。
  • 注意：本次调整仅限制广播，对广播外的推送不影响。如广播推送需更高频率，请 联系商务 ，详情请阅读 公告 。
    		•
    tag JSON Array 标签 OR 数组。多个标签之间是 OR 的关系，即取并集。
  • 用标签来进行大规模的设备属性、用户属性分群，此功能为 VIP 用户功能。
  • 一次推送最多 20 个。
  • 有效的 tag 组成：字母（区分大小写）、数字、下划线、汉字、特殊字符 @!#$&*+=.|￥。
  • 限制：每一个 tag 的长度限制为 40 字节。（判断长度需采用 UTF-8 编码）
    		•
    tag_and JSON Array 标签 AND 数组。多个标签之间是 AND 关系，即取交集。
  • 此功能为 VIP 用户功能， 注意与 tag 区分。
  • 一次推送最多 20 个。
    		•
    tag_not JSON Array 标签 NOT 数组。多个标签之间，先取多标签的并集，再对该结果取补集。
  • 此功能为 VIP 用户功能。
  • 一次推送最多 20 个。
    		•
    alias JSON Array 别名 数组。多个别名之间是 OR 关系，即取并集。
  • 用别名来标识一个用户，一个设备只能绑定一个别名，但多个设备可以绑定同一个别名。
  • 一次推送最多 1000 个。
  • 有效的 alias 组成：字母（区分大小写）、数字、下划线、汉字、特殊字符 @!#$&*+=.|￥。
  • 限制：每一个 alias 的长度限制为 40 字节。（判断长度需采用 UTF-8 编码）
    		•
    registration_id JSON Array 注册 ID 数组。多个注册 ID 之间是 OR 关系，即取并集。
  • 设备标识，客户端集成 SDK 后可获取到该值。
  • 一次推送最多 1000 个。
  • 如果您一次推送的 registration_id 值超过 1000 个，可以直接使用 文件推送 功能。
    		•
    segment JSON Array 用户分群 ID 在页面创建的用户分群的 ID。定义为数组，但目前限制一次只能推送一个。 目前限制是一次只能推送一个。
    abtest JSON Array A/B Test ID 在页面创建的 A/B 测试的 ID。定义为数组，但目前限制是一次只能推送一个。 目前限制一次只能推送一个。
    live_activity_id String 实时活动标识 对应 iOS SDK liveActivityId 的值，参考客户端：registerLiveActivity。 这种方式不能和其它audience方式组合使用，比如不允许（live_activity + tag 组合）。

    以上几种类型至少需要有其一。如果值数组长度为 0，表示该类型不存在。

    这几种类型可以并存（live_activity_id除外），多项的隐含关系是 AND，即取几种类型结果的交集。

    例如：

    "audience" : {"tag" : [ "tag1", "tag2"], "tag_and" : ["tag3", "tag4"], "tag_not" : ["tag5", "tag6"] }

    先计算 "tag" 字段的结果 tag1 或 tag2=A;

    再计算 "tag_and" 字段的结果 tag3 且 tag4=B;

    再计算 "tag_not" 字段的结果 非 (tag5 或 tag6)=C;

    "audience" 的最终结果为 A 且 B 且 C 。


    示例

    • 推送给全部（广播）：
    { "platform": "all", "audience" : "all", "notification" : { "alert" : "Hi, JPush!", "android" : {}, "ios" : {"extras" : { "newsid" : 321} } } }
              {
   "platform": "all",
   "audience" : "all",
   "notification" : {
      "alert" : "Hi, JPush!",
      "android" : {},
      "ios" : {"extras" : { "newsid" : 321}
      }
   }
}
    此代码块在浮窗中显示
    • 推送给多个标签（只要在任何一个标签范围内都满足）：在深圳、广州、或者北京
    { "audience" : {"tag" : [ "深圳", "广州", "北京"] } }
              {
    "audience" : {"tag" : [ "深圳", "广州", "北京"]
    }
}
    此代码块在浮窗中显示
    • 推送给多个标签（需要同时在多个标签范围内）：在深圳并且是“女”
    { "audience" : {"tag_and" : [ "深圳", "女"] } }
              {
    "audience" : {"tag_and" : [ "深圳", "女"]
    }
}
    此代码块在浮窗中显示
    • 推送给多个别名：
    { "audience" : {"alias" : [ "4314", "892", "4531"] } }
              {
    "audience" : {"alias" : [ "4314", "892", "4531"]
    }
}
    此代码块在浮窗中显示
    • 推送给多个注册 ID：
    { "audience" : {"registration_id" : [ "4312kjklfds2", "8914afd2", "45fdsa31"] } }
              {
    "audience" : {"registration_id" : [ "4312kjklfds2", "8914afd2", "45fdsa31"]
    }
}
    此代码块在浮窗中显示
    • 可同时推送指定多类推送目标：在深圳或者广州，并且是 “女” “会员”
    { "audience" : {"tag" : [ "深圳", "广州"], "tag_and" : ["女", "会员"] } }
              {
    "audience" : {"tag" : [ "深圳", "广州"],
        "tag_and" : ["女", "会员"]
    }
}
    此代码块在浮窗中显示
    • 推送给指定实时活动：
    { "audience" : {"live_activity_id" : "312kjklds2"} } }
              {
    "audience" : {"live_activity_id" : "312kjklds2"}
    }
}
    此代码块在浮窗中显示

    notification：通知

    “通知”对象，是一条推送的实体内容对象之一（另一个是“消息”），是会作为“通知”推送到客户端的。
    其下属属性包含 4 种，3 个平台属性，以及一个 "alert" 属性。

    alert

    • 通知的内容在各个平台上，都可能只有这一个最基本的属性 "alert"。
    • 这个位置的 "alert" 属性（直接在 notification 对象下），是一个快捷定义，各平台的 alert 信息如果都一样，则以此定义为准。如果各平台有定义，则覆盖这里的定义。
    • 支持设置个性化文案，详情参考 个性化文案推送。

    普通示例：

    { "notification": { "alert": "Hello, JPush!" } }
              {
    "notification": {
        "alert": "Hello, JPush!"
    }
}
    此代码块在浮窗中显示

    个性化文案示例：

    { "notification": { "alert": "Hello, {{content}}！" } }
              {
    "notification": {
        "alert": "Hello, {{content}}！"
    }
}
    此代码块在浮窗中显示

    alternate_alert

    • alert 的备用文案，当后台查询个性文案的属性值为空时，使用备用文案的值定义 alert。
    • 使用时需设置 option.alternate_set 为 true，详见 如何实现个性化文案推送 。
    { "notification": { "alert": "Hello, {{content}}！", "alternate_alert": "Hello" } }
              {
    "notification": {
        "alert": "Hello, {{content}}！",
        "alternate_alert": "Hello"
    }
}
    此代码块在浮窗中显示

    android

    Android 平台上的通知，JPush SDK 按照一定的通知栏样式展示。

    支持的字段有：

    关键字 类型 选项 含义 说明
    alert string 必填 通知内容
  • 这里指定后会覆盖上级统一指定的 alert 信息。
  • 内容可以为空字符串，表示不展示到通知栏。
  • 支持设置个性化文案，详情参考 个性化文案推送 。
  • 各推送通道对此字段的限制详见 推送限制 。
    		•
    alternate_alert string 可选 alert 的备用文案
  • 仅开启个性化文案功能时有效。
  • 当后台查询个性文案的属性值为空时，使用备用文案的值定义 alert，详情参考 个性化文案推送 。
    		•
    title string 可选 通知标题
  • 如果指定了，则通知里原来展示 App 名称的地方，将展示 title。
  • 支持设置个性化文案，详情参考 个性化文案推送 。
  • 各推送通道对此字段的限制详见 推送限制 。
    		•
    alternate_title string 可选 title 的备用文案
  • 仅开启个性化文案功能时有效。
  • 当后台查询个性文案的属性值为空时，使用备用文案的值定义 title，详情参考 个性化文案推送 。
    		•
    builder_id int 可选 通知栏样式 ID
  • Android SDK 可 设置通知栏样式 。
  • 根据样式 ID 来指定通知样式。
  • android 8.0 开始建议采用 NotificationChannel 配置 。
    		•
    channel_id String 可选 android 通知 channel_id
  • 根据 channel ID 来指定通知栏展示效果，不超过 1000 字节。
  • Android 8.0 开始可以进行 NotificationChannel 配置 。
  • options.third_party_channel 下的小米、OPPO 和华为厂商参数也有 channel_id 字段，若有填充，则优先使用，若无填充则以本字段定义为准。
    		•
    priority int 可选 通知栏展示优先级 默认为 0，范围为 -2～2。
    category string 可选 通知栏条目过滤或排序 完全依赖 rom 厂商对 category 的处理策略。
    style int 可选 通知栏样式类型 用来指定通知栏样式类型，默认为 0。
  • 1：bigText
  • 2：Inbox
  • 3：bigPicture
    		•
    alert_type int 可选 通知提醒方式 可选范围为 -1～7 ，默认按照 -1 处理。 即0111二进制，左数第二位代表 light,第三位代表 vibrate，第四位代表 sound。 0：不生效，1：生效。如： Notification.DEFAULT_ALL = -1 ，Notification.DEFAULT_SOUND = 1, Notification.DEFAULT_VIBRATE = 2, Notification.DEFAULT_LIGHTS = 4 的任意 “or” 组合。
    big_text string 可选 大文本通知栏样式
  • 当 style = 1 时可用，内容会被通知栏以大文本的形式展示出来。
  • 若没有填充 厂商 big_text, 则也默认使用该 big_text 字段展示。
  • 支持 api 16 以上的 rom。
    		•
    inbox JSONObject 可选 文本条目通知栏样式
  • 当 style = 2 时可用， json 的每个 key 对应的 value 会被当作文本条目逐条展示。
  • 若没有填充 厂商 inbox，则默认使用该 inbox 字段展示。
  • 支持 api 16 以上的 rom。
    		•
    big_pic_path string 可选 大图片通知栏样式 使用详情参见 设置大图片文档 。
  • 当 style = 3 时可用，目前支持 .jpg 和 .png 格式的图片。
  • 支持网络图片 url、本地图片的 path、 极光 media_id（推荐使用），如果是 http／https 的 url，会自动下载；如果要指定开发者准备的本地图片就填 sdcard 的相对路径。
  • 若没有填充 厂商 big_pic_path，则默认使用该字段展示。
  • 支持 api 16 以上的 rom。
    		•
    extras JSON Object 可选 扩展字段
  • 这里自定义 JSON 格式的 Key / Value 信息，以供业务使用。
  • 针对部分厂商跳转地址异常，可通过 third_url_encode 兼容处理，详情参考 厂商通道无法跳转问题分析。
    • large_icon string 可选 通知栏大图标 使用详情参见 设置图标文档 。
  • 图标大小不超过 30 k（注：从 JPush Android SDK v4.0.0 版本开始，图片大小限制提升至 300 k）。
  • 支持网络图片 url、本地图片的 path、 极光 media_id（推荐使用），如果是 http／https 的 url，会自动下载；如果要指定开发者准备的本地图片就填 sdcard 的相对路径。
  • 此字段值，若是 media_id, 则对其它厂商通道生效，若非 media_id，则对走华硕通道和极光通道下发的消息生效，不影响请求走其它厂商通道。
  • 若没有填充 厂商 large_icon ，则默认使用该 large_icon 字段展示。
    		•
    small_icon_uri string 可选 通知栏小图标 使用详情参见 设置图标文档 。
  • 图标大小不超过 30 k （注：从 JPush Android SDK v4.0.0 版本开始，图片大小限制提升至 300 k）。
  • 支持以 http 或 https 开头的网络图片和通过极光图片上传接口得到的 media_id 值（推荐使用）。
  • 此字段值，若是 media_id, 则对其它厂商通道生效，若非 media_id，则对走华硕通道和极光通道下发的消息生效，不影响请求走其它厂商通道。
  • 若没有填充 厂商 small_icon_uri，则默认使用该 small_icon_uri 字段展示。
    		•
    intent JSON Object 可选 指定跳转页面 使用 intent 里的 url 指定点击通知栏后跳转的目标页面;
  • SDK＜422 的版本此字段值仅对走华硕通道和极光自有通道下发生效，不影响请求走其它厂商通道。
  • SDK≥422 的版本，API 推送时建议填写 intent 字段，否则点击通知可能无跳转动作。此字段支持以下三种类型:
    1. 跳转到目标页:
    intent:#Intent;action=action 路径;component= 包名 /Activity 全名;end
    （OPPO 和 FCM 通道必须传 "action 路径", 其他厂商必须传 "Activity 全名", 否则将出现对应厂商无法跳转问题）
    2. 跳转到 deeplink 地址:
    scheme://test?key1=val1&key2=val2
    3. 应用首页: intent:#Intent;action=android.intent.action.MAIN;end (固定为此地址)
    		•
    uri_activity string 可选 指定跳转页面
  • 用于指定开发者想要打开的 activity，值为 activity 节点的 “android:name”属性值。
  • 适配华为、小米、vivo 厂商通道跳转。
  • Jpush SDK≥V4.2.2，可不再填写本字段，仅设置 intent 字段即可。
    • uri_action string 可选 指定跳转页面
  • 用于指定开发者想要打开的 activity，值为 "activity"-"intent-filter"-"action" 节点的 "android:name" 属性值。
  • 适配 oppo、fcm 跳转。
  • Jpush SDK≥V4.2.2，可不再填写本字段，仅设置 intent 字段即可，但若需兼容旧版 SDK 必须填写该字段
    • badge_add_num int 可选 设置角标数字累加值，在原角标的基础上进行累加
  • 此属性目前仅针对华为 EMUI 8.0 及以上、小米 MIUI 6 及以上、vivo、荣耀设备生效。
  • 此字段如果不填，表示不改变角标数字（小米设备由于系统控制，不论推送走极光通道下发还是厂商通道下发，即使不传递依旧是默认 +1 的效果）。
  • 取值范围为：1-99，若设置了取值范围内的数字，下一条通知栏消息配置的 badge_add_num 数据会和原角标数量进行相加，建议取值为 1。
    举例：badge_add_num 取值为 1，原角标数为 2，发送此角标消息后，应用角标数显示为 3。
  • 针对华为 / 荣耀通道，如果 badge_set_num 与 badge_add_num 同时存在，则以 badge_set_num 为准。
    		•
    badge_set_num int 可选 设置角标数字固定值
  • 此属性目前仅针对华为 EMUI 8.0 及以上、荣耀设备走厂商通道时生效，如果 badge_set_num 与 badge_add_num 同时存在，则以 badge_set_num 为准。
  • 取值范围为：1-99，若设置了取值范围内的数字，对应下一条通知栏消息配置的 badge_set_num 数字则为角标数值，举例：badge_set_num 取值为 1，无论应用之前角标数为多少，发送此角标消息后，应用角标数均显示为 1。
    		•
    badge_class string 可选 桌面图标对应的应用入口 Activity 类， 比如“com.test.badge.MainActivity”
  • 仅华为和荣耀通道推送时生效，此值如果填写非主 Activity 类，以厂商限制逻辑为准。
  • 若需要实现角标累加功能，需配合 badge_add_num 使用，二者需要共存，缺少其一不可。
  • 若需要实现角标固定值功能，需配合 badge_set_num 使用，二者需要共存，缺少其一不可。
    		•
    sound string 可选 铃声
  • 填写 Android 工程中 /res/raw/ 路径下铃声文件名称，无需文件名后缀.
  • 注意：针对 Android 8.0 以上，当传递了 channel_id 时，此属性不生效。
    		•
    show_begin_time string 可选 定时展示开始时间（yyyy-MM-dd HH:mm:ss）
  • 此属性不填写，SDK 默认立即展示；此属性填写，则以填写时间点为准才开始展示。
  • JPush Android SDK v3.5.0 版本开始支持。
    		•
    show_end_time string 可选 定时展示结束时间（yyyy-MM-dd HH:mm:ss）
  • 此属性不填写，SDK 会一直展示；此属性填写，则以填写时间点为准，到达时间点后取消展示。
  • JPush Android SDK v3.5.0 版本开始支持。
    		•
    display_foreground string 可选 APP 在前台，通知是否展示
  • 值为 "1" 时，APP 在前台会弹出通知栏消息。
  • 值为 "0" 时，APP 在前台不会弹出通知栏消息。
  • 注：默认情况下 APP 在前台会弹出通知栏消息，JPush Android SDK v3.5.8 版本开始支持。
    		•

    { "notification" : { "android" : { "alert" : "hello, JPush!", "title" : "JPush test", "builder_id" : 3, "style":1 // 1,2,3 "alert_type":1 // -1 ~ 7 "big_text":"big text content", "inbox":JSONObject, "big_pic_path":"picture url", "priority":0, // -2~2 "category":"category str", "large_icon": "http://www.jiguang.cn/largeIcon.jpg", "intent": {"url": "intent:#Intent;component=com.jiguang.push/com.example.jpushdemo.SettingActivity;end",}, "extras" : { "news_id" : 134, "my_key" : "a value" } } } }
              {
    "notification" : {
        "android" : {
             "alert" : "hello, JPush!",
             "title" : "JPush test",
             "builder_id" : 3,
             "style":1  // 1,2,3
             "alert_type":1 // -1 ~ 7
             "big_text":"big text content",
             "inbox":JSONObject,
             "big_pic_path":"picture url",
             "priority":0, // -2~2
             "category":"category str",
             "large_icon": "http://www.jiguang.cn/largeIcon.jpg",
           "intent": {"url": "intent:#Intent;component=com.jiguang.push/com.example.jpushdemo.SettingActivity;end",},
             "extras" : {
                  "news_id" : 134,
                  "my_key" : "a value"
             }
        }
    }
}
    此代码块在浮窗中显示

    ios

    iOS 平台上 APNs 通知结构。
    该通知内容会由 JPush 代理发往 Apple APNs 服务器，并在 iOS 设备上在系统通知的方式呈现。
    该通知内容满足 APNs 的规范，支持的字段如下：

    关键字 类型 选项 含义 说明
    alert string 或 JSON Object 必填 通知内容
  • 这里指定内容将会覆盖上级统一指定的 alert 信息。
  • 内容为空则不展示到通知栏。
  • 支持字符串形式也支持官方定义的 alert payload 结构，在该结构中包含 title 和 subtitle 等官方支持的 key。
  • 支持设置个性化文案，详情参考 个性化文案推送 。
    		•
    alternate_alert string 或 JSON Object 可选 alert 的备用文案
  • 仅开启个性化文案功能时有效。
  • alert 和 alternate_alert 必须使用同种数据类型。
  • 当后台查询个性文案的属性值为空时，使用备用文案的值定义 alert，详情参考 个性化文案推送 。
    		•
    sound string 或 JSON Object 可选 通知提示声音或警告通知
  • 普通通知： string 类型，如果无此字段，则此消息无声音提示；有此字段，如果找到了指定的声音就播放该声音，否则播放默认声音，如果此字段为空字符串，iOS 7 为默认声音，iOS 8 及以上系统为无声音。说明：JPush 官方 SDK 会默认填充声音字段，提供另外的方法关闭声音，详情查看各 SDK 的源码。
  • 告警通知： JSON Object , 支持官方定义的 payload 结构，在该结构中包含 critical 、name 和 volume 等官方支持的 key 。
    		•
    badge string 可选 应用角标
  • 可设置为 N、+N、-N，N 的取值范围为 [0,99]。若上传的角标值 value 为 10，表示角标会设置为 N、10+N、10-N（值小于 0 时默认清除角标）。
  • 为 0 或空字符串，则表示清除角标。
  • 如果不填，表示不改变角标数字。
  • JPush 官方服务端 SDK 会默认填充 badge 值为 "+1"，详情参考：badge +1。
    		•
    content-available boolean 可选 推送唤醒 推送的时候携带 "content-available":true，说明是 Background Remote Notification，如果不携带此字段则是普通的 Remote Notification，详情参考：Background Remote Notification。
    mutable-content boolean 可选 通知扩展 iOS 10 新增的 Notification Service Extension 功能，用于上报每条 APNs 信息的送达状态，使用该功能需要客户端实现 Service Extension 接口 ，并在服务端使用 mutable-content 字段完成设置。
  • true：说明支持 iOS 10 的 UNNotificationServiceExtension 功能。
  • 如果不携带此字段则是普通的 Remote Notification，无法统计抵达数据。
    		•
    category string 可选 iOS 分类 iOS 8 开始支持，设置 APNs payload 中的 "category" 字段值。
    extras JSON Object 可选 附加字段 这里自定义 Key / value 信息，以供业务使用，详情参考 如何设置右侧图标/大图片 和 iOS 通知点击跳转。
    thread-id string 可选 通知分组 ios 的远程通知通过该属性来对通知进行分组，同一个 thread-id 的通知归为一组。
    interruption-level string 可选 通知优先级和交付时间的中断级别 ios 15 的通知级别，取值只能是 active,critical,passive,time-sensitive 中的一个，详情参考：UNNotificationInterruptionLevel。

    iOS 通知 JPush 要转发给 APNs 服务器。APNs HTTP/2 的推送协议支持传递 4096 字节。

    JPush 因为需要重新组包，并且考虑一点安全冗余，要求 "iOS":{ } 及大括号内的总体长度不超过：3584 个字节。JPush 使用 utf-8 编码，所以一个汉字占用 3 个字节长度。


    服务端发送消息串

    { "notification" : {      "ios" : {              "alert" : "hello, JPush!",              "sound" : "sound.caf",              "badge" : 1,              "extras" : {                   "news_id" : 134,                   "my_key" : "a value"              }         } } }
              {
    "notification" : {
         "ios" : {
                 "alert" : "hello, JPush!",
                 "sound" : "sound.caf",
                 "badge" : 1,
                 "extras" : {
                      "news_id" : 134,
                      "my_key" : "a value"
                 }
               }
       }
}
    此代码块在浮窗中显示

    客户端收到 apns

    { "_j_msgid" = 813843507; aps = { alert = "hello,JPush!"; badge = 1; sound = "sound.caf"; }; "my_key" = "a value"; "news_id" = 134; }
              {
    "_j_msgid" = 813843507;
    aps =     {
        alert = "hello,JPush!";
        badge = 1;
        sound = "sound.caf";
    };
    "my_key" = "a value";
    "news_id" = 134;
}
    此代码块在浮窗中显示

    quickapp

    快应用平台上通知结构。 该通知内容满足快应用平台的规范，支持的字段如下：

    关键字 类型 选项 含义 说明
    title string 必填 通知标题
  • 必填字段，快应用推送通知的标题。
  • 支持设置个性化文案，详情参考 个性化文案推送 。
    • alternate_title string 可选 title 的备用文案
  • 仅开启个性化文案功能时有效。
  • 当后台查询个性文案的属性值为空时，使用备用文案的值定义 title，详情参考 个性化文案推送 。
    		•
    alert string 必填 通知内容
  • 这里指定了，则会覆盖上级统一指定的 alert 信息。
  • 支持设置个性化文案，详情参考 个性化文案推送 。
    		•
    alternate_alert string 可选 alert 的备用文案
  • 仅开启个性化文案功能时有效。
  • 当后台查询个性文案的属性值为空时，使用备用文案的值定义 alert，详情参考 个性化文案推送 。
    		•
    page string 必填 跳转页面 快应用通知跳转地址。
    extras JSON Object 可选 附加字段 这里自定义 Key / value 信息，以供业务使用。

    服务端发送消息串

    { "notification" : { "quickapp": { "alert": "Hi, JPush!", "title": "Send to QuickApp", "page": "/page1", "extras" : { "news_id" : 134, "my_key" : "a value" } } }
              {
    "notification" : {
        "quickapp": {
            "alert": "Hi, JPush!",
            "title": "Send to QuickApp",
            "page": "/page1",
            "extras" : {
                "news_id" : 134,
                "my_key" : "a value"
            }
        }
}
    此代码块在浮窗中显示

    voip

    iOS VOIP 功能。
    该类型推送支持和 iOS 的 Notification 通知并存，请求参数结构参考：

    { "notification": { "ios" : { "alert" : "hello, JPush!", "sound" : "sound.caf" }, "voip": {"key": "value" // 任意自定义 key/value 对，会透传给 APP} } }
                  {
        "notification": {
            "ios" : {
                "alert" : "hello, JPush!",
                "sound" : "sound.caf"
            },
            "voip": {"key": "value" // 任意自定义 key/value 对，会透传给 APP}
        }
    }
    此代码块在浮窗中显示

    message：自定义消息

    应用内消息，又称作：自定义消息，透传消息。

    • 此部分内容不会展示到通知栏上，JPush SDK 收到消息内容后透传给 App，需要 App 自行处理。
    • iOS 在推送应用内消息通道（非 APNS）获取此部分内容，需 App 处于前台。
    • Windows Phone 暂时不支持应用内消息。

    消息包含如下字段：

    关键字 类型 选项 含义
    msg_content string 必填
  • 消息内容本身。
  • 支持设置个性化文案，详情参考 个性化文案推送 。
    		•
    alternate_content string 可选
  • content 的备用文案，仅开启个性化文案功能时有效。
  • 当后台查询个性文案的属性值为空时，使用备用文案的值定义 content，详情参考 个性化文案推送 。
    		•
    title string 可选
  • 消息标题。
  • 支持设置个性化文案，详情参考 个性化文案推送 。
    • alternate_title string 可选
  • title 的备用文案,仅开启个性化文案功能时有效。
  • 当后台查询个性文案的属性值为空时，使用备用文案的值定义 title，详情参考 个性化文案推送 。
    		•
    content_type string 可选 消息内容类型，开发者可根据自身业务定义具体类型。
    extras JSON Object 可选 JSON 格式的可选参数

    Android 1.6.2 及以下版本 接收 notification 与 message 并存（即本次 api 调用同时推送通知和消息）的离线推送， 只能收到通知部分，message 部分没有透传给 App。 Android 1.6.3 及以上 SDK 版本已做相应调整，能正常接收同时推送通知和消息的离线记录。 iOS 1.7.3 及以上的版本才能正确解析 v3 的 message，但是无法解析 v2 推送通知同时下发的应用内消息。
              Android 1.6.2 及以下版本 接收 notification 与 message 并存（即本次 api 调用同时推送通知和消息）的离线推送， 只能收到通知部分，message 部分没有透传给 App。

Android 1.6.3 及以上 SDK 版本已做相应调整，能正常接收同时推送通知和消息的离线记录。

iOS 1.7.3 及以上的版本才能正确解析 v3 的 message，但是无法解析 v2 推送通知同时下发的应用内消息。
    此代码块在浮窗中显示

    inapp_message：应用内提醒

    inapp_message 此功能生效需 Android push SDK≥V3.9.0、iOS push SDK≥V3.4.0，若低于此版本按照原流程执行。

    inapp_message 面向于通知栏消息类型，对于通知权限关闭的用户可设置启用此功能。此功能启用后，当用户前台运行 APP 时，会通过应用内消息的方式展示通知栏消息内容。

    • inapp_message： 面向通知栏消息，Boolean 类型；
      • 值为 true 表示启用应用内提醒功能；
      • 值为 false 表示禁用应用内提醒功能。

    示例如下：

    { "cid": "8103a4c628a0b98974ec1949-711261d4-5f17-4d2f-a855-5e5a8909335e", "platform": "all", "audience": { "tag": [ "深圳", "北京" ] }, "notification": { "android": { "alert": "Hi, JPush!", "title": "Send to Android" }, "ios": { "alert": "Hi, JPush!", "sound": "default", "badge": "+1", "thread-id": "default", "extras": {"newsid": 321} } }, "inapp_message": {"inapp_message": true} }
              {
    "cid": "8103a4c628a0b98974ec1949-711261d4-5f17-4d2f-a855-5e5a8909335e",
    "platform": "all",
    "audience": {
        "tag": [
            "深圳",
            "北京"
        ]
    },
    "notification": {
        "android": {
            "alert": "Hi, JPush!",
            "title": "Send to Android"
        },
        "ios": {
            "alert": "Hi, JPush!",
            "sound": "default",
            "badge": "+1",
            "thread-id": "default",
            "extras": {"newsid": 321}
        }
    },
    "inapp_message": {"inapp_message": true}
}
    此代码块在浮窗中显示

    live_activity：实时活动消息

    实时活动内容体。有如下字段信息：

    关键字 类型 选项 说明
    ios JSON Object 必填 详细字段参考下表 iOS JSON Object 部分。

    iOS JSON Object

    关键字 类型 选项 说明
    event string 必填 更新：“update”，结束："end"。
    content-state JSON Object 必填 需与客户端 SDK 值匹配（对应 Apple 官方的 content-state 字段）。
    alert JSON Object 选填 参考下表 iOS alert JSON Object 说明。
    dismissal-date int 可选 实时活动结束展示时间。

    iOS alert JSON Object
    关键字 类型 选项 说明
    title string 可选 显示到Apple Watch的消息标题。
    alternate_title string 可选 title 的备用文案。
    body string 可选 显示到Apple Watch的消息内容。
    alternate_body string 可选 body 的备用文案。
    sound string 可选 提示音。
    • iOS 实时活动消息（Live Activity） JPush 要转发给苹果服务器。苹果要求实时活动消息 （ActivityKit）远程推送的动态更新数据大小不超过 4096 字节。
    • JPush 因为需要重新组包，并且考虑一点安全冗余，要求 "live_activity" 参数体内 "iOS":{ } 及大括号内的总体长度不超过：3584 个字节。JPush 使用 utf-8 编码，所以一个汉字占用 3 个字节长度。

    实时活动推送示例

    { "cid": "8103a4c628a0b98974ec1949-711261d4-5f17-4d2f-a855-5e5a8909b26e", "platform": ["ios"], "audience": { "live_activity_id": "abcdef" }, "live_activity": { "ios": { "event": "update", "content-state":{ "key":"value" }, "alert":{ "title":"Send to {{nickname}}", "alternate_title":"Send to iOS", "body":"Hi, {{nickname}}!", "alternate_body":"Hi, JPush!", "sound":"default" }, "dismissal-date": 1168364460 } }, "options": { "apns_production": false, "alternate_set": true } }
              {
    "cid": "8103a4c628a0b98974ec1949-711261d4-5f17-4d2f-a855-5e5a8909b26e",
    "platform": ["ios"],
    "audience": {
        "live_activity_id": "abcdef"
    },
    "live_activity": {
        "ios": {
            "event": "update",
            "content-state":{
                "key":"value"
            },
            "alert":{
                "title":"Send to {{nickname}}",
                "alternate_title":"Send to iOS",
                "body":"Hi, {{nickname}}!",
                "alternate_body":"Hi, JPush!",
                "sound":"default"
            },
            "dismissal-date": 1168364460
        }  
    },
    "options": {
        "apns_production": false,
        "alternate_set": true
    }
}
    此代码块在浮窗中显示

    sms_message：短信

    温馨提示：

    1. 使用短信业务，会产生额外的运营商费用，具体请咨询商务，联系电话：400-888-2376

    2. 短信由签名和正文内容两部分组成。应运营商规定，签名和正文内容需审核，参考 名词解释 。

    3. 签名设置参考 《控制台操作指南》之签名设置 和 短信签名 API 。

    4. 自 2018 年 3 月起，短信补充的开发者必须提交正文内容模板，审核通过后即可使用。因此推送时需要填写 temp_id（如果模版有设置参数则需要填写 temp_para），参考 《控制台操作指南》之模板设置 和 短信模板 API 。


    开发者需要先把用户的手机号码与设备的 registrationID 匹配。绑定方法： 服务端-Device-更新设备 、Android API-设置手机号码 、 iOS API-设置手机号码 。

    短信补发

    在开发者指定时间之内，判断推送是否成功，若没有达到成功标准则补发短信。

    • 极光通道以真实送达为推送成功。
    • 极光后台可以设置厂商通道判断成功的标准，支持选择 api 调用成功、全部补发、不补发、送达回执，可 联系商务 更改条件。若不选择，默认以提交厂商服务器成功为准。
      • api 调用成功：以极光调用厂商推送 api 成功为基准，调用成功就不补发。
      • 全部补发：厂商通道设备全部补发短信。
      • 不补发：完全不给厂商通道设备补发短信。
      • 送达回执：以厂商送达回执为基准 （如果该通道有送达回执的话），有送达回执就不补发。
    • 设置 delay_time 为非 0 值，详情参见 短信参数说明。

    短信并发

    极光推送支持同时下发推送和短信，API 推送时将 delay_time 设置为 0，详情参见 短信参数说明。

    短信参数说明

    使用 sms_message 设置短信推送内容以及短信发送的延迟时间。与原有 JSON 业务协议相匹配，消息有如下字段信息：

    关键字 类型 选项 说明
    delay_time int 必填 短信发送的延迟时间，若在设定的时间内没有推送成功，则下发短信。
  • 设置为 0，表示立即发送短信，即通知和短信并发。
  • 设置不为 0，表示若在设定的时间内没有推送成功，则进行短信补发。
  • 单位为秒，不能超过 24 小时。
  • 该参数仅对 android 和 iOS 平台有效。
    		•
    signid int 选填 签名 ID，该字段为空则使用应用默认签名。
    temp_id long 必填 短信补充的内容模板 ID,没有填写该字段即表示不使用短信补充功能。
    temp_para JSON 可选 短信模板中的参数。
    active_filter boolean 可选 active_filter 字段用来控制是否对补发短信的用户进行活跃过滤。
  • 默认为 true ，做活跃过滤。
  • 为 false，则不做活跃过滤。

    • options：可选参数

    推送可选项。

    当前包含如下几个可选项：

    关键字 类型 选项 含义 说明
    sendno int 可选 推送序号
  • 纯粹用来作为 API 调用标识，API 返回时被原样返回，以方便 API 调用方匹配请求与返回。
  • 值为 0 表示该 messageid 无 sendno，所以字段取值范围为非 0 的 int。
    		•
    time_to_live int 可选 离线消息保留时长 (秒)
  • 推送当前用户不在线时，为该用户保留多长时间的离线消息，以便其上线时再次推送。
  • 默认 86400 （1 天），普通用户最长 3 天， VIP 用户最长 10 天。设置为 0 表示不保留离线消息，只有推送当前在线的用户可以收到。
  • 该字段对 iOS 的 Notification 消息无效。
    		•
    override_msg_id long 可选 要覆盖的消息 ID 如果当前的推送要覆盖之前的一条推送，这里填写前一条推送的 msg_id 就会产生覆盖效果，即：
  • 该 msg_id 离线收到的消息是覆盖后的内容，即使该 msg_id Android 端用户已经收到，如果通知栏还未清除，则新的消息内容会覆盖之前这条通知。
  • 覆盖功能起作用的时限是：1 天，如果在覆盖指定时限内该 msg_id 不存在，则返回 1003 错误，提示不是一次有效的消息覆盖操作，当前的消息不会被推送。
  • 该字段仅对 Android 有效仅支持极光通道、小米通道、魅族通道、OPPO 通道、FCM 通道、荣耀通道和华为通道（EMUI10 及以上的设备）。
    		•
    apns_production boolean 可选 APNs 是否生产环境 该字段仅对 iOS 的 Notification 有效，如果不指定则为推送生产环境。注意：JPush 服务端 SDK 默认设置为推送 “开发环境”。
  • true：表示推送生产环境。
  • false：表示推送开发环境。
    		•
    apns_collapse_id string 可选 更新 iOS 通知的标识符
  • APNs 新通知如果匹配到当前通知中心有相同 apns-collapse-id 字段的通知，则会用新通知内容来更新它，并使其置于通知中心首位。
  • collapse id 长度不可超过 64 bytes。
    		•
    big_push_duration int 可选 定速推送时长 (分钟)
  • 又名缓慢推送，把原本尽可能快的推送速度，降低下来，给定的 n 分钟内，均匀地向这次推送的目标用户推送；最大值为 1400。
  • 最多能同时存在 20 条定速推送。
  • 未设置则不是定速推送。
    		•
    third_party_channel JSON Object 可选 推送请求下发通道 仅针对配置了厂商用户使用有效，详情参考 third_party_channel 说明 。
    alternate_set boolean 可选 个性化文案功能开关 是否启用个性化文案功能，默认为 false。
  • true: 启用个性化文案功能。
  • false: 关闭个性化文案功能。
    		•
    classification int 可选 消息类型分类 极光不对指定的消息类型进行判断或校准，会以开发者自行指定的消息类型适配 Android 厂商通道。不填默认为 0。
  • 0：代表运营消息。
  • 1：代表系统消息。
    		•

    third_party_channel 说明

    • options.third_party_channel： key 只支持 xiaomi、huawei、honor、meizu、oppo、vivo、fcm 类型用户。 key 可以为上述 7 个类型中的其中一个或者多个同时存在，未传递的 key 其对应的厂商下发走默认下发逻辑。

    • 默认下发逻辑

      • 免费用户：distribution 默认值为 secondary_push，distribution_fcm 默认值为 secondary_fcm_push。
      • VIP 用户：distribution 默认值为 first_ospush，distribution_fcm 默认值为 fcm。

    • 厂商类型的 KEY 对应的 3 个策略参数如下：

    关键字 类型 选项 含义 说明
    distribution string 可选 通知栏消息下发逻辑 取值不能为空字符串。
  • first_ospush（VIP）：成功注册厂商通道的设备走厂商通道，仅注册极光通道的设备走极光通道。
  • ospush（VIP）：表示推送强制走厂商通道下发。 需要特别注意，只要指定此值的厂商对应配额不够时，推送请求会失败，返回 1012 错误码。
    举例：假设指定一个小米用户的 RegistrationID 推送，请求时针对小米、OPPO 等厂商通道都指定了“ospush”，且 OPPO 厂商通道都配额已经用完，则推送同样会返回 1012 错误，提示厂商配额不足。
  • jpush：表示推送强制走极光通道下发。
  • secondary_push：表示推送优先走极光，极光不在线再走厂商，厂商作为辅助（建议此种方式）。
    		•
    distribution_fcm string 可选 通知栏消息 fcm+ 国内厂商组合类型下发逻辑 取值不能为空字符串。
  • jpush：表示推送强制走极光通道下发。
  • fcm（VIP）：表示推送强制走 fcm 通道下发。
  • pns（VIP）：表示推送强制走小米 / 华为 / 荣耀 / 魅族 /oppo/vivo 通道下发。
  • secondary_fcm_push：表示针对 fcm+ 国内厂商组合类型用户，推送优先走极光，极光不在线再走 fcm 通道，fcm 作为辅助。
  • secondary_pns_push：表示针对 fcm+ 国内厂商组合类型用户，推送优先走极光，极光不在线再走厂商通道，厂商作为辅助。
    		•
    distribution_customize string 可选 自定义消息国内厂商类型下发逻辑 定义国内厂商类型用户下发自定义消息的逻辑，此功能仅支持 huawei、honor 通道，需 Android push SDK≥V3.9.0。
    ⚠️注意：小米推送于2022年9月12日0点起停止提供透传消息下发的服务，届时您将无法通过小米通道发送透传消息，请注意调整下发策略，详见 小米官方公告 。
  • jpush：表示推送强制走极光通道下发。
  • first_ospush（VIP）：成功注册厂商通道的设备走厂商通道，仅注册极光通道的设备走极光通道。
  • secondary_push：表示推送优先走极光，极光不在线再走厂商，厂商作为辅助。
    		•

    不同厂商类型的 KEY 可以存在以下属性参数：

    关键字 类型 选项 含义 说明
    channel_id string 可选 通知栏消息分类
  • 为了适配小米、华为、oppo 手机厂商通知栏消息分类，由开发者自行向手机厂商申请，具体申请规则参考： 厂商消息分类使用指南 。
  • 注意华为数据处理位置为中国区的应用不支持该字段，详情参见 华为自定义通知渠道 。
  • android 下也有 channel_id 字段，若本字段有填充，则优先使用，若无填充则以 android.channel_id 的定义为准。
    		•
    skip_quota boolean 可选 配额判断及扣除 是否跳过配额判断及扣除，目前仅对小米和 oppo 有效，默认为 false。
  • true:表示跳过判断及跳过扣除极光侧的配额。
  • false:表示不跳过判断及跳过扣除极光侧的配额。
    • classification int 可选 通知栏消息分类 vivo 手机厂商通知栏消息分类，不填默认为 0。
  • 0：代表运营消息。
  • 1：代表系统消息。
    目前 vivo 对系统消息分类较为严格，具体规则参考：vivo。
    		•
    push_mode int 可选 通知栏消息类型 对应 vivo 的 pushMode 字段，不填默认为 0。详情参考：vivo pushMode。
  • 0：表示正式推送。
  • 1：表示测试推送。
    		•
    importance string 可选 华为、荣耀通知栏消息智能分类 为了适配华为、荣耀手机厂商的通知栏消息智能分类，对应华为/荣耀的 importance 字段，不填充则不下发，参考： 华为通知消息智能分类 、 荣耀通知消息分类标准。
  • LOW：一般消息。
  • NORMAL：重要消息。
  • HIGH：非常重要消息（仅华为支持）。
    		•
    sound string 可选 华为自定义铃声
  • 铃声文件必须存放在应用的 /res/raw 路径下，例如“/res/raw/shake.mp3”，对应 sound 值参数为“/raw/shake”，无需后缀，支持的格式包括 MP3、WAV、MPEG 等。
  • 仅首次给应用推送 服务与通讯消息 时设置有效，需要配合 default_sound 一起使用，详情参考 如何实现自定义铃声 。
    		•
    default_sound boolean 可选 华为默认铃声控制开关 华为官方说明，首次给应用推送 服务与通讯消息 时携带 sound 字段且 default_sound 值设置为 false。注意：由于铃声是通知渠道的属性，因此铃声仅在首次创建渠道（设置 sound）有效，后续无法修改。
  • true：使用系统默认铃声。
  • false：使用 sound 自定义铃声。
    		•
    urgency string 可选 华为厂商自定义消息优先级 为了适配华为手机厂商自定义消息的优先级。
  • HIGH：非常重要消息，HIGH 级别消息到达用户手机时可强制拉起应用进程。
  • NORMAL：重要消息。
    设置“HIGH”需要向华为申请特殊权限，参考： 特殊权限如何申请 。
    		•
    category string 可选 华为、vivo 厂商消息场景标识 为了适配华为、vivo 手机厂商消息，用于标识消息类型，确定消息提醒方式，对特定类型消息加快发送。对应值及其说明参考：华为 category 值说明 、vivo 分类标准。注意：华为需完成 自分类权益申请 。
  • 若应用没有自分类权益，或应用有自分类权益但推送消息不携带 category 字段，则应用的推送消息将通过智能分类进行自动归类。
  • 若应用有自分类权益且推送消息携带 category 字段，将信任开发者提供的分类信息，消息不经过智能分类。
  • vivo 具体生效时间和规则参考 vivo 官方说明。
    		•
    receipt_id string 可选 回执 ID
  • 仅华为通道有效。
  • 输入一个唯一的回执 ID 指定本次下行消息的回执地址及配置，该回执 ID 可以在 回执参数配置 中查看。
    		•
    target_user_type int 可选 华为消息类型 仅华为通道有效。
  • 0：普通消息（默认值）
  • 1：测试消息。每个应用每日可发送该测试消息 500 条且不受 每日单设备推送数量上限要求 。
    		•
    large_icon string 可选 厂商消息大图标样式
  • 支持小米 / 华为 / 荣耀 / oppo 厂商，使用详情参见 设置图标文档 。
  • 优先使用厂商字段， 厂商字段没有填充，则使用 android 里面定义 large_icon 字段 android 内的 large_icon。
  • 其中小米支持极光的 media_id 及小米厂商的大图标 id, 但必须配合小米 big_text 或者是 big_pic_path 使用，否则无效。
  • 华为、荣耀支持极光的 media_id 及网络 https 路径。
  • oppo 支持极光的 media_id 及 oppo 厂商的大图标 id。
  • JPush Android SDK v3.9.0 版本以上才支持该字段。
    		•
    small_icon_uri string 可选 厂商消息小图标样式
  • 目前支持小米 / 华为 / 荣耀厂商，使用详情参见 设置图标文档 。
  • 优先使用厂商字段， 厂商字段没有填充，则使用 android 内的 small_icon_uri 字段。
  • 小米支持极光的 media_id 及小米厂商的小图标 id，华为、荣耀支持极光的 media_id 及厂商本地路径。(小米官方后续不再支持自定义小图标，建议开发者不要继续使用小米 small Icon 相关特性功能)。
    		•
    small_icon_color string 可选 小米厂商小图标样式颜色
  • 为了适配小米厂商的消息小图标样式颜色，不填充默认是灰色 (小米官方后续不在支持自定义小图标，建议开发者不要继续使用小米 small icon 相关特性功能)。
  • JPush Android SDK v3.9.0 版本以上才支持该字段。
    		•
    style int 可选 厂商消息大文本 /inbox/ 大图片样式 用来指定厂商的通知栏样式类型，JPush Android SDK v3.9.0 版本以上才支持该字段，默认为 0。
  • 1：bigText
  • 2：Inbox
  • 3：bigPicture
    • big_text string 可选 厂商消息大文本样式
  • 为了适配厂商的消息大文本样式, 目前支持小米 / 华为 / 荣耀 / oppo 厂商。
  • 优先使用厂商字段， 厂商字段没有填充，则使用 android 里面定义 big_text 字段 android 内的 big_text。
  • 其中小米最多支持 128 个字符 (一个英文或一个中文算一个字符)，配合小米 style 使用，oppo 最多也是支持 128 个字符，配合 style 使用。
  • JPush Android SDK v3.9.0 版本以上才支持该字段。
    • inbox JSONObject 可选 厂商消息 inbox 样式
  • 为了适配厂商的消息 inbox 样式, 目前支持华为厂商。
  • 优先使用厂商字段， 厂商字段没有填充，则使用 android 里面定义 inbox 字段 android 内的 inbox ，配合华为 style 使用。
  • JPush Android SDK v3.9.0 版本以上才支持该字段。
    • big_pic_path string 可选 厂商 big_pic_path
  • 为了适配厂商的消息大图片样式, 目前支持小米 /oppo 两个厂商，使用详情参见 设置大图片文档 。
  • 优先使用厂商字段，厂商字段没有填充，则使用 android 里面定义 big_pic_path 字段 android 内的 big_pic_path，配合各自厂 商的 style 使用。
  • JPush Android SDK v3.9.0 版本以上才支持该字段。
    • only_use_vendor_style boolean 可选 是否使用自身通道设置样式 是否只使用自身通道设置的样式，不使用 android 里面设置的样式，默认为 false，JPush Android SDK v3.9.0 版本以上才支持该字段。
  • true：只使用自身通道设置的样式。
  • false：可使用 android 里面设置的样式。

    • 示例：

    "third_party_channel":{ "xiaomi":{ "distribution":"jpush", "channel_id":"*******", "large_icon":"jgmedia-2-14b23451-0001-41ce-89d9-987b465122da", "small_icon_uri":"jgmedia-3-14b23451-0001-41ce-89d9-987b465122da", "small_icon_color":"#ABCDEF", "big_text":"testbigtext", // 可选，最多支持 128 个字符，配合小米 style 使用 "style":1, "distribution_fcm":"fcm", "skip_quota": true }, "huawei":{ "distribution":"secondary_push", "distribution_fcm":"jpush", "distribution_customize":"first_ospush", "sound":"/raw/shake", "default_sound":false, "importance":"NORMAL", "receipt_id":"111111", "target_user_type":1, "large_icon":"jgmedia-2-14b23451-0001-41ce-89d9-987b465122da", "small_icon_uri":"jgmedia-3-14b23451-0001-41ce-89d9-987b465122da", "inbox": JSONObject, //可选，配合华为 style 使用 "style":2, "only_use_vendor_style":true }, "honor":{ "distribution":"secondary_push", "distribution_fcm":"jpush", "distribution_customize":"first_ospush", "large_icon":"jgmedia-2-14b23451-0001-41ce-89d9-987b465122da", "small_icon_uri":"jgmedia-3-14b23451-0001-41ce-89d9-987b465122da", "style":1 }, "meizu":{ "distribution":"jpush", "distribution_fcm":"pns" }, "fcm":{ // 这个参数不支持 distribution_fcm 字段 "distribution":"jpush" }, "oppo":{ "distribution":"ospush", "channel_id":"*******", "distribution_fcm":"secondary_fcm_push", "large_icon":"jgmedia-2-14b23451-0001-41ce-89d9-987b465122da", "big_pic_path":"jgmedia-1-14b23451-0001-41ce-89d9-987b465122da", "style":1, "skip_quota": true }, "vivo":{ "distribution":"jpush", "classification": 0, "distribution_fcm":"secondary_pns_push", "push_mode":0 } } 
              "third_party_channel":{
    "xiaomi":{
              "distribution":"jpush", 
              "channel_id":"*******", 
              "large_icon":"jgmedia-2-14b23451-0001-41ce-89d9-987b465122da", 
              "small_icon_uri":"jgmedia-3-14b23451-0001-41ce-89d9-987b465122da",
              "small_icon_color":"#ABCDEF", 
              "big_text":"testbigtext", // 可选，最多支持 128 个字符，配合小米 style 使用
              "style":1, 
              "distribution_fcm":"fcm",
              "skip_quota": true 
    },
    "huawei":{
              "distribution":"secondary_push", 
              "distribution_fcm":"jpush", 
              "distribution_customize":"first_ospush", 
              "sound":"/raw/shake",
              "default_sound":false,
              "importance":"NORMAL",
              "receipt_id":"111111", 
              "target_user_type":1,
              "large_icon":"jgmedia-2-14b23451-0001-41ce-89d9-987b465122da",
              "small_icon_uri":"jgmedia-3-14b23451-0001-41ce-89d9-987b465122da",
              "inbox": JSONObject, //可选，配合华为 style 使用
              "style":2, 
              "only_use_vendor_style":true 
    },
    "honor":{
              "distribution":"secondary_push", 
              "distribution_fcm":"jpush", 
              "distribution_customize":"first_ospush", 
              "large_icon":"jgmedia-2-14b23451-0001-41ce-89d9-987b465122da",
              "small_icon_uri":"jgmedia-3-14b23451-0001-41ce-89d9-987b465122da",
              "style":1
    },
    "meizu":{
              "distribution":"jpush",
              "distribution_fcm":"pns" 
    },
    "fcm":{   // 这个参数不支持 distribution_fcm 字段
              "distribution":"jpush"  
    },
    "oppo":{
              "distribution":"ospush", 
              "channel_id":"*******",
              "distribution_fcm":"secondary_fcm_push", 
              "large_icon":"jgmedia-2-14b23451-0001-41ce-89d9-987b465122da", 
              "big_pic_path":"jgmedia-1-14b23451-0001-41ce-89d9-987b465122da", 
              "style":1, 
              "skip_quota": true 
    },
    "vivo":{
            "distribution":"jpush",
            "classification": 0,
            "distribution_fcm":"secondary_pns_push", 
            "push_mode":0
    }
}
    此代码块在浮窗中显示

    callback：回调参数

    Push API 发起请求时，可以指定 callback 参数，方便用户临时变更回调 URL 或者回调带上其自定义参数，满足其日常业务需求。

    此功能仅针对极光 VIP 用户提供，主要提供消息送达、点击回执数据。

    如需要开通此功能，请联系：商务客服

    示例：

    { "platform":"all", "audience":"all", "notification":{"alert":"Hi, JPush",}, .... "callback": { "url":"https://***", // 可选字段； "params":{ // 可选 "name":"joe", "age":26 }, "type":3 // 可选，1: 送达回执, 2: 点击回执, 3: 送达和点击回执, 8: 推送成功回执, 9: 成功和送达回执, 10: 成功和点击回执, 11: 成功和送达以及点击回执 } }
              {
    "platform":"all",
    "audience":"all",
    "notification":{"alert":"Hi, JPush",},
    ....
    "callback": {
        "url":"https://***",  // 可选字段；
        "params":{          // 可选
            "name":"joe",
            "age":26
         },
         "type":3   // 可选，1: 送达回执, 2: 点击回执, 3: 送达和点击回执, 8: 推送成功回执, 9: 成功和送达回执, 10: 成功和点击回执, 11: 成功和送达以及点击回执
    }
}
    此代码块在浮窗中显示

    callback 包含如下字段：

    关键字 类型 选项 含义
    url string 可选 数据临时回调地址。
  • 指定后以此处指定为准，仅针对这一次推送请求生效。
  • 不指定，则以极光后台配置为准。
    • params JSON Object 可选 需要回调给用户的自定义参数
    type int 可选 回调数据类型。
  • 1: 送达回执
  • 2: 点击回执
  • 3: 送达和点击回执
  • 8: 推送成功回执
  • 9: 成功和送达回执
  • 10: 成功和点击回执
  • 11: 成功和送达以及点击回执

    • notification_3rd：自定义消息转厂商通知

    Push API 发起自定义消息类型的推送请求时，针对 Android 设备，如果 APP 长连接不在线，则消息没法及时的下发；针对这种情况，极光推出了“自定义消息转厂商通知”的功能。

    也就是说，针对用户一些重要的自定义消息，可以申请开通极光 VIP 厂商通道功能，开通后，通过 APP 长连接不在线时没法及时下发的消息，可以通过厂商通道下发以厂商通知形式展示，及时提醒到用户。极光内部会有去重处理，您不用担心消息重复下发问题。

    如需要开通此功能，请联系：商务客服

    示例：

    { "platform":"all", "audience":"all", "message":{"msg_content": "Hi,JPush",}, "notification_3rd": { "content": "Hi,JPush", "title": "msg", "channel_id": "channel001", "uri_activity": "cn.jpush.android.ui.OpenClickActivity", "uri_action": "cn.jpush.android.intent.CONNECTION", "badge_add_num": 1, "badge_set_num": 1, "badge_class": "com.test.badge.MainActivity", "sound": "sound", "extras":{ "news_id" : 134, "my_key" : "a value" } } }
              {
    "platform":"all",
    "audience":"all",
    "message":{"msg_content": "Hi,JPush",},
    "notification_3rd": {
        "content": "Hi,JPush",
        "title": "msg",
        "channel_id": "channel001",
        "uri_activity": "cn.jpush.android.ui.OpenClickActivity",
        "uri_action": "cn.jpush.android.intent.CONNECTION",
        "badge_add_num": 1,
        "badge_set_num": 1,
        "badge_class": "com.test.badge.MainActivity",
        "sound": "sound",
        "extras":{
            "news_id" : 134,
            "my_key" : "a value"
        }
    }
}
    此代码块在浮窗中显示
    • notification_3rd 包含如下字段：
    关键字 类型 选项 含义
    title string 可选
  • 补发通知标题，如果为空则默认为应用名称。
  • 支持设置个性化文案，详情参考 个性化文案推送 。
    • alternate_title string 可选
  • title 的备用文案,仅开启个性化文案功能时有效。
  • 当后台查询个性文案的属性值为空时，使用备用文案的值定义 title，详情参考 个性化文案推送 。
    		•
    content string 必填
  • 补发通知的内容，如果存在 notification_3rd 这个 key，content 字段不能为空，且值不能为空字符串。
  • 支持设置个性化文案，详情参考 个性化文案推送 。
    		•
    alternate_content string 可选
  • content 的备用文案，仅开启个性化文案功能时有效。
  • 当后台查询个性文案的属性值为空时，使用备用文案的值定义 content，详情参考 个性化文案推送 。
    		•
    intent JSON Object 可选 使用 intent 里的 url 指定点击通知栏后跳转的目标页面;
  • SDK＜422 的版本此字段值仅对走华硕通道和极光自有通道下发生效，不影响请求走其它厂商通道。
  • SDK≥422 的版本，API 推送时建议填写 intent 字段，否则点击通知可能无跳转动作。此字段支持以下三种类型:
    1. 跳转到目标页:
    intent:#Intent;action=action 路径;component= 包名 /Activity 全名;end
    （OPPO 和 FCM 通道必须传 "action 路径", 其他厂商必须传 "Activity 全名", 否则将出现对应厂商无法跳转问题）
    2. 跳转到 deeplink 地址:
    scheme://test?key1=val1&key2=val2
    3. 应用首页: intent:#Intent;action=android.intent.action.MAIN;end (固定为此地址)
    		•
    uri_activity string 可选
  • 用于指定开发者想要打开的 activity，值为 activity 节点的 “android:name”属性值。
  • 适配华为、小米、vivo 厂商通道跳转。
  • Jpush SDK≥V4.2.2，可不再填写本字段，仅设置 intent 字段即可。
    • uri_action string 可选
  • 用于指定开发者想要打开的 activity，值为 "activity"-"intent-filter"-"action" 节点的 "android:name" 属性值。
  • 适配 oppo、fcm 跳转。
  • Jpush SDK≥V4.2.2，可不再填写本字段，仅设置 intent 字段即可，但若需兼容旧版 SDK 必须填写该字段
    • badge_add_num int 可选
  • 设置角标数字累加值，在原角标的基础上进行累加，取值范围为：1-99。
  • 此属性目前仅针对华为 EMUI 8.0 及以上、小米 MIUI 6 及以上、vivo、荣耀设备走厂商通道时生效。
  • 此字段如果不填，表示不改变角标数字（小米设备由于系统控制，不论推送走极光通道下发还是厂商通道下发，即使不传递依旧是默认 +1 的效果）。
  • 若设置了取值范围内的数字，下一条通知栏消息配置的 badge_add_num 数据会和原角标数量进行相加，建议取值为1。
    举例：badge_add_num 取值为1，原角标数为2，发送此角标消息后，应用角标数显示为3。
  • 针对华为/荣耀通道，如果 badge_set_num 与 badge_add_num 同时存在，则以 badge_set_num 为准。
    		•
    badge_set_num int 可选
  • 设置角标数字固定值，取值范围为：1-99。
  • 此属性目前仅针对华为 EMUI 8.0 及以上、荣耀设备走厂商通道时生效，如果 badge_set_num 与 badge_add_num 同时存在，则以 badge_set_num 为准。
  • 取值范围为：1-99，若设置了取值范围内的数字，对应下一条通知栏消息配置的 badge_set_num 数字则为角标数值，举例：badge_set_num 取值为 1，无论应用之前角标数为多少，发送此角标消息后，应用角标数均显示为1。
    		•
    badge_class string 可选
  • 桌面图标对应的应用入口 Activity 类， 比如“com.test.badge.MainActivity”。
  • 仅华为和荣耀通道推送时生效，此值如果填写非主 Activity 类，以厂商限制逻辑为准。
  • 若需要实现角标累加功能，需配合 badge_add_num 使用，二者需要共存，缺少其一不可。
  • 若需要实现角标固定值功能，需配合 badge_set_num 使用，二者需要共存，缺少其一不可。
    		•
    sound string 可选
  • 填写 Android 工程中 /res/raw/ 路径下铃声文件名称，无需文件名后缀。
  • 注意：针对 Android 8.0 以上，当传递了 channel_id 时，此属性不生效。
    		•
    channel_id string 可选
  • 根据 channel ID 来指定通知栏展示效果，不超过 1000 字节。
  • Android 8.0 开始可以进行 NotificationChannel 配置 。
    • extras JSON Object 可选 扩展字段；这里自定义 JSON 格式的 Key / Value 信息，以供业务使用。
    • 使用说明
      • notification_3rd 只针对开通了厂商通道的用户生效；
      • notification 和 notification_3rd 不能同时有内容，如果这两块同时有内容，则会返回错误提示；
      • notification_3rd 的内容对 iOS 平台无效，只针对 Android 平台生效；
      • notification_3rd 是用作补发厂商通知的内容，只有当 message 部分有内容，才允许传递此字段，且要两者都不为空时，才会对离线的厂商设备转发厂商通道的通知。

    调用返回

    返回示例

    < HTTP/1.1 200 OK < Content-Type: application/json { "sendno": "0", "msg_id": "18100287008546343" }
              < HTTP/1.1 200 OK
< Content-Type: application/json
{
    "sendno": "0",
    "msg_id": "18100287008546343"
}
    此代码块在浮窗中显示

    错误码

    Code 描述 详细解释 HTTP Status Code
    1000 系统内部错误 服务器端内部逻辑错误，请稍后重试。 500
    1001 只支持 HTTP Post 方法 不支持 Get 方法。 405
    1002 缺少了必须的参数 必须改正，检查要求必填的参数是否未写 400
    1003 参数值不合法 必须改正，参数不合法的情况如：
  • Audience 参数中 tag，alias，registration_id 有空值。
  • 单发指定的 registration_id 非法或者格式错误。
  • live_activity 参数格式错误，参考 实时活动推送示例 。
    		• 400
    1004 验证失败 必须改正。检查 Appkey 与 MasterSecret，详情请看：调用验证 401
    1005 消息体太大 必须改正。
  • Android 平台 Notification+Message 长度限制为 4000 字节。
  • iOS Notification 中 “iOS”:{ } 及大括号内的总体长度不超过：3584 个字节（包括自定义参数和符号），iOS 的 Message 部分长度不超过 4000 字节。
    		• 400
    1008 app_key 参数非法 必须改正，请仔细对比你所传的 Appkey 是否与应用信息中的一致，是否多了空格。 400
    1009 推送对象中有不支持的 key 必须改正，提示：是否将 content-available 错误地写为 content_available，builder_id 错误地写为 build_id；除文档中指定的字段外，还需传递自定义的 key 请在 extras 中填写。 400
    1011 没有满足条件的推送目标
  • 请检查是否有设备满足 audience 的目标条件（别名与标签是否设置成功）；若客户端未完成 SDK 集成，服务端先做测试，需下载 demo 安装到手机上再做推送；第一次集成成功，若采用广播推送请等待 10 分钟。
  • 推送目标超过 255 天不活跃，被排除在推送目标之外。
    		•  400
    1012 符合当前条件的推送已超过限制
  • 定速推送超过限制。
  • 厂商配额不足。
    特别说明：假设指定一个小米用户的 RegistrationID 推送，请求时针对小米、OPPO 等厂商通道都指定了“ospush”参数，且 OPPO 厂商通道都配额已经用完，则推送也会返回 1012 错误，提示厂商配额不足。
    		• 400
    1016 参数非法
  • 可能是因为没有开通对应厂商系统通道权限，但传递了厂商系统特性参数导致。
  • 也可能是传递的其它参数所对应的功能权限未开通。
    		•  400
    1017 参数非法 一般是因为传递了互斥的多个系统通道参数属性导致。 400
    1018 参数非法 请检查 callback 回调参数指定的 URL 是否在极光官网配置。 400
    1019 参数非法 请检查 options.third_party_channel 中的策略字段 distribution/distribution_custom/distribution_fcm 与消息类型（通知 / 自定义）是否匹配。 400
    1020 只支持 HTTPS 请求 必须改正 404
    1030 内部服务超时 稍后重试，若多次重试无法成功，请联系 support@jiguang.cn 503
    1031 参数非法 实时活动消息不能和通知消息、自定义消息同时推送 503
    2002 API 调用频率超出该应用的限制 注意 API 频率控制 ，可联系极光商务或技术支持开通更高的 API 调用频率。 429
    2003 该应用 appkey 已被限制调用 API 联系技术支持查明限制原因和寻求帮助。 403
    2004 无权限执行当前操作 必须改正。当前调用 API 的源 ip 地址不在该应用的 ip 白名单中，请在官网应用设置中配置 IP 白名单。 403
    2005 信息发送量超出合理范围。 检测到目标用户累计发送消息量过大，超过合理的使用范围，需要检查业务逻辑或者联系技术支持。 403
    2006 非 VIP 用户。 接口只针对 VIP 用户开放。 403
    2007 无权调用此接口。 请联系商务开通使用权限。 403
    2008 广播推送超出频率限制 极光于 2020/03/10 对「广播推送」的频率进行限制，调整为 10 次每天，如需更高频率，请联系商务。 400
    2009 推送请求被限制 推送方式被系统限制；或者如果是厂商推送，请确认是否在厂商允许推送时间范围；更详细可以联系技术支持查明限制原因和寻求帮助。 400
    2010 推送请求被限制 推送内容包含黑词，或者推送总量超限。 400

    相关参考

    厂商通道 标题长度 内容长度 敏感词 其他说明
    极光通道                             不限制，但限制消息体总大小 不限制，但限制消息体总大小 根据安全包功能所配置的黑词 消息体大小限制参考 常见问题。
    华为通道 ＜ 40 个字符 ＜ 1024 字符 禁止携带政府，领导人名称、台独等相关内容 默认【营销通知】的权限为静默通知，静默推送没有声音、震动等提示。
    荣耀通道 不限制，但消息体总大小 ＜ 4096 字节 不限制，但消息体总大小 ＜ 4096 字节 禁止携带政府，领导人名称、台独等相关内容 -
    魅族通道 ＜ 32 个字符 ＜ 100 个字符 禁止特殊字符，如：#
  • 中英文字符均计算为 1 个字符。
  • 部分消息可能会存入魅族手机右上角【魅族消息盒子】中。
    		•
    小米通道 ＜ 50 个字符 ＜ 128 个字符 禁止特殊字符，如：#、>>
  • 中英文字符均计算为 1 个字符。
  • 部分消息可能会存在通知栏的不重要通知里。
    		•
    OPPO 通道 ＜ 32 个字符 ＜ 200 个字符 暂无说明
  • 中英文字符均计算为 1 个字符。
  • 默认关闭通知权限。
    		•
    vivo 通道 ＜ 40 个字符 ＜ 100 个字符
  • 禁止特殊字符，如：#、>>
  • 正式消息禁止：纯数字、纯英文、纯符号、符号加数字，测试、test、大括号、中括号等
  • 英文为 1 个字符，中文为 2 个字符。
  • 默认关闭通知权限。
  • 同设备 1 天内运营消息的推送条数不能超过 5 条。
  • 同设备 1 天内不能重复推送内容相同的运营消息。
    		•
    APNS 通道 ＜ 20 个字符（40 个英文字符）
  • 通知中心和锁屏状态最多显示 110 个字符，55 个汉字。
  • 顶部弹窗最多显示 62 个字符，31 个汉字，超过部分会显示省略号。
    		•  暂无 暂无
    文档内容是否对您有帮助？

    Copyright 2011-2022, jiguang.cn, All Rights Reserved. 粤ICP备12056275号-13 深圳市和讯华谷信息技术有限公司

    在文档中心打开