Skip to end of metadata
Go to start of metadata

这是 Push API 最新的版本。

相比 API v2 版本,v3 版本的改进为:

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

推送概述

功能说明

向某单个设备或者某设备列表推送一条通知、或者消息。

推送的内容是 JSON 结构,其中包含平台信息,推送目标,通知内容,消息内容与可选参数。

调用地址

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

请求示例

返回示例

调用验证

HTTP Header(头)里加一个字段(Key/Value对):

其中 base64_auth_string 的生成算法为:base64(appKey:masterSecret)

即,对 appKey 加上冒号,加上 masterSecret 拼装起来的字符串,再做 base64 转换。

推送对象

一个推送对象,以 JSON 格式表达,包含一条推送相关的所有信息,最多包含以下五个方面:

关键字 含义
platform必填推送平台设置
audience必填推送设备指定
notification可选通知内容体。是被推送到客户端的内容。与 message 一起二者必须有其一,可以二者并存
message可选消息内容体。是被推送到客户端的内容。与 notification 一起二者必须有其一,可以二者并存
options可选推送参数

platform

JPush 当前支持 Android, iOS, Windows Phone 三个平台的推送。其关键字分别为:"android", "ios", "winphone"。

推送到所有平台:

指定特定推送平台:

 

audience

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

all

如果要发广播(全部设备),则直接填写 “all”。

推送目标

除广播外的设备选择方式,有如下几种:

关键字 含义值类型说明
tagJSON Array标签数组。多个标签之间是 OR 的关系,即取并集。

用标签来进行大规模的设备属性、用户属性分群。
一次推送最多 20 个。 

  • 有效的 tag 组成:字母(区分大小写)、数字、下划线、汉字。
  • 限制:长度限制为 40 字节。(判断长度需采用UTF-8编码)
tag_andJSON Array标签AND数组。多个标签之间是 AND 关系,即取交集。注册与 tag 区分。
一次推送最多 20 个。 
aliasJSON Array别名数组。多个别名之间是 OR 关系,即取并集。

用别名来标识一个用户。一个设备只能绑定一个别名,但多个设备可以绑定同一个别名。
一次推送最多 1000 个。 

  • 有效的 alias 组成:字母(区分大小写)、数字、下划线、汉字。
  • 限制:长度限制为 40 字节。(判断长度需采用UTF-8编码)
registration_idJSON Array注册ID数组。多个注册ID之间是 OR 关系,即取并集。设备标识。
一次推送最多 1000 个。 

每种类型的值都是数组(Array),数组里多个值之间隐含的关系是是 OR,即取并集。但 tag_and 不同,其数组里多个值之间是 AND 关系,即取交集。

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

这几种类型可以并存。并存时多项的隐含关系是 AND,即取交集。

示例
  • 推送给全部(广播):
  • 推送给多个标签(只要在任何一个标签范围内都满足):在深圳、广州、或者北京
  • 推送给多个标签(需要同时在多个标签范围内):在深圳并且是“女”
  • 推送给多个别名:
  • 推送给多个注册ID:
  • 可同时推送指定多类推送目标:在深圳或者广州,并且是 ”女“ “会员”

notification

“通知”对象,是一条推送的实体内容对象之一(另一个是“消息”),是会作为“通知”推送到客户端的。

其下属属性包含 4 种,3 个平台属性,以及一个 "alert" 属性。

alert

通知的内容在各个平台上,都可能只有这一个最基本的属性 "alert"。

这个位置的 "alert" 属性(直接在 notification 对象下),是一个快捷定义,各平台的 alert 信息如果都一样,则可不定义。如果各平台有定义,则覆盖这里的定义。

上面定义的 notification 对象,将被推送到 "platform" 指定的多个平台,并且其通知 alert 信息都一样。

android

Android 平台上的通知。

被 JPush SDK 按照一定的通知栏样式展示。

支持的字段有:

关键字  含义说明
alertstring必须通知内容这里指定了,则会覆盖上级统一指定的 alert 信息;内容可以为空字符串,则表示不展示到通知栏。这里不指定则上级 notification 必须指定。
titlestring可选通知标题如果指定了,则通知里原来展示 App名称的地方,将展示成这个字段。
builder_idint可选通知栏样式IDAndroid SDK 可设置通知栏样式,这里根据样式 ID 来指定该使用哪套样式。
extrasJSON Object可选扩展字段。这里自定义 JSON 格式的 Key/Value 信息,以供业务使用。
ios

iOS 平台上 APNs 通知。

该通知内容会由 JPush 代理发往 Apple APNs 服务器,并在 iOS 设备上在系统通知的方式呈现。

该通知内容满足 APNs 的规范,支持的字段如下:

关键字  含义说明
alertstring必须通知内容这里指定了,将会覆盖上级统一指定的 alert 信息;内容为空则不展示到通知栏。支持 emoji 表情。这里不指定则上级 notification 必须指定。
soundstring可选通知提示声音

