JPush相关概念

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。定义为数组，但目前限制是一次只能推送一个。	目前限制一次只能推送一个。

示例

推送给全部（广播）：

{
   "platform": "all",
   "audience" : "all",
   "notification" : {
      "alert" : "Hi, JPush!",
      "android" : {}, 
      "ios" : {
         "extras" : { "newsid" : 321}
      }
   }
}

推送给多个标签（只要在任何一个标签范围内都满足）：在深圳、广州、或者北京

{
    "audience" : {
        "tag" : [ "深圳", "广州", "北京" ]
    }
}

推送给多个标签（需要同时在多个标签范围内）：在深圳并且是“女”

{
    "audience" : {
        "tag_and" : [ "深圳", "女" ]
    }
}

推送给多个别名：

{
    "audience" : {
        "alias" : [ "4314", "892", "4531" ]
    }
}

推送给多个注册ID：

{
    "audience" : {
        "registration_id" : [ "4312kjklfds2", "8914afd2", "45fdsa31" ]
    }
}

可同时推送指定多类推送目标：在深圳或者广州，并且是 “女” “会员”

{
    "audience" : {
        "tag" : [ "深圳", "广州" ]
        "tag_and" : [ "女", "会员"]
    }
}

notification

推送实体内容对象=通知(notification)+消息(message)
notification对象：下属属性包含 4 种(alert+3个平台属性)
alert
通知的内容在各个平台上，都可能只有这一个最基本的属性 "alert"。
这个位置的 "alert" 属性（直接在 notification 对象下），是一个快捷定义，各平台的 alert 信息如果都一样，则可不定义。如果各平台有定义，则覆盖这里的定义。

{
    "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 个字节长度。

服务端发送消息串：

{
    "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;
}

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值。