文档中心 合规指南 开发者社区
极光文档 > 极光推送 > REST API > 推送 API > 创建推送 API
极光文档 > 极光推送 > REST API > 推送 API > 创建推送 API
推送 API
最近更新：2024-10-17
展开全部

推送 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}}！", "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 } }, "hmos" : { "alert":"hmos alert", "title":"hmos titile", "intent": { "url":"scheme://test?key1=val1&key2=val2" }, "badge_add_num":1, "badge_set_num":1, "extras": { "age":18 }, "category":"IM", "test_message":false, "receipt_id":"abc1212", "large_icon":"https://www.jiguang.cn/largeIcon.jpg", "style":0, "push_type": 0 }, "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": { "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}}！",
        "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
            }
        },
        "hmos" : {
            "alert":"hmos alert",
            "title":"hmos titile",
            "intent": {
                "url":"scheme://test?key1=val1&key2=val2"
            },
            "badge_add_num":1,
            "badge_set_num":1,
            "extras": {
                "age":18
            },
            "category":"IM",
            "test_message":false,
            "receipt_id":"abc1212",
            "large_icon":"https://www.jiguang.cn/largeIcon.jpg",
            "style":0,
            "push_type": 0
        },
        "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": {
        "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 。
    android 可选 Android 平台上的通知，详见 android 。
    ios 可选 iOS 平台上 APNs 通知结构，详见 ios 。
    quickapp 可选 快应用平台上通知结构，详见 quickapp 。
    hmos 可选 鸿蒙平台上通知结构，详见 hmos 。
    voip 可选 iOS VOIP 功能。该类型推送支持和 iOS 的 Notification 通知并存，详见 voip 。
    message 可选
  • 消息内容体,是被推送到客户端的内容。
  • 与 notification 一起二者必须有其一，可以二者并存。
    		•
    inapp_message 可选
  • 面向于通知栏消息类型，需搭配notification参数一起使用，对于通知权限关闭的用户可设置启用此功能。
  • 不可与 message 同时并存。
    		•
    live_activity 可选
  • 实时活动内容体。
  • 不可与 notification 或 message 等并存。
    		•
    sms_message 可选 短信渠道补充送达内容体
    options 可选 推送参数
    callback 可选 回调参数
    notification_3rd 可选
  • 自定义消息转厂商通知内容体。
  • 与 message 一起使用。
    		•
    cid 可选 用于防止 api 调用端重试造成服务端的重复推送而定义的一个标识符，获取方法详见 高级功能 API。

    platform：推送平台

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

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


    推送到所有平台：

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

    指定特定推送平台：

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

    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!"
    }
}
    此代码块在浮窗中显示

    android

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

    支持的字段有：

    关键字 类型 选项 含义 说明
    alert string 必填 通知内容
  • 这里指定后会覆盖上级统一指定的 alert 信息。
  • 内容可以为空字符串，表示不展示到通知栏。
  • 各推送通道对此字段的限制详见 推送限制 。
    		•
    title string 可选 通知标题
  • 如果指定了，则通知里原来展示 App 名称的地方，将展示 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 字段，若有填充，则优先使用，若无填充则以本字段定义为准。
    		•
    category string 可选 通知栏消息分类条目
  • 完全依赖 rom 厂商对 category 的处理策略。
  • 说明1：华为从 2023.09.15 开始基于《华为消息分类标准》 对其本地通知进行管控推送，参考：《华为本地通知频次及分类管控通知》 ，此字段值对应华为「本地通知」category取值，开发者通过极光服务发起推送时如果传递了此字段值，请务必按照华为官方要求传递，极光会自动适配华为本地通知importance取值，无需开发者额外处理。
  • 说明2：考虑到一次推送包含多个厂商用户的情况，建议此处传递的字段值要和您APP开发代码中创建的channel效果对应（category值一致），最好创建新的channelId，避免曾经已经创建了无法修改。
  • 官方category分类取值规则也可参考华为消息分类对应表
    • priority int 可选 通知栏展示优先级
  • 默认为 0，范围为 -2～2。
  • 说明1：华为从 2023.09.15 开始基于《华为消息分类标准》 对其本地通知进行管控推送，参考：《华为本地通知频次及分类管控通知》 ，开发者通过极光服务发起推送时，如果有传递此字段值，请注意此字段要和 category 同时使用；反之，如果传了category，没传递此值时极光会自动帮您适配处理优先级。
  • priority = -2 时，对应华为本地通知 importance 级别为 IMPORTANCE_MIN；priority = 0 时，对应华为本地通知 importance 级别为 IMPORTANCE_DEFAULT。
  • 官方消息优先级取值规则也可参考华为消息分类对应表
  • 极光取值 -2 ～-1 对应 FCM 取值 normal，极光取值 0~2 对应 FCM 取值 high。
    		•
    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 兼容处理，详情参考 厂商通道无法跳转问题分析。
  • 当通知内容超过厂商的限制时，厂商通道会推送失败，可以在 extras 中配置 xx_content_forshort 参数传入对应厂商的通知内容，详情可展开表格查看。
    		•
    mipns_content_forshort string 可选 小米通知内容 由于小米官方的通知内容长度限制为128个字符以内（中英文都算一个），当通知内容（极光的“alert”字段的值）长度超过128时，小米通道会推送失败。此时调用极光api推送通知时，可使用此字段传入不超过128字符的通知内容作为小米通道通知内容。
    oppns_content_forshort string 可选 OPPO通知内容 由于OPPO官方的通知内容长度限制为200个字符以内（中英文都算一个），当通知内容（极光的“alert”字段的值）长度超过200时，OPPO通道会推送失败。此时调用极光api推送通知时，可使用此字段传入不超过200字符的通知内容作为OPPO通道通知内容。
    vpns_content_forshort string 可选 vivo通知内容 由于vivo官方的通知内容长度限制为100个字符以内（1个汉字等于2个英文字符），当通知内容（极光的“alert”字段的值）长度超过100时，vivo通道会推送失败。此时调用极光api推送通知时，可使用此字段传入不超过100字符的通知内容作为vivo通道通知内容。
    mzpns_content_forshort string 可选 魅族通知内容 由于魅族官方的通知内容长度限制为100个字符以内（中英文都算一个），当通知内容（极光的“alert”字段的值）长度超过100时，魅族通道会推送失败。此时调用极光api推送通知时，可使用此字段传入不超过100字符的通知内容作为魅族通道通知内容。
    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 字段展示。
    		•
    icon_bg_color string 可选 设置通知小图标背景色
  • 该字段仅对消息走极光通道下发生效。
  • 该字段能辅助解决部分设备小图标显示灰白情况，但最终还是依赖系统本身支持情况，建议开发者在设计UI图标时就做好适配工作。
  • 需要搭配 Android JPush SDK v5.5.0 及其以上版本使用。
    		•
    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_add_num”和“badge_set_num”都设置为空，则应用角标数字默认加1。
    		•
    badge_set_num int 可选 设置角标数字固定值
  • 此属性目前仅针对华为 EMUI 8.0 及以上、荣耀设备走厂商通道时生效，若 badge_set_num 与 badge_add_num 同时存在，则以 badge_set_num 为准；若“badge_add_num”和“badge_set_num”都设置为空，则应用角标数字默认加1。
  • 取值范围为：0-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。
    		•
    sound string 或 JSON Object 可选 通知提示声音或警告通知
  • 普通通知： string 类型，如果无此字段，则此消息无声音提示；有此字段，如果找到了指定的声音就播放该声音，否则播放默认声音，如果此字段为空字符串，iOS 7 为默认声音，iOS 8 及以上系统为无声音。说明：JPush 官方 SDK 会默认填充声音字段，提供另外的方法关闭声音，详情查看各 SDK 的源码。
  • 告警通知： JSON Object , 支持官方定义的 payload 结构，在该结构中包含 critical 、name 和 volume 等官方支持的 key 。
  • 自定义铃声说明：格式必须是 Linear PCM、MA4（IMA/ADPCM）、alaw，μLaw 的一种，将声频文件放到项目 bundle 目录中，且时长要求 30s 以下，否则就是系统默认的铃声，详见 自定义铃声。
    		•
    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;
}
    此代码块在浮窗中显示

    hmos

    鸿蒙（HarmonyOS）平台上的通知，JPush SDK 按照一定的通知栏样式展示。

    支持的字段有：

    关键字 类型 选项 含义 说明
    alert string 必填 通知内容
  • 这里指定后会覆盖上级统一指定的 alert 信息。
  • 内容不可以是空字符串，否则推送厂商会返回失败。
    		•
    title string 可选 通知标题
  • 如果指定了，则通知里原来展示 App 名称的地方，将展示 title。否则使用WebPortal配置的默认title。
    		•
    category string 必填 通知栏消息分类条目
  • 此字段由于厂商为必填字段，效果也完全依赖 rom 厂商对 category 的处理策略，请开发者务必填写。极光内部对此字段实际未进行必填校验，请开发者按照必填处理。
  • 此字段值对应官方「云端category」取值，开发者通过极光服务发起推送时如果传递了此字段值，请务必按照官方要求传递，官方category分类取值规则也可参考鸿蒙消息分类标准
    • large_icon string 可选 通知栏大图标
  • 要求传递网络地址，使用HTTPS协议，取值样例：https://example.com/image.png。
  • 图标大小不超过 30 k，图片长*宽<12800像素。
    		•
    intent JSON Object 可选 指定跳转页面 支持跳转到应用首页、deeplink 地址和Action跳转三种类型：
    1. 跳转应用首页：固定 action.system.home
    2. 跳转到 deeplink 地址: scheme://test?key1=val1&key2=val2
    3. 跳转到 action 地址: com.test.action
    badge_add_num int 可选 设置角标数字累加值
  • 此字段如果不填，表示不改变角标数字
  • 取值范围为：1-99，若设置了取值范围内的数字，下一条通知栏消息配置的 badge_add_num 数据会和原角标数量进行相加，建议取值为 1。
    举例：badge_add_num 取值为 1，原角标数为 2，发送此角标消息后，应用角标数显示为 3。
    		•
    badge_set_num int 可选 设置角标数字为固定值
  • 此字段如果不填，表示不改变角标数字
  • 取值范围为：0-99，若设置了取值范围内的数字，对应下一条通知栏消息配置的 badge_set_num 数字则为角标数值，举例：badge_set_num 取值为 1，无论应用之前角标数为多少，发送此角标消息后，应用角标数均显示为 1。
    		•
    test_message boolean 可选 测试消息标识 测试消息标识：
  • false：正常消息（默认值）
  • true：测试消息
    		•
    receipt_id string 可选 华为回执 ID 输入一个唯一的回执 ID 指定本次下行消息的回执地址及配置，该回执 ID 可以在鸿蒙回执参数配置中查看。
    extras JSON Object 可选 扩展字段
  • 这里自定义 JSON 格式的 Key / Value 信息，以供业务使用。
    		•
    style int 可选 通知栏样式类型
  • 默认为0，0:普通样式 2:多文本样式。
    		•
    inbox JSON Object 可选 多行文本样式
  • 对应 style 的取值类型 2。
    		•
    push_type int 可选 推送类型
  • 默认值 0，目前仅支持：0-通知消息，2-通知拓展消息，10-VoIP呼叫消息，其它值报错。
    		•
    extra_data string 可选 推送类型
  • 对应华为 extraData 字段，当 push_type=2 或 push_type=10 时生效，此时是必填的，push_type=0时忽略此字段。
    		•

    // 指定鸿蒙（HarmonyOS）平台推送： {"platform" : ["hmos"] } // 通知参数 { "notification" : { "hmos" : { "alert":"hmos alert", "title":"hmos titile", "intent": { "url":"scheme://test?key1=val1&key2=val2" }, "badge_add_num":1, "extras": { "age":18 }, "category":"IM", "test_message":false, "receipt_id":"abc1212", "large_icon":"https://www.jiguang.cn/largeIcon.jpg" } } }
              // 指定鸿蒙（HarmonyOS）平台推送：
{"platform" : ["hmos"] }