如果无此字段,则此消息无声音提示;有此字段,如果找到了指定的声音就播放该声音,否则播放默认声音。

(info) 说明:JPush 官方 API Library (SDK) 会默认填充声音字段。提供另外的方法关闭声音。

badgestring可选应用角标

如果不填,表示不改变角标数字;否则把角标数字改为指定的数字;为 0 表示清除。
新增支持 "+1" 功能,详情参考:http://blog.jpush.cn/ios_apns_badge_plus/

(info) 说明:JPush 官方 API Library (SDK) 会默认填充 badge 值为 "+1"。提供另外的方法不变更 badge 值。

content-availableboolean可选静默推送标志如果为 1 表示要静默推送。
extrasJSON Object可选扩展字段这里自定义 Key/value 信息,以供业务使用。

iOS 通知 JPush 要转发给 APNs 服务器。APNs 协议定义通知长度为 255 字节。JPush 因为需要重新组包,并且考虑一点安全冗余,要求 “iOS”:{ } 内的总体长度不超过:220 个字节。

另外,JPush 在推送时使用 utf-8 编码,所以一个汉字占用 3 个字节长度。

winphone

Windows Phone 平台上的通知。

该通知由 JPush 服务器代理向微软的 MPNs 服务器发送,并在 Windows Phone 客户端的系统通知栏上展示。

该通知满足 MPNs 的相关规范。当前 JPush 仅支持 toast 类型:

关键字  含义说明
alertstring必须通知内容

会填充到 toast 类型 text2 字段上。
这里指定了,将会覆盖上级统一指定的 alert 信息;内容为空则不展示到通知栏。这里不指定则上级 notification 必须指定。

titlestring可选通知标题会填充到 toast 类型 text1 字段上。
_open_pagestring可选点击打开的页面名称点击打开的页面。会填充到推送信息的 param 字段上,表示由哪个 App 页面打开该通知。可不填,则由默认的首页打开。
extrasJSON Object可选扩展字段作为参数附加到上述打开页面的后边。

 

message

应用内消息。或者称作:自定义消息,透传消息。

此部分内容不会展示到通知栏上,JPush SDK 收到消息内容后透传给 App。App 需要自行处理。

iOS 平台上,有此部分内容,才会推送应用内消息通道。

Windows Phone 平台上,暂时不支持应用内消息。

消息包含如下字段:

关键字  含义说明
msg_contentstring必填消息内容本身 
titlestring可选消息标题 
content_typestring可选消息内容类型 
extrasJSON Object可选JSON 格式的可选参数 

notification 与 message 并存(一次推送都发)时,Android 1.6.2及以下版本 只能收到通知部分,message 部分暂未时透传给 App。 Android 1.6.3及以上SDK 版本已做相应调整。

只有iOS 1.7.3及以上的版本才能正确解析v3的message。

options

推送可选项。

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

关键字  含义说明
sendnoint可选推送序号纯粹用来作为 API 调用标识,API 返回时被原样返回,以方便 API 调用方匹配请求与返回。
time_to_liveint可选离线消息保留时长推送当前用户不在线时,为该用户保留多长时间的离线消息,以便其上线时再次推送。默认 86400 (1 天),最长 10 天。设置为 0 表示不保留离线消息,只有推送当前在线的用户可以收到。
override_msg_idlong可选要覆盖的消息ID如果当前的推送要覆盖之前的一条推送,这里填写前一条推送的 msg_id 就会产生覆盖效果,即:1)该 msg_id 离线收到的消息是覆盖后的内容;2)即使该 msg_id Android 端用户已经收到,如果通知栏还未清除,则新的消息内容会覆盖之前这条通知;覆盖功能起作用的时限是:1 天。
如果在覆盖指定时限内该 msg_id 不存在,则返回 1003 错误,提示不是一次有效的消息覆盖操作,当前的消息不会被推送。
apns_productionboolean可选APNs是否生产环境

默认推送生产环境。False 表示要推送测试环境。 

(info) JPush 官方 API LIbrary (SDK) 把默认值设置为了 “开发环境”。

 

调用返回

HTTP 状态码

参考文档:HTTP-Status-Code

业务返回码

Code描述详细解释实际提示信息HTTP Status Code
1000系统内部错误服务器端内部逻辑错误,请稍后重试。 500
1001只支持 HTTP Post 方法不支持 Get 方法。 405
1002缺少了必须的参数必须改正。 400
1003参数值不合法必须改正。 400
1004验证失败必须改正,详情请看:调用验证 401
1005消息体太大

必须改正。

通知 “iOS”:{ } 内的总体长度不超过:220 个字节(包括自定义参数和符号)。

JPush 的 消息加通知 部分长度不超过 1K 字节。

 400
1008app_key 参数非法必须改正。 400
1011没有满足条件的推送目标请检查audience 400
1020只支持 HTTPS 请求必须改正。 404
1030内部服务超时稍后重试 503

其他参考

 

Labels
  • None