JPush相关概念
连接极光服务器前提
在连接极光服务器之前需要先将APP进行注册，连接Server时需要用到下发的两个字段： AppKey：应用唯一标识。 Master Secret：服务器秘钥，用于服务器端调用API请求时对发送内容做签名。 客户端调用时传输这两个字段进行验证 HTTP Header（头）里加一个字段（Key/Value对）： Authorization: Basic base64authstring 其中 base64authstring 的生成算法为：base64(appKey:masterSecret) 即，对 appKey 加上冒号，加上 masterSecret 拼装起来的字符串，再做 base64 转换。
消息形式
JPush提供四种消息形式：通知，自定义消息，富媒体和本地通知。 通知 或者说 Push Notification，即指在手机的通知栏（状态栏）上会显示的一条通知信息。 通知主要用于提示用户的目的，应用于新闻内容、促销活动、产品信息、版本更新提醒、订单状态提醒等多种场景 自定义消息 自定义消息不是通知，所以不会被SDK展示到通知栏上。其内容完全由开发者自己定义。 自定义消息主要用于应用的内部业务逻辑。一条自定义消息推送过来，有可能没有任何界面显示。 富媒体 JPush支持开发者发送图文并茂的通知，从而更好的传达信息，带来更丰富的用户互动。 JPush提供了5种模板，开发者可以通过填充模板的内容，发送landing page、弹窗、信息流形式的富媒体通知。 开发者还可以直接通过URL发送预先编辑好的页面。 富媒体当前支持Android平台，为更好的使用富媒体的功能，建议更新当前SDK版本至v2.1.8及以上。 暂时只能通过极光推送的控制台发送，不支持API形式。 本地通知 本地通知API不依赖于网络，无网条件下依旧可以触发；本地通知的定时时间是自发送时算起的，不受中间关机等操作的影响。 本地通知与网络推送的通知是相互独立的，不受保留最近通知条数上限的限制。 本地通知适用于在特定时间发出的通知，如一些Todo和闹钟类的应用，在每周、每月固定时间提醒用户回到应用查看任务。
名词解释
设备标识 Registration ID 集成了 JPush SDK 的应用程序在第一次 App 启动后，成功注册到 JPush 服务器时，JPush 服务器会给客户端返回唯一的该设备的标识 – RegistrationID。JPush SDK 会以广播的形式发送 RegistrationID 到应用程序。 有了这个标识，App 编程可以把这个 RegistrationID 保存到自己的应用服务器上，然后就可以根据 RegistrationID 来向设备推送消息或者通知。 RegistrationID在卸载重装后是否可变：http://blog.jiguang.cn/registrationid/
别名 alias 为安装了应用程序的用户，取个别名来标识。以后给该用户 Push 消息时，就可以用此别名来指定。每个用户只能指定一个别名。 同一个应用程序内，对不同的用户，建议取不同的别名。这样，尽可能根据别名来唯一确定用户。 系统不限定一个别名只能指定一个用户。如果一个别名被指定到了多个用户，当给指定这个别名发消息时，服务器端API会同时给这多个用户发送消息。 举例：在一个用户要登录的游戏中，可能设置别名为 userid。游戏运营时，发现该用户 3 天没有玩游戏了，则根据 userid 调用服务器端API发通知到客户端提醒用户。 标签 tag 为安装了应用程序的用户，打上标签。其目的主要是方便开发者根据标签，来批量下发 Push 消息。 可为每个用户打多个标签。 举例： game, old_page, women 用户分群 用户分群的筛选条件有：标签、地理位置、系统版本、注册时间、活跃用户和在线用户。 开发者可以通过在控制台（官网）设置好用户分群之后，在控制台推送时指定该分群的名称或使用API调用该分群的id发送。 比如，开发者可以设置这样的用户分群：位于北京、上海、广州和深圳，并且最近7天在线的用户。
推送对象
一个推送对象，以 JSON 格式表达，表示一条推送相关的所有信息。 关键字 选项 含义 platform 必填 推送平台设置 audience 必填 推送设备指定 notification 可选 通知内容体。是被推送到客户端的内容。与 message 一起二者必须有其一，可以二者并存 message 可选 消息内容体。是被推送到客户端的内容。与 notification 一起二者必须有其一，可以二者并存 sms_message 可选 短信渠道补充送达内容体 options 可选 推送参数 cid 可选 用于防止 api 调用端重试造成服务端的重复推送而定义的一个标识符。
示例与说明
关键字 | 选项 | 含义 |
|---|---|---|
platform | 必填 | 推送平台设置 |
audience | 必填 | 推送设备指定 |
notification | 可选 | 通知内容体。是被推送到客户端的内容。与 message 一起二者必须有其一，可以二者并存 |
message | 可选 | 消息内容体。是被推送到客户端的内容。与 notification 一起二者必须有其一，可以二者并存 |
sms_message | 可选 | 短信渠道补充送达内容体 |
options | 可选 | 推送参数 |
cid | 可选 | 用于防止 api 调用端重试造成服务端的重复推送而定义的一个标识符。 |
{
"cid": "8103a4c628a0b98974ec1949-711261d4-5f17-4d2f-a855-5e5a8909b26e",
"platform": "all",
"audience": {
"tag": [
"深圳",
"北京"
]
},
"notification": {
"android": {
"alert": "Hi, JPush!",
"title": "Send to Android",
"builder_id": 1,
"extras": {
"newsid": 321
}
},
"ios": {
"alert": "Hi, JPush!",
"sound": "default",
"badge": " 1",
"extras": {
"newsid": 321
}
}
},
"message": {
"msg_content": "Hi,JPush",
"content_type": "text",
"title": "msg",
"extras": {
"key": "value"
}
},
"sms_message":{
"content":"sms msg content",
"delay_time":3600
},
"options": {
"time_to_live": 60,
"apns_production": false,
"apns_collapse_id":"jiguang_test_201706011100"
}
}platform
JPush 当前支持 Android, iOS, Windows Phone 三个平台的推送。其关键字分别为："android", "ios", "winphone"。 推送到所有平台： { "platform" : "all" } 指定特定推送平台： { "platform" : ["android", "ios"] }
audience
推送设备对象，表示一条推送可以被推送到哪些设备列表。确认推送设备对象，JPush 提供了多种方式，比如：别名、标签、注册ID、分群、广播等。 all 如果要发广播（全部设备），则直接填写 “all”。
推送形式
单播(unicast) 向指定的设备发送消息，包括向单个devicetoken或者单个alias发消息。 列播（listcast) 向指定的一批设备发送消息，包括向多个devicetoken或者多个alias发消息。 广播(broadcast) 向安装该App的所有设备发送消息（对 app_key 下的所有用户推送消息。）
推送目标(即设备)
广播外的设备选择方式，有如下几种：
关键字 | 类型 | 含义 | 说明 | 备注 |
|---|---|---|---|---|
tag | JSON Array | 标签OR | 数组。多个标签之间是 OR 的关系，即取并集。 | 用标签来进行大规模的设备属性、用户属性分群。 一次推送最多 20 个。 有效的 tag 组成：字母（区分大小写）、数字、下划线、汉字、特殊字符@!#$&* =.|￥。 限制：每一个 tag 的长度限制为 40 字节。（判断长度需采用UTF-8编码） |
tag_and | JSON Array | 标签AND | 数组。多个标签之间是 AND 关系，即取交集。 | 注意与 tag 区分。一次推送最多 20 个。 |
tag_not | JSON Array | 标签NOT | 数组。多个标签之间，先取多标签的并集，再对该结果取补集。 | 一次推送最多 20 个。 |
alias | JSON Array | 别名 | 数组。多个别名之间是 OR 关系，即取并集。 | 用别名来标识一个用户。一个设备只能绑定一个别名，但多个设备可以绑定同一个别名。一次推送最多 1000 个。 有效的 alias 组成：字母（区分大小写）、数字、下划线、汉字、特殊字符@!#$&* =.|￥。 限制：每一个 alias 的长度限制为 40 字节。（判断长度需采用UTF-8编码） |
registration_id | JSON Array | 注册ID | 数组。多个注册ID之间是 OR 关系，即取并集。 | 设备标识。一次推送最多 1000 个。 |
segment | JSON Array | 用户分群ID | 在页面创建的用户分群的 ID。定义为数组，但目前限制一次只能推送一个。 | 目前限制是一次只能推送一个。 |
abtest | JSON Array | A/B Test ID | 在页面创建的 A/B 测试的 ID。定义为数组，但目前限制是一次只能推送一个。 | 目前限制一次只能推送一个。 |
- 有效的 tag 组成：字母（区分大小写）、数字、下划线、汉字、特殊字符@!#$&* =.|￥。
- 限制：每一个 tag 的长度限制为 40 字节。（判断长度需采用UTF-8编码）
tag_and JSON Array 标签AND 数组。多个标签之间是 AND 关系，即取交集。 注意与 tag 区分。一次推送最多 20 个。 tag_not JSON Array 标签NOT 数组。多个标签之间，先取多标签的并集，再对该结果取补集。 一次推送最多 20 个。 alias JSON Array 别名 数组。多个别名之间是 OR 关系，即取并集。 用别名来标识一个用户。一个设备只能绑定一个别名，但多个设备可以绑定同一个别名。一次推送最多 1000 个。
- 有效的 alias 组成：字母（区分大小写）、数字、下划线、汉字、特殊字符@!#$&* =.|￥。
- 限制：每一个 alias 的长度限制为 40 字节。（判断长度需采用UTF-8编码）
registration_id JSON Array 注册ID 数组。多个注册ID之间是 OR 关系，即取并集。 设备标识。一次推送最多 1000 个。 segment JSON Array 用户分群ID 在页面创建的用户分群的 ID。定义为数组，但目前限制一次只能推送一个。 目前限制是一次只能推送一个。 abtest JSON Array A/B Test ID 在页面创建的 A/B 测试的 ID。定义为数组，但目前限制是一次只能推送一个。 目前限制一次只能推送一个。
示例
推送给全部（广播）：
代码语言：javascript复制{
"platform": "all",
"audience" : "all",
"notification" : {
"alert" : "Hi, JPush!",
"android" : {},
"ios" : {
"extras" : { "newsid" : 321}
}
}
}推送给多个标签（只要在任何一个标签范围内都满足）：在深圳、广州、或者北京
代码语言：javascript复制{
"audience" : {
"tag" : [ "深圳", "广州", "北京" ]
}
}推送给多个标签（需要同时在多个标签范围内）：在深圳并且是“女”
代码语言：javascript复制{
"audience" : {
"tag_and" : [ "深圳", "女" ]
}
}推送给多个别名：
代码语言：javascript复制{
"audience" : {
"alias" : [ "4314", "892", "4531" ]
}
}推送给多个注册ID：
代码语言：javascript复制{
"audience" : {
"registration_id" : [ "4312kjklfds2", "8914afd2", "45fdsa31" ]
}
}可同时推送指定多类推送目标：在深圳或者广州，并且是 “女” “会员”
代码语言：javascript复制{
"audience" : {
"tag" : [ "深圳", "广州" ]
"tag_and" : [ "女", "会员"]
}
}notification
推送实体内容对象=通知(notification) 消息(message) notification对象：下属属性包含 4 种(alert 3个平台属性) alert 通知的内容在各个平台上，都可能只有这一个最基本的属性 "alert"。 这个位置的 "alert" 属性（直接在 notification 对象下），是一个快捷定义，各平台的 alert 信息如果都一样，则可不定义。如果各平台有定义，则覆盖这里的定义。
代码语言：javascript复制{
"notification" : {
"alert" : "Hello, JPush!"
}
}上面定义的 notification 对象，将被推送到 "platform" 指定的多个平台，并且其通知 alert 信息都一样。
android Android 平台上的通知，JPush SDK 按照一定的通知栏样式展示。
关键字 | 类型 | 选项 | 含义 | 说明 |
|---|---|---|---|---|
alert | string | 必填 | 通知内容 | 这里指定了，则会覆盖上级统一指定的 alert 信息；内容可以为空字符串，则表示不展示到通知栏。 |
title | string | 可选 | 通知标题 | 如果指定了，则通知里原来展示 App名称的地方，将展示成这个字段。 |
builder_id | int | 可选 | 通知栏样式ID | Android SDK 可设置通知栏样式，这里根据样式 ID 来指定该使用哪套样式。 |
priority | int | 可选 | 通知栏展示优先级 | 默认为0，范围为 -2～2 ，其他值将会被忽略而采用默认。 |
category | string | 可选 | 通知栏条目过滤或排序 | 完全依赖 rom 厂商对 category 的处理策略 |
style | int | 可选 | 通知栏样式类型 | 默认为0，还有1，2，3可选，用来指定选择哪种通知栏样式，其他值无效。有三种可选分别为bigText=1，Inbox=2，bigPicture=3。 |
alert_type | int | 可选 | 通知提醒方式 | 可选范围为 -1 ～ 7 ，对应 Notification.DEFAULT_ALL = -1 或者 Notification.DEFAULT_SOUND = 1, Notification.DEFAULT_VIBRATE = 2, Notification.DEFAULT_LIGHTS = 4 的任意 “or” 组合。默认按照 -1 处理。 |
big_text | string | 可选 | 大文本通知栏样式 | 当 style = 1 时可用，内容会被通知栏以大文本的形式展示出来。支持 api 16以上的rom。 |
inbox | JSONObject | 可选 | 文本条目通知栏样式 | 当 style = 2 时可用， json 的每个 key 对应的 value 会被当作文本条目逐条展示。支持 api 16以上的rom。 |
big_pic_path | string | 可选 | 大图片通知栏样式 | 当 style = 3 时可用，可以是网络图片 url，或本地图片的 path，目前支持.jpg和.png后缀的图片。图片内容会被通知栏以大图片的形式展示出来。如果是 http／https 的url，会自动下载；如果要指定开发者准备的本地图片就填sdcard 的相对路径。支持 api 16以上的rom。 |
extras | JSON Object | 可选 | 扩展字段 | 这里自定义 JSON 格式的 Key/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",
"extras" : {
"news_id" : 134,
"my_key" : "a value"
}
}
}
}iOS iOS 平台上 APNs 通知结构。
该通知内容会由 JPush 代理发往 Apple APNs 服务器，并在 iOS 设备上在系统通知的方式呈现。 该通知内容满足 APNs 的规范，支持的字段如下：
关键字 | 类型 | 选项 | 含义 | 说明 |
|---|---|---|---|---|
alert | string或JSON Object | 必填 | 通知内容 | 这里指定内容将会覆盖上级统一指定的 alert 信息；内容为空则不展示到通知栏。支持字符串形式也支持官方定义的alert payload 结构 |
sound | string | 可选 | 通知提示声音 | 如果无此字段，则此消息无声音提示；有此字段，如果找到了指定的声音就播放该声音，否则播放默认声音,如果此字段为空字符串，iOS 7 为默认声音，iOS 8及以上系统为无声音。(消息) 说明：JPush 官方 API Library (SDK) 会默认填充声音字段。提供另外的方法关闭声音。 |
badge | int | 可选 | 应用角标 | 如果不填，表示不改变角标数字；否则把角标数字改为指定的数字；为 0 表示清除。JPush 官方 API Library(SDK) 会默认填充badge值为" 1",详情参考：badge 1 |
content-available | boolean | 可选 | 推送唤醒 | 推送的时候携带"content-available":true 说明是 Background Remote Notification，如果不携带此字段则是普通的Remote Notification。详情参考：Background Remote Notification |
mutable-content | boolean | 可选 | 通知扩展 | 推送的时候携带”mutable-content":true 说明是支持iOS10的UNNotificationServiceExtension，如果不携带此字段则是普通的Remote Notification。详情参考：UNNotificationServiceExtension |
category | string | 可选 | IOS8才支持。设置APNs payload中的"category"字段值 | |
extras | JSON Object | 可选 | 附加字段 | 这里自定义 Key/value 信息，以供业务使用。 |
iOS 通知 JPush 要转发给 APNs 服务器。APNs 协议定义通知长度为 2048 字节。
JPush 因为需要重新组包，并且考虑一点安全冗余，要求"iOS":{ } 及大括号内的总体长度不超过：2000 个字节。JPush 使用 utf-8 编码，所以一个汉字占用 3 个字节长度。
服务端发送消息串：
代码语言：javascript复制{
"notification" : {
"ios" : {
"alert" : "hello, JPush!",
"sound" : "sound.caf",
"badge" : 1,
"extras" : {
"news_id" : 134,
"my_key" : "a value"
}
}
}
} 客户端收到apns：
代码语言：javascript复制{
"_j_msgid" = 813843507;
aps = {
alert = "hello,JPush!";
badge = 1;
sound = "sound.caf";
};
"my_key" = "a value";
"news_id" = 134;
}winphone
Windows Phone 平台上的通知。
该通知由 JPush 服务器代理向微软的 MPNs 服务器发送，并在 Windows Phone 客户端的系统通知栏上展示。
该通知满足 MPNs 的相关规范。当前 JPush 仅支持 toast 类型：
关键字 | 类型 | 选项 | 含义 | 说明 |
|---|---|---|---|---|
alert | string | 必填 | 通知内容 | 会填充到 toast 类型 text2 字段上。这里指定了，将会覆盖上级统一指定的 alert 信息；内容为空则不展示到通知栏。 |
title | string | 可选 | 通知标题 | 会填充到 toast 类型 text1 字段上。 |
_open_page | string | 可选 | 点击打开的页面名称 | 点击打开的页面。会填充到推送信息的 param 字段上，表示由哪个 App 页面打开该通知。可不填，则由默认的首页打开。 |
extras | JSON Object | 可选 | 扩展字段 | 作为参数附加到上述打开页面的后边。 |
{
"notification" : {
"winphone" : {
"alert" : "hello, JPush!",
"title" : "Push Test",
"_open_page" : "/friends.xaml",
"extras" : {
"news_id" : 134,
"my_key" : "a value"
}
}
}
}message
message：自定义消息
应用内消息。或者称作：自定义消息，透传消息。 此部分内容不会展示到通知栏上，JPush SDK 收到消息内容后透传给 App。需要 App 自行处理。 iOS 平台上，此部分内容在推送应用内消息通道（非APNS）获取。Windows Phone 暂时不支持应用内消息。
sms_message
用于设置短信推送内容以及短信发送的延迟时间。手机接收号码,开发者需要先把用户的手机号码与设备的registration id匹配。
options
cid
cid 是用于防止 api 调用端重试造成服务端的重复推送而定义的一个推送参数。 用户使用一个 cid 推送后，再次使用相同的 cid 进行推送，则会直接返回第一次成功推送的结果，不会再次进行推送。 CID的有效期为1天。CID的格式为：{appkey}-{uuid} 在使用cid之前，必须通过接口获取你的 cid 池。获取时type=push或者不传递type值。