// 通知参数
{
    "notification" : {
        "hmos" : {
            "alert":"hmos alert",
            "title":"hmos titile",
            "intent": {
                "url":"scheme://test?key1=val1&key2=val2"
            },
            "badge_add_num":1,
            "extras": {
                "age":18
            },
            "category":"IM",
            "test_message":false,
            "receipt_id":"abc1212",
            "large_icon":"https://www.jiguang.cn/largeIcon.jpg"
        }
    }
}
    此代码块在浮窗中显示

    quickapp

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

    关键字 类型 选项 含义 说明
    title string 必填 通知标题
  • 必填字段，快应用推送通知的标题。
    		•
    alert string 必填 通知内容
  • 这里指定了，则会覆盖上级统一指定的 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 处于前台。
    • 鸿蒙平台（HarmonyOS）从 2024.08.13 开始支持自定义消息，对应 JPush HarmonyOS SDK v1.1.0 版本。

    消息包含如下字段：

    关键字 类型 选项 含义
    msg_content string 必填
  • 消息内容本身。
    		•
    title string 可选
  • 消息标题。
    • 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 面向于通知栏消息类型，需搭配 notification 参数一起使用，对于通知权限关闭的用户可设置启用此功能。此功能启用后，当用户前台运行 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 P8 证书，对应极光 WebPortal 集成设置中 iOS 鉴权方式需要选择「Token Authentication配置」方式。

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

    关键字 类型 选项 说明
    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的消息标题。
    body string 可选 显示到Apple Watch的消息内容。
    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}}", "body":"Hi, {{nickname}}!", "sound":"default" }, "dismissal-date": 1168364460 } }, "options": { "apns_production": false } }
              {
    "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}}",
                "body":"Hi, {{nickname}}!",
                "sound":"default"
            },
            "dismissal-date": 1168364460
        }  
    },
    "options": {
        "apns_production": false
    }
}
    此代码块在浮窗中显示

    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 说明 。
    classification int 可选 消息类型分类 极光不对指定的消息类型进行判断或校准，会以开发者自行指定的消息类型适配 Android 厂商通道。不填默认为 0。
  • 0：代表运营消息。
  • 1：代表系统消息。
  • 此字段优先级最高，会覆盖 options.third_party_channel.vivo.classification 设置的值。
    		•
    target_event JSON Array 可选 目标转化事件 目标转化事件支持传递「自定义事件」和「极光预置事件」，目前支持Android和iOS平台（要求JPush SDK ≥ 5.0.0 ，且JCore ≥ 4.2.0），支持通知消息和应用内消息两种消息类型。
  • 自定义事件：需集成极光分析SDK，开发者在极光分析产品中自行创建的业务事件（如：加入购物车、浏览商品等），详情参考 如何创建自定义事件 和 SDK如何上报自定义事件
  • 极光预置事件：极光推送SDK默认支持，无需开发者创建，也无需集成极光分析SDK，系统已预置；目标支持的预置事件有2个：jg_app_show（应用切换到前台）、jg_app_hide（应用切换到后台）。
  • 代码示例：{"options": {"target_event": ["jg_app_show"]}}
    • test_message boolean 可选 是否测试消息标识 优先级大于 hmos 通知体内的 test_message 字段（同样适配鸿蒙自定义消息，如果推送鸿蒙自定义消息，请传递此字段）
    receipt_id string 可选 回执ID 优先级大于 hmos 通知体内的 receipt_id 字段（同样适配鸿蒙自定义消息，如果推送鸿蒙自定义消息，请传递此字段）
    active_push boolean 可选 是否使用亮屏推送 true-使用亮屏推送，false-不使用亮屏推送，默认值false。
  • 此功能为增值付费服务，需要额外申请权限。
  • 当使用亮屏推送时，建议同时设置need_backup=true。
  • 此功能仅支持单纯通知消息，不支持自定义消息或者通知+自定义消息推送，否则请求会返回 code 码 1035。
  • 此功能不支持定速推送，否则请求会返回 code 码 1035。
  • 亮屏推送支持的时间范围是每天 7:00 - 22:00
  • 亮屏推送对于Android厂商用户的下发策略固定为在线走极光，离线走厂商。
    • need_backup boolean 可选 使用亮屏推送兜底策略 true-使用亮屏兜底策略，false-不使用亮屏兜底策略，默认值false。
  • 若此字段指定为true，则active_push字段值必须为true。
  • 是否使用兜底策略主要是确认离线消息到期后的处理逻辑。
  • 当使用兜底策略下发时：如果是厂商用户（离线消息到期后 0-5 分钟之内通过厂商通道下发），如果是非厂商用户（离线消息到期后，如果用户是在线状态则直接下发；如果用户离线则丢弃）。
    例如上午 8 点推送此条消息，设置了离线时间 2 小时。在 8:00 - 10:00 内，设备亮屏则会触发消息下发。剩余未发送的用户，在到达10:00后，0-5 分钟之内剩余消息走厂商通道下发。
  • 当不使用兜底策略下发时：离线消息到期后未下发的直接丢弃，不区分是否厂商用户。
    		•
    business_operation_code string 可选 推送计划标识 需先通过极光 WebPortal 创建计划标识值，创建步骤参考推送计划文档。

    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 的定义为准。
  • 特别注意：由于 OPPO 厂商 2024.11.20 实施OPPO消息分类新规，建议您同时填写此字段和下面的category、notify_level字段。
    		•
    skip_quota boolean 可选 配额判断及扣除 是否跳过配额判断及扣除，目前仅对小米和 oppo 有效，默认为 false。
  • true:表示跳过判断及跳过扣除极光侧的配额。
  • false:表示不跳过判断及跳过扣除极光侧的配额。
    		•
    classification int 可选 通知栏消息分类 vivo 手机厂商通知栏消息分类，不填默认为 0。
  • 此字段优先级较低，会被 options.classification 设置的值覆盖，请您务必设置 options.classification 值。
  • 0：代表运营消息。
  • 1：代表系统消息。
    目前 vivo 对系统消息分类较为严格，具体规则参考：vivo。

    关于 classification 和 skip_quota 字段说明：
  • 不传递 classification 字段，但传递 skip_quota 时，应用是否扣除配额以客户传递的 skip_quota 为准，需开发者自己管理配额。
  • 传递 classification 时，会忽略 skip_quota 值，极光会按照 厂商「系统消息」、「运营消息」分类 规则自动判断是否扣除配额，帮助开发者管理配额。
    		•
    push_mode int 可选 通知栏消息类型 对应 vivo 的 pushMode 字段，不填默认为 0。详情参考：vivo pushMode。
  • 0：表示正式推送。
  • 1：表示测试推送。
    		•
    importance string 可选 华为、荣耀通知栏消息智能分类 为了适配华为、荣耀手机厂商的通知栏消息智能分类，对应华为/荣耀的「云端通知」importance 字段，不填充则不下发，参考： 华为通知消息智能分类 、 荣耀通知消息分类标准。
  • LOW：一般消息。
  • NORMAL：重要消息。
  • HIGH：非常重要消息（仅华为支持）。
  • 说明1：华为从 2023.09.15 开始基于《华为消息分类标准》对其云端通知和本地通知进行共同管控推送，开发者通过极光服务发起推送时，请注意此字段传值要符合华为官方「云端通知 importance」取值要求，要和「华为云端通知 category」取值要求对应。
    		•
    category string 可选 华为、vivo、OPPO 厂商消息场景标识 为了适配华为、vivo、OPPO 手机厂商消息，用于标识「云端通知」消息类型，确定消息提醒方式，对特定类型消息加快发送。
  • 对应值及其说明参考：华为 category 值说明 、vivo 分类标准。
  • oppo category 值说明
  • 说明1：华为需完成 自分类权益申请 。
  • 说明2：华为从 2023.09.15 开始基于《华为消息分类标准》对其云端通知和本地通知进行共同管控推送，开发者通过极光服务发起推送时，请注意此字段传值要符合华为官方「华为云端通知 category」取值要求。
  • 说明3：vivo 具体规则参考 vivo 官方说明。
  • 说明4：OPPO于2024.11.20实施消息分类新规，具体规则参考 OPPO 官方说明。
    		•
    notify_level int 可选 OPPO通知栏消息提醒等级
  • 说明1：官方取值定义：1-通知栏、2-通知栏+锁屏、16-通知栏+锁屏+横幅+震动+铃声；请开发者按照官网定义传递，极光仅做透传处理。
  • 说明2：根据官方说明 notify_level 字段，仅对「服务与通讯类」消息生效
  • 说明3：使用notify_level参数时，category参数必传
    		•
    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”需要向华为申请特殊权限，参考： 特殊权限如何申请 。
    		•
    receipt_id string 可选 华为回执 ID
  • 仅华为通道有效。
  • 输入一个唯一的回执 ID 指定本次下行消息的回执地址及配置，该回执 ID 可以在 华为回执参数配置 中查看。
    		•
    callback_id string 可选 vivo回执 ID
  • 仅vivo通道有效。
  • 输入一个唯一的回执 ID 指定本次下行消息的回执地址及配置，该回执 ID 可以在 vivo回执参数配置 中查看。
    		•
    target_user_type int 可选 华为消息类型 仅华为通道有效。
  • 0：普通消息（默认值）
  • 1：测试消息。每个应用每日可发送该测试消息 500 条且不受 每日单设备推送数量上限要求 。
    		•
    large_icon string 可选 厂商消息大图标样式
  • 支持华为 / 荣耀 / oppo 厂商，使用详情参见 设置图标文档 。
  • 优先使用厂商字段， 厂商字段没有填充，则使用 android 里面定义 large_icon 字段 android 内的 large_icon。
  • 小米从 2023.08 开始不再支持推送时动态设置小图标、右侧图标、大图片功能。
  • 华为、荣耀支持极光的 media_id 及网络 https 路径。
  • oppo 支持极光的 media_id 及 oppo 厂商的大图标 id。
  • JPush Android SDK v3.9.0 版本以上才支持该字段。
    		•
    small_icon_uri string 可选 厂商消息小图标样式
  • 目前支持华为 / 荣耀厂商，使用详情参见 设置图标文档 。
  • 优先使用厂商字段， 厂商字段没有填充，则使用 android 内的 small_icon_uri 字段。
  • 华为、荣耀支持极光的 media_id 及厂商本地路径。(小米从 2023.08 开始不再支持推送时动态设置小图标、右侧图标、大图片功能，建议开发者不要继续使用小米相关特性功能)。
    		•
    small_icon_color string 可选 小米厂商小图标样式颜色
  • 为了适配小米厂商的消息小图标样式颜色，不填充默认是灰色 (小米官方后续不在支持自定义小图标，建议开发者不要继续使用小米 small icon 相关特性功能)。
  • JPush Android SDK v3.9.0 版本以上才支持该字段。
    小米从 2023.08 开始不再支持推送时动态设置小图标、右侧图标、大图片功能，开发者可不在设置此字段值。
    		•
    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 里面设置的样式。
    		•
    auditResponse JSONObject 可选 基于第三方审核结果 目前支持 华为 / OPPO / vivo 厂商。
  • 此处直接使用第三方审核结果的返回值原数据填充即可，开发者无需关心各个厂商原始协议，对应推必安信息审核api响应内容，详见推必安官方文档
  • 华为官方说明参考 基于第三方审核结果的消息推送
  • OPPO官方说明参考 基于第三方审核结果的消息推送
  • vivo官方说明参考 基于第三方审核结果的消息推送

    • 示例：

    "third_party_channel":{ "xiaomi":{ "distribution":"jpush", "channel_id":"*******", "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, "auditResponse":{ "code": 200, "ts": 1659421654502, "requestId": "9221dbbaxxxxx", "msg": "ok", "data": { "accessToken": "IDp7WVJyJVgOUQwNbDkPAXlbCkd7LWAxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "expiresIn": 604800 } } }, "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, "auditResponse":{ "code": 200, "ts": 1659421654502, "requestId": "9221dbbaxxxxx", "msg": "ok", "data": { "accessToken":"IDp7WVJyJVgOUQwNbDkPAXlbCkd7LWAxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "expiresIn": 604800 } } }, "vivo":{ "distribution":"jpush", "classification": 0, "distribution_fcm":"secondary_pns_push", "push_mode":0, "auditResponse":{ "code": 200, "ts": 1659421654502, "requestId": "9221dbbaxxxxx", "msg": "ok", "data": { "accessToken":"IDp7WVJyJVgOUQwNbDkPAXlbCkd7LWAxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "expiresIn": 604800 } } } } 
              "third_party_channel":{
    "xiaomi":{
              "distribution":"jpush", 
              "channel_id":"*******", 
              "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,
              "auditResponse":{
                    "code": 200,
                    "ts": 1659421654502,
                    "requestId": "9221dbbaxxxxx",
                    "msg": "ok",
                    "data": {
                    "accessToken":
                        "IDp7WVJyJVgOUQwNbDkPAXlbCkd7LWAxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
                        "expiresIn": 604800
                    }
              } 
    },
    "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,
              "auditResponse":{
                    "code": 200,
                    "ts": 1659421654502,
                    "requestId": "9221dbbaxxxxx",
                    "msg": "ok",
                    "data": {
                        "accessToken":"IDp7WVJyJVgOUQwNbDkPAXlbCkd7LWAxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
                        "expiresIn": 604800
                    }
               } 
    },
    "vivo":{
            "distribution":"jpush",
            "classification": 0,
            "distribution_fcm":"secondary_pns_push", 
            "push_mode":0,
            "auditResponse":{
                "code": 200,
                "ts": 1659421654502,
                "requestId": "9221dbbaxxxxx",
                "msg": "ok",
                "data": {
                    "accessToken":"IDp7WVJyJVgOUQwNbDkPAXlbCkd7LWAxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
                    "expiresIn": 604800
                }
            } 
    }
}
    此代码块在浮窗中显示

    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 可选
  • 补发通知标题，如果为空则默认为应用名称。
    		•
    content string 必填
  • 补发通知的内容，如果存在 notification_3rd 这个 key，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 可选
  • 设置角标数字固定值，取值范围为：0-99。
  • 此属性目前仅针对华为 EMUI 8.0 及以上、荣耀设备走厂商通道时生效，如果 badge_set_num 与 badge_add_num 同时存在，则以 badge_set_num 为准。
  • 取值范围为：0-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 参数非法 实时活动消息不能和通知消息、自定义消息同时推送 400
    1033 参数非法 目标转化功能仅支持通知消息和应用内消息 400
    1035 参数非法 亮屏推送参数错误，可能原因：
  • 仅支持通知消息，您请求的含非通知消息内容
  • 兜底策略和亮屏推送策略不匹配
  • 离线消息保存时长不能为0
  • 亮屏推送不支持和big_push_duration定速推送搭配使用
  • 亮屏推送支持的时间范围是每天 7:00 - 22:00
    		•  400
    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 推送请求被限制
  • 推送方式被系统限制：设备标签调整为 VIP 功能，非 VIP 不能使用标签功能。
  • 如果是厂商推送，请确认是否在厂商允许推送时间范围。
  • 更详细可以联系技术支持查明限制原因和寻求帮助。
    		•  400
    2010 推送请求被限制 推送内容包含黑词，或者推送总量超限。 400
    2011 推送时间窗口限制 超出发送时间允许范围，请检查您在极光 WebPortal 配置的允许推送时间的窗口。 400

    相关参考

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

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

    在文档中心打开