极光API推送 (v3 版本)
Push API v3
这是 Push API 最近的版本。
相比于 API v2 版本,v3 版本的改进为:
完全基于 https,不再提供 http 访问;
使用 HTTP Basic Authentication 的方式做访问授权。这样整个 API 请求可以使用常见的 HTTP 工具来完成,比如:curl,浏览器插件等;
推送内容完全使用 JSON 的格式;
支持的功能有所改进:支持多 tag 的与或操作;可单独发送通知或者自定义消息,也可同时推送通知与自定义消息;windows phone 目前只有通知。
推送概述
功能说明
向某单个设备或者某设备列表推送一条通知、或者消息。
推送的内容只能是 JSON 表示的一个推送对象。
调用地址:
POST https://api.jpush.cn/v3/push
请求示例
curl --insecure -X POST -v https://api.jpush.cn/v3/push -H "Content-Type: application/json" -u "7d431e42dfa6a6d693ac2d04:5e987ac6d2e04d95a9d8f0d1" -d '{"platform":"all","audience":"all","notification":{"alert":"Hi,JPush!"}}'> POST /v3/push HTTP/1.1> Authorization: Basic N2Q0MzFlNDJkZmE2YTZkNjkzYWMyZDA0OjVlOTg3YWM2ZDJlMDRkOTVhOWQ4ZjBkMQ==
返回示例
< HTTP/1.1 200 OK
< Content-Type: application/json
{"sendno":"18","msg_id":"1828256757"}
调用验证
HTTP Header(头)里加一个字段(Key/Value对):
Authorization: Basic base64_auth_string
其中 base64_auth_string 的生成算法为:base64(appKey:masterSecret)
即,对 appKey 加上冒号,加上 masterSecret 拼装起来的字符串,再做 base64 转换。
推送校验 API
POST https://api.jpush.cn/v3/push/validate
功能说明
该 API 只用于验证推送调用是否能够成功,与推送 API 的区别在于:不向用户发送任何消息。 其他字段说明:同推送 API。
推送对象
一个推送对象,以 JSON 格式表达,表示一条推送相关的所有信息。
示例与说明
{
"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"
}
},
"options": {
"time_to_live": 60,
"apns_production": false
}}
关键字 | 选项 | 含义 |
---|---|---|
platform | 必填 | 推送平台设置 |
audience | 必填 | 推送设备指定 |
notification | 可选 | 通知内容体。是被推送到客户端的内容。与 message 一起二者必须有其一,可以二者并存 |
message | 可选 | 消息内容体。是被推送到客户端的内容。与 notification 一起二者必须有其一,可以二者并存 |
options | 可选 | 推送参数 |
platform
JPush 当前支持 Android, iOS, Windows Phone 三个平台的推送。其关键字分别为:"android", "ios", "winphone"。
如果目标平台为 iOS 平台 需要在 options 中通过 apns_production 字段来制定推送环境。True 表示推送生产环境,False 表示要推送开发环境; 如果不指定则为推送生产环境
推送到所有平台:
{ "platform" : "all" }
指定特定推送平台:
{ "platform" : ["android", "ios"] }
audience
推送设备对象,表示一条推送可以被推送到哪些设备列表。确认推送设备对象,JPush 提供了多种方式,比如:别名、标签、注册ID、分群、广播等。
all
如果要发广播(全部设备),则直接填写 “all”。
推送目标
广播外的设备选择方式,有如下几种:
关键字 | 含义 | 类型 | 说明 | 备注 |
---|---|---|---|---|
tag | JSON Array | 标签 | 数组。多个标签之间是 OR 的关系,即取并集。 | 用标签来进行大规模的设备属性、用户属性分群。 一次推送最多 20 个。
|
tag_and | JSON Array | 标签AND | 数组。多个标签之间是 AND 关系,即取交集。 | 注册与 tag 区分。一次推送最多 20 个。 |
alias | JSON Array | 别名 | 数组。多个别名之间是 OR 关系,即取并集。 | 用别名来标识一个用户。一个设备只能绑定一个别名,但多个设备可以绑定同一个别名。一次推送最多 1000 个。
|
registration_id | JSON Array | 注册ID | 数组。多个注册ID之间是 OR 关系,即取并集。 | 设备标识。一次推送最多 1000 个。 |
每种类型的值都是数组(Array),数组里多个值之间隐含的关系是是 OR,即取并集。但 tag_and 不同,其数组里多个值之间是 AND 关系,即取交集。
4 种类型至少需要有其一。如果值数组长度为 0,表示该类型不存在。
这几种类型可以并存。并存时多项的隐含关系是 AND,即取交集。
示例
推送给全部(广播):
{
"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
“通知”对象,是一条推送的实体内容对象之一(另一个是“消息”),是会作为“通知”推送到客户端的。
其下属属性包含 4 种,3 个平台属性,以及一个 "alert" 属性。
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 来指定该使用哪套样式。 |
extras | JSON Object | 可选 | 扩展字段 | 这里自定义 JSON 格式的 Key/Value 信息,以供业务使用。 |
{
"notification" : {
"android" : {
"alert" : "hello, JPush!",
"title" : "JPush test",
"builder_id" : 3,
"extras" : {
"news_id" : 134,
"my_key" : "a value"
}
}
}}
iOS
iOS 平台上 APNs 通知。
该通知内容会由 JPush 代理发往 Apple APNs 服务器,并在 iOS 设备上在系统通知的方式呈现。
该通知内容满足 APNs 的规范,支持的字段如下:
关键字 | 类型 | 选项 | 说明 | |
---|---|---|---|---|
alert | string | 必填 | 通知内容 | 这里指定了,将会覆盖上级统一指定的 alert 信息;内容为空则不展示到通知栏。支持 emoji 表情。 |
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 |
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
应用内消息。或者称作:自定义消息,透传消息。
此部分内容不会展示到通知栏上,JPush SDK 收到消息内容后透传给 App。App 需要自行处理。
iOS 平台上,有此部分内容,才会推送应用内消息通道。
Windows Phone 平台上,暂时不支持应用内消息。
消息包含如下字段:
关键字 | 类型 | 选项 | 含义 |
---|---|---|---|
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推送通知同时下发的应用内消息。
options
推送可选项。
当前包含如下几个可选项:
关键字 | 类型 | 选项 | 含义 | 说明 |
---|---|---|---|---|
sendno | int | 可选 | 推送序号 | 纯粹用来作为 API 调用标识,API 返回时被原样返回,以方便 API 调用方匹配请求与返回。 |
time_to_live | int | 可选 | 离线消息保留时长(秒) | 推送当前用户不在线时,为该用户保留多长时间的离线消息,以便其上线时再次推送。默认 86400 (1 天),最长 10 天。设置为 0 表示不保留离线消息,只有推送当前在线的用户可以收到。 |
override_msg_id | long | 可选 | 要覆盖的消息ID | 如果当前的推送要覆盖之前的一条推送,这里填写前一条推送的 msg_id 就会产生覆盖效果,即:1)该 msg_id 离线收到的消息是覆盖后的内容;2)即使该 msg_id Android 端用户已经收到,如果通知栏还未清除,则新的消息内容会覆盖之前这条通知;覆盖功能起作用的时限是:1 天。如果在覆盖指定时限内该 msg_id 不存在,则返回 1003 错误,提示不是一次有效的消息覆盖操作,当前的消息不会被推送。 |
apns_production | boolean | 可选 | APNs是否生产环境 | True 表示推送生产环境,False 表示要推送开发环境;如果不指定则为推送生产环境。JPush 官方 API LIbrary (SDK) 默认设置为推送 “开发环境”。 |
big_push_duration | int | 可选 | 定速推送时长(分钟) | 又名缓慢推送,把原本尽可能快的推送速度,降低下来,给定的n分钟内,均匀地向这次推送的目标用户推送。最大值为1400.未设置则不是定速推送。 |
调用返回
HTTP 状态码
参考文档:HTTP-Status-Code
业务返回码
Code | 描述 | 详细解释 | HTTP Status Code |
---|---|---|---|
1000 | 系统内部错误 | 服务器端内部逻辑错误,请稍后重试。 | 500 |
1001 | 只支持 HTTP Post 方法 | 不支持 Get 方法。 | 405 |
1002 | 缺少了必须的参数 | 必须改正 | 400 |
1003 | 参数值不合法 | 必须改正 | 400 |
1004 | 验证失败 | 必须改正。详情请看:调用验证 | 401 |
1005 | 消息体太大 | 必须改正。 Android平台Notification+Message长度限制为1000字节; iOS Notification 中 “iOS”:{ } 及大括号内的总体长度不超过:2000个字节(包括自定义参数和符号),iOS 的 Message部分长度不超过 1000 字节; WinPhone平台Notification长度限制为1000字节 | 400 |
1008 | app_key参数非法 | 必须改正 | 400 |
1011 | 没有满足条件的推送目标 | 请检查audience | 400 |
1020 | 只支持 HTTPS 请求 | 必须改正 | 404 |
1030 | 内部服务超时 | 稍后重试 | 503 |
极光API推送 (v3 版本)的更多相关文章
- .net平台借助第三方推送服务在推送Android,IOS消息(极光推送_V3版本)最新
最近刚从极光推送官网上看到V2版本要停用,不得不有重新写V3版本的.这里用到了 HTTP Basic Authentication http://www.cnblogs.com/pingming/p/ ...
- atitit.极光消息推送服务器端开发实现推送 jpush v3. 总结o7p
atitit.极光消息推送服务器端开发实现推送 jpush v3. 总结o7p 1. 推送所设计到底功能1 1.1. 内容压缩1 1.2. 多引擎1 2. reg ,设置appkey and pw ...
- .NET对接极光消息推送
什么是APP消息推送? 很多手机APP会不定时的给用户推送消息,例如一些新闻APP会给用户推送用户可能感兴趣的新闻,或者APP有更新了,会给用户推送是否选择更新的消息等等,这就是所谓的"消息 ...
- java服务端集成极光消息推送--详细开发步骤
1.极光推送账号准备 要使用极光消息推送必须先在官方网站上注册账号,并添加应用. 产品介绍:https://docs.jiguang.cn/jpush/guideline/intro/ 注册开发者账号 ...
- Git for Windows之推送本地版本库到远程仓库
Git for Windows之基础环境搭建与基础操作中介绍了Git基本环境的构建与基本的操作.生成了一个本地git版本库,本文将介绍如何将这个版本库推送到远程仓库(码云,github也可以). 1. ...
- Github自动打包并推送Nuget版本
如何将自己的类库,自动打包并自动发布到Nuget? 1. 项目csproject属性修改 新建一个项目GitToNugetPackageTest 不用添加任何类,我们修改csproject属性. 替换 ...
- git-------基础知识(本地推送项目版本---github上)
创建Git仓库 一:初始化版本库:-git init 二:添加文件到缓存区:-git add --添加所有文件 是:加个点-列:git add . 三:查看仓库状态:-git status 四:添加 ...
- IOS JPush 集成步骤(极光远程推送解决方案,支持android和iOS两个平台)
● 什么是JPush ● 一套远程推送解决方案,支持android和iOS两个平台 ● 它能够快捷地为iOS App增加推送功能,减少集成APNs需要的工作量.开发复杂 度 ● 更多的信息,可 ...
- 极光推送 JPush 简介 集成 MD
Markdown版本笔记 我的GitHub首页 我的博客 我的微信 我的邮箱 MyAndroidBlogs baiqiantao baiqiantao bqt20094 baiqiantao@sina ...
随机推荐
- Python基础语法03-控制流
Python 条件语句 Python条件语句是通过一条或多条语句的执行结果(True或者False)来决定执行的代码块. 可以通过下图来简单了解条件语句的执行过程: Python程序语言指定任何非0和 ...
- Windows10系统修复
sfc /scannow 命令将扫描所有受保护的系统文件,并用位于 %WinDir%\System32\dllcache 的压缩文件夹中的缓存副本替换损坏的文件. %WinDir% 占位符代表Wind ...
- SolidEdge 打开工程图提示图纸已过期怎么办
如下图所示,打开工程图时提示图纸已过期 点击工具-图纸视图跟踪器,按提示打开过期的装配体文件 更新这个装配体文件 然后切换到刚才提示过期的工程图文件,点击更新视图,下次再打开的时候就不会提 ...
- Flash如何为文字描边
可以使用墨水瓶工具,但是要先把文字打散(可以打散之后再组合起来)粗细和颜色都可以调,粗细就是笔触,颜色就是前景色(边框颜色)
- C++11 并发指南三(std::mutex 详解)(转)
转自:http://www.cnblogs.com/haippy/p/3237213.html 上一篇<C++11 并发指南二(std::thread 详解)>中主要讲到了 std::th ...
- hdoj 2188 悼念512汶川大地震遇难同胞——选拔志愿者 【巴什博弈】
题意:. . . 策略:最简单的典型的巴什博弈. 代码: #include<stdio.h> int main() { int n, m; int t; scanf("%d&qu ...
- JobConf
/** * A map/reduce job configuration. * 翻译:一个map/reduce作业配置 * <p><code>JobConf</code ...
- 3D打印技术之切片引擎(4)
[此系列文章基于熔融沉积( fused depostion modeling, FDM )成形工艺] 这一篇文章我讲一下多边打印的问题,多边打印是切片引擎的一项关键的技术. 图1 双边打印 首先.它能 ...
- hdu5318 The Goddess Of The Moon (矩阵高速幂优化dp)
题目:pid=5318">http://acm.hdu.edu.cn/showproblem.php?pid=5318 题意:给定n个数字串和整数m,规定若数字串s1的后缀和数字串s2 ...
- Android调用JNI本地方法经过有点改变
方法注册好后要经过哪些路 Android一个异常捕获项目 https://github.com/xroche/coffeecatch coffeecatch CoffeeCatch, a tiny n ...