jpushVip插件封装了极光推送平台的SDK,使用此插件可实现接收推送通知和透传消息功能,同时集成极光厂商通道。
注意:使用了jpushVip或者其他非YonBuilder移动开发提供的push服务,如个推等,请登录官网,在推送设置界面将官方的推送关闭,并去掉push插件,避免因同时使用多个推送服务而带来设备资源的更多消耗,如耗电量增加等。iOS 端没有 vip,只有普通账号。
###使用极光推送基本流程说明:
1.在极光推送网站( https://www.jpush.cn )注册帐号,并创建应用,获取APP_KEY
2.在config.xml中配置meta-data,填写JPUSH_APPKEY及JPUSH_CHANNEL参数
3.若是集成极光厂商通道,在config.xml中配置meta-data,小米平台,魅族平台,oppo平台,vivo平台,华为平台推送信息, 各平台申请方式如下
4.进入极光工作台,在推送设置中设置相应厂商通道的appKey & appSecret
5.前端调用jpushVip插件方法,初始化和监听推送消息。
使用此插件之前需先配置config文件 ,方法如下 "MI-" "MZ-" "appid=" 等前缀不能省略。
//极光配置
<meta-data name="JPUSH_CHANNEL" value="渠道号"/>
<meta-data name="JPUSH_APPKEY" value="通过极光推送网站获得appkey" />
// <!-- 小米开始 -->
<meta-data name="XIAOMI_APPKEY" value="MI-您的应用对应的小米的APPKEY" />
<meta-data name="XIAOMI_APPID" value="MI-您的应用对应的小米的APPID" />
// <!-- 小米结束 -->
// <!-- meizu start -->
<meta-data name="MEIZU_APPKEY" value="MZ-您的应用对应的魅族的APPKEY" />
<meta-data name="MEIZU_APPID" value="MZ-您的应用对应的魅族的APPID" />
// <!-- meizhu end -->
// <!-- oppo start -->
<meta-data name="OPPO_APPKEY" value="OP-您的应用对应的OPPO的APPKEY" />
<meta-data name="OPPO_APPID" value="OP-您的应用对应的OPPO的APPID" />
<meta-data name="OPPO_APPSECRET" value="OP-您的应用对应的OPPO的APPSECRET" />
// <!-- oppo end -->
// <!-- vivo start -->
<meta-data name="com.vivo.push.api_key" value="您的应用对应的VIVO的APPKEY" />
<meta-data name="com.vivo.push.app_id" value="您的应用对应的VIVO的APPID" />
// <!-- vivo end -->
// <!-- huawei start -->
<meta-data name="com.huawei.hms.client.appid"
value="appid=您的应用对应华为的appID"></meta-data>
// <!-- huawei end -->
// <!-- 荣耀推送 start -->
<meta-data
name="com.hihonor.push.app_id"
value="您的应用对应的Honor的APP ID" />
// <!-- 荣耀推送 end -->
// <!-- iOS start -->
<feature name="jpushVip">
<param name="app_key" value="123456789" />
<param name="channel" value="your channel" />
</feature>
// <!-- iOS end -->
iOS 配置字段描述:
1. app_key:通过极光推送网站获得
2. channel: 渠道号
3. requestPermission: 是否自动请求通知权限,布尔类型,只支持iOS。插件默认会向系统请求通知权限,亦可以根据需要配置为false,然后调用api.requestPermission方法请求通知权限。
是否同意隐私协议政策(极光合规授权接口是为了保障用户隐私为根本目的,广大的开发者务必遵循其相关协议,确保用户同意《隐私政策》之后,再另行使用极光业务 SDK 功能)
setAuth(callback(ret))
auth:
ret:
内部字段:
{
status:1 //操作成功状态值,1-同意,0-不同意
}
var jpushVip = api.require('jpushVip');
jpushVip.setAuth({
auth:true
},function(ret) {
if (ret && ret.status){
//success
}
});
ios系统,Android系统
可提供的1.0.0及更高版本
初始化推送服务,只Android有效,iOS上会自动初始化
init(callback(ret, err))
audioName:
ret:
{
status:1 //操作成功状态值,1-成功,0-失败
}
var jpushVip = api.require('jpushVip');
jpushVip.init(function(ret) {
if (ret && ret.status){
//success
}
});
Android系统
可提供的1.0.0及更高版本
设置推送监听。
若未注册监听,应用在前台运行时,收到“消息”和“通知”都会自动弹出通知到手机状态栏。
注册该监听后,应用在前台运行时,“消息”类型的推送,将直接交给该监听的回调函数,由开发人员自行处理推送消息,不自动弹出通知到手机状态栏。“通知”类型的推送,iOS平台也将直接交给该监听的回调函数,Android则会自动弹出通知到状态栏。
注意:由于系统差异,Android平台应用在前台、后台、退出情况下都能收到“消息”和“通知”,iOS平台应用在前台时才能收到“消息”和“通知”,后台、退出情况下只能收到“通知”。
setListener(callback(ret, err))
ret:
{
id:'' //推送id,可能为空
title:'' //推送标题,可能为空
content:'' //推送内容
extra:{} //额外键值对,可能为空
}
var jpushVip = api.require('jpushVip');
jpushVip.setListener(
function(ret) {
var id = ret.id;
var title = ret.title;
var content = ret.content;
var extra = ret.extra;
}
);
iOS系统,Android系统
可提供的 1.0.0 及更高版本
移除消息监听
removeListener()
var jpushVip = api.require('jpushVip');
jpushVip.removeListener();
iOS系统,Android系统
可提供的 1.0.0 及更高版本
绑定用户别名和标签。服务端可以指定别名和标签进行消息推送
注意:本接口iOS端已废弃,使用setAlias、setTags代替
bindAliasAndTags({params}, callback(ret, err))
alias:
tags:
ret:
内部字段:
{
statusCode:0 //极光推送返回的状态码
}
var jpushVip = api.require('jpushVip');
var param = {alias:'myalias',tags:['tag1','tag2']};
jpushVip.bindAliasAndTags(param,function(ret) {
var statusCode = ret.statusCode;
});
iOS系统,Android系统
可提供的 1.0.0 及更高版本
设置标签
setTags({params}, callback(ret, err))
sequence:
tags:
ret:
{
statusCode:0 //数字类型;极光推送返回的状态码
sequence: //数字类型;请求序列号
}
var ajpush = api.require('jpushVip');
var param = {sequence:100,tags:['tag1','tag2']};
ajpush. setTags(param,function(ret) {
var statusCode = ret.statusCode;
});
iOS系统 ,Android系统
可提供的 1.1.3 及更高版本
删除标签
deleteTags({params}, callback(ret, err))
sequence:
tags:
ret:
内部字段:
{
status:, //布尔类型,是否成功
sequence:, //数字类型;操作序列号
}
var jpushVip = api.require('jpushVip');
var param = {sequence:101, sequence:101};
jpushVip.deleteTags(param,function(ret) {
alert('处理结果:\n' + JSON.stringify(ret));
});
iOS系统,Android系统
可提供的1.0.0及更高版本
删除所有标签
clearTags({params}, callback(ret, err))
sequence:
ret:
内部字段:
{
status:, //布尔类型,是否成功
sequence:, //数字类型;操作序列号
}
var jpushVip = api.require('jpushVip');
var param = {sequence:102};
jpushVip.clearTags(param,function(ret) {
alert('处理结果:\n' + JSON.stringify(ret));
});
iOS系统,Android系统
可提供的1.0.0及更高版本
设置别名
setAlias({params}, callback(ret, err))
sequence:
alias:
ret:
{
statusCode:0 //数字类型;极光推送返回的状态码
sequence: //数字类型;请求序列号
}
var ajpush = api.require('jpushVip');
var param = { sequence: 102, alias:'bieming' };
ajpush.setAlias(param,function(ret) {
var statusCode = ret.statusCode;
});
iOS系统 ,Android系统
可提供的 1.1.3 及更高版本
删除别名
deleteAlias({params}, callback(ret, err))
sequence:
ret:
内部字段:
{
status:, //布尔类型,是否成功
sequence:, //数字类型;操作序列号
}
var jpushVip = api.require('jpushVip');
var param = {sequence:102};
jpushVip.deleteAlias(param,function(ret) {
alert('处理结果:\n' + JSON.stringify(ret));
});
iOS系统,Android系统
可提供的1.0.0及更高版本
通知极光推送SDK当前应用恢复到前台。
本API用于极光推送做“用户使用时长”,“活跃用户”,“用户打开次数”的统计,并上报到服务器,在Portal上展示给开发者。只Android有效
onResume()
api.addEventListener({name:'resume'}, function(ret,err) {
var jpushVip = api.require('jpushVip');
jpushVip.onResume();
});
Android系统
可提供的 1.0.0 及更高版本
通知极光推送SDK当前应用退入到后台。
本API用于极光推送做“用户使用时长”,“活跃用户”,“用户打开次数”的统计,并上报到服务器,在Portal上展示给开发者。只Android有效
onPause()
api.addEventListener({name:'pause'}, function(ret,err) {
var jpushVip = api.require('jpushVip');
jpushVip.onPause();
});
Android系统
可提供的 1.0.0 及更高版本
清除极光推送发送到状态栏的通知。
clearNotification({params}, callback(ret, err))
id:
ret:
{
status:1 //操作成功状态值,1-成功,0-失败
}
var jpushVip = api.require('jpushVip');
var param = {id:-1};
jpushVip.clearNotification(param,function(ret) {
if(ret && ret.status){
//success
}
});
iOS系统,Android系统
可提供的1.0.0及更高版本
设置允许推送时间,只Android有效
setPushTime(params,callback(ret, err))
days:
startHour:
endHour:
ret:
{
status:1 //操作成功状态值,1-成功,0-失败
}
var jpushVip = api.require('jpushVip');
var params = {};
params.days = [1,2];
params.startHour = 8;
params.endHour = 20;
jpushVip.setPushTime(params, function(ret) {
if(ret && ret.status){
//success
}
});
默认情况下用户在任何时间都允许推送。即任何时候有推送下来,客户端都会收到,并展示。开发者可以调用此 API 来设置允许推送的时间。如果不在该时间段内收到消息,当前的行为是:推送到的通知会被扔掉。
Android系统
可提供的1.0.0及更高版本
设置通知静默时间,只Android有效
setSilenceTime(params,callback(ret, err))
startHour:
startMinute:
endHour:
endMinute:
ret:
{
status:1 //操作成功状态值,1-成功,0-失败
}
var jpushVip = api.require('jpushVip');
var params = {};
params.startHour = 8;
params.startMinute = 0;
params.endHour = 20;
params.endMinute = 59;
jpushVip.setSilenceTime(params, function(ret) {
if(ret && ret.status){
//success
}
});
默认情况下用户在收到推送通知时,客户端可能会有震动,响铃等提示。但用户在睡觉、开会等时间点希望为 "免打扰" 模式,也是静音时段的概念。开发者可以调用此 API 来设置静音时段。如果在该时间段内收到消息,则:不会有铃声和震动。
Android系统
可提供的1.0.0及更高版本
停止Push推送。
注意:iOS上面应该尽量不使用该方法,除非该版本和以后都不再使用远程推送功能。停止推送意味着从系统移除注册的远程通知功能,停止后再恢复在某些版本系统上面可能会有兼容问题。如果只是想实现不给某个用户推送,可以通过其它方式处理,如移除绑定的标签或别名,这样服务端就不会向该用户推送。
stopPush(callback(ret, err))
ret:
{
status:1 //操作成功状态值,1-成功,0-失败
}
var jpushVip = api.require('jpushVip');
jpushVip.stopPush(function(ret) {
if(ret && ret.status){
//success
}
});
iOS系统,Android系统
可提供的 1.0.0 及更高版本
恢复Push推送。
注意:需要额外在config.xml里面配置
resumePush(callback(ret, err))
ret:
{
status:1 //操作成功状态值,1-成功,0-失败
}
var jpushVip = api.require('jpushVip');
jpushVip.resumePush(function(ret) {
if(ret && ret.status){
//success
}
});
iOS系统,Android系统
可提供的 1.0.0 及更高版本
查询当前推送服务是否停止。
isPushStopped(callback(ret, err))
ret:
{
isStopped:1 //推送服务是否停止状态,1-停止,0-未停止
}
var jpushVip = api.require('jpushVip');
jpushVip.isPushStopped(function(ret) {
if(ret && ret.isStopped){
}
});
iOS系统,Android系统
可提供的 1.0.0 及更高版本
设置应用图标右上角数字,只iOS有效。
setBadge({params})
badge:
var jpushVip = api.require('jpushVip');
jpushVip.setBadge({
badge:0
});
iOS系统
可提供的 1.0.0 及更高版本
集成了JPush SDK的应用程序在第一次成功注册到JPush服务器时,JPush服务器会给客户端返回一个唯一的该设备的标识RegistrationID。JPush SDK会以广播的形式发送RegistrationID到应用程序。应用程序可以把此RegistrationID保存于自己的应用服务器上,然后就可以根据 RegistrationID来向设备推送消息或者通知
getRegistrationId(callback(ret, err))
ret:
{
id:'' //RegistrationID
}
var jpushVip = api.require('jpushVip');
jpushVip.getRegistrationId(function(ret) {
var registrationId = ret.id;
});
iOS系统,Android系统
可提供的 1.0.0 及更高版本
在Android平台,使用极光推送发送通知、消息等类型推送时,极光推送插件会往设备状态栏上发送通知,当通知被点击后,YonBuilder移动开发会将本次推送的内容通过事件监听回调的方式交给开发者。具体使用如下:
api.addEventListener({
name: 'appintent'
}, function(ret, err) {
if (ret && ret.appParam.ajpush) {
var ajpush = ret.appParam.ajpush;
var id = ajpush.id;
var title = ajpush.title;
var content = ajpush.content;
var extra = ajpush.extra;
}
})
在iOS平台,使用极光推送发送通知时,若应用在前台运行,则推送内容可以通过setListener方法监听到,若应用在后台,系统会往设备通知栏发送通知,当通知被点击后,YonBuilder移动开发会将本次推送的内容通过事件监听回调的方式交给开发者。具体使用如下:
api.addEventListener({
name: 'noticeclicked'
}, function(ret, err) {
if (ret && ret.value) {
var ajpush = ret.value;
var content = ajpush.content;
var extra = ajpush.extra;
}
})
// 示例
{
"notification": {
"android": {
"alert": "message alert",
"title": "title",
// 如果 sound 和 channel_id 都有传,那么会以 channel_id 的铃声为准
"sound": "coin",
"channel_id": "m_channel123" //注意: channel_id 要与 config.xml中的 JPUSH_CHANNEL值一致
}
}
}
以下错误码可能在发生在调用本插件的任意接口发生错误时返回,应根据错误码产生的原因进行排查问题。
6001:无效的设置,tag/alias不应参数都为null,3.0.7开始的新tag/alias接口此错误码表示,tag/alias参数不能为空
6002:设置超时,建议重试
6003:alias字符串不合法。有效的别名、标签组成:字母(区分大小写)、数字、下划线、汉字、特殊字符(2.1.6支持)@!#$&*+=.|
6004:alias超长。最多 40个字节。中文UTF-8是3个字节
6005:某一个tag字符串不合法。有效的别名、标签组成:字母(区分大小写)、数字、下划线、汉字、特殊字符(2.1.6支持)@!#$&*+=.|
6006:某一个tag 超长。一个tag最多40个字节。中文UTF-8是3个字节
6007:tags数量超出限制。最多1000个,这是一台设备的限制。一个应用全局的标签数量无限制。
6008:tag超出总长度限制。3.0.7版本中新增tag/alias接口最长度最多5000字节,tag/alias老接口总长度最多7000字节
6009:未知错误。由于权限问题,导致的PushService启动异常。
6011:10s内设置tag或alias大于10次,短时间内操作过于频繁
6012:在JPush服务stop状态下设置了tag或alias。3.0.0版本新增的错误码。开发者可根据这个错误码的信息做相关处理或者提示。
6013:用户设备时间轴异常。3.0.6 版本新增的错误码。设备本地时间轴异常变化影响了设置频率。
6014:服务器繁忙,建议重试。3.0.7 版本新增的错误码
6015:appkey在黑名单中。3.0.7 版本新增的错误码
6016:无效用户。3.0.7 版本新增的错误码
6017:无效请求。3.0.7 版本新增的错误码
6018:后台累计设置的tag数超过1000个,建议先清除部分tag。3.0.7 版本新增的错误码
6019:查询请求已过期。3.0.7 版本新增的错误码
6020:tag/alias操作暂停,建议过一段时间再设置。3.0.7版本新增的错误码
6021:tags操作正在进行中,暂时不能进行其他tags操作。3.0.7版本新增的错误码
6022:alias操作正在进行中,暂时不能进行其他alias操作。3.0.7版本新增的错误码
-997:注册失败。(一般是由于没有网络造成的)如果确保设备网络正常,还是一直遇到此问题,则还有另外一个原因:JPush服务器端拒绝注册。而这个的原因一般是:你当前的App的Android包名,以及appKey,与你在Portal上注册的应用的Android包名与AppKey不相同。
1005:包名和AppKey不匹配
1008:AppKey非法请到官网检查此应用详情中的appkey,确认无误
1009:当前的appkey下没有创建Android应用。请到官网检查此应用的应用详情
-996:网络连接断开。如果确保设备网络正常,可能是由于包名不正确,服务器强制断开客户端的连接
-994:网络连接超时