jpushVip

Method

概述

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方法请求通知权限。

Android极光推送角标设置应用入口Activity类：com.uzmap.pkg.LauncherUI

Android极光推送华为接收推送参数：

推送时添加uri_activity -- com.uzmap.pkg.EntranceActivity
应用监听时解析appintent监听中data数据（仅华为手机解析此数据）

setAuth

是否同意隐私协议政策（极光合规授权接口是为了保障用户隐私为根本目的，广大的开发者务必遵循其相关协议，确保用户同意《隐私政策》之后，再另行使用极光业务 SDK 功能）

setAuth(callback(ret))

params

auth：

类型：布尔类型
默认值：false
描述：是否同意授权

callback(ret)

ret：

类型：JSON 对象

内部字段：

{
    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及更高版本

init

初始化推送服务，只Android有效，iOS上会自动初始化

init(callback(ret, err))

params

audioName：

类型：字符串
默认值：无
描述：自定义通知的声音
注意：只需要传文件名（不需要路径及后缀），详细说明见自定义推送声音

callback(ret, err)

ret：

类型：JSON 对象
内部字段：

{
    status:1       //操作成功状态值，1-成功，0-失败
}

示例代码

var jpushVip = api.require('jpushVip');

jpushVip.init(function(ret) {
    if (ret && ret.status){
        //success
    }
});

可用性

Android系统

可提供的1.0.0及更高版本

setListener

设置推送监听。

若未注册监听，应用在前台运行时，收到“消息”和“通知”都会自动弹出通知到手机状态栏。

注册该监听后，应用在前台运行时，“消息”类型的推送，将直接交给该监听的回调函数，由开发人员自行处理推送消息，不自动弹出通知到手机状态栏。“通知”类型的推送，iOS平台也将直接交给该监听的回调函数，Android则会自动弹出通知到状态栏。

注意：由于系统差异，Android平台应用在前台、后台、退出情况下都能收到“消息”和“通知”，iOS平台应用在前台时才能收到“消息”和“通知”，后台、退出情况下只能收到“通知”。

setListener(callback(ret, err))

callback(ret, err)

ret：

类型：JSON 对象
内部字段：

{
    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

移除消息监听

removeListener()

示例代码

var jpushVip = api.require('jpushVip');
jpushVip.removeListener();

可用性

iOS系统，Android系统

可提供的 1.0.0 及更高版本

bindAliasAndTags

绑定用户别名和标签。服务端可以指定别名和标签进行消息推送

注意：本接口iOS端已废弃，使用setAlias、setTags代替

bindAliasAndTags({params}, callback(ret, err))

params

alias：

类型：字符串
默认值：无
描述：别名

tags：

类型：字符串数组
默认值：无
描述：标签列表

callback(ret, err)

ret：

类型：JSON 对象

内部字段：

{
    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

设置标签

setTags({params}, callback(ret, err))

params

sequence：

类型：数字类型
描述：操作序列号，同操作结果一起返回

tags：

类型：字符串数组
描述：标签列表，调用该接口会覆盖用户所有的tags

callback(ret)

ret：

类型：JSON 对象
内部字段：

{
    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

删除标签

deleteTags({params}, callback(ret, err))

params

sequence：

类型：数字类型
描述：操作序列号，同操作结果一起返回

tags：

类型：字符串数组
默认值：无
描述：标签列表

callback(ret, err)

ret：

类型：JSON 对象

内部字段：

{
    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

删除所有标签

clearTags({params}, callback(ret, err))

params

sequence：

类型：数字类型
描述：操作序列号，同操作结果一起返回

callback(ret, err)

ret：

类型：JSON 对象

内部字段：

{
    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

设置别名

setAlias({params}, callback(ret, err))

params

sequence：

类型：数字类型
描述：操作序列号，同操作结果一起返回

alias：

类型：字符串
默认值：无
描述：别名

callback(ret)

ret：

类型：JSON 对象
内部字段：

{
    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

删除别名

deleteAlias({params}, callback(ret, err))

params

sequence：

类型：数字类型
描述：操作序列号，同操作结果一起返回

callback(ret, err)

ret：

类型：JSON 对象

内部字段：

{
    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及更高版本

onResume

通知极光推送SDK当前应用恢复到前台。

本API用于极光推送做“用户使用时长”，“活跃用户”，“用户打开次数”的统计，并上报到服务器，在Portal上展示给开发者。只Android有效

onResume()

示例代码

api.addEventListener({name:'resume'}, function(ret,err) {
    var jpushVip = api.require('jpushVip');
    jpushVip.onResume();
});

可用性

Android系统

可提供的 1.0.0 及更高版本

onPause

通知极光推送SDK当前应用退入到后台。

本API用于极光推送做“用户使用时长”，“活跃用户”，“用户打开次数”的统计，并上报到服务器，在Portal上展示给开发者。只Android有效

onPause()

示例代码

api.addEventListener({name:'pause'}, function(ret,err) {
    var jpushVip = api.require('jpushVip');
    jpushVip.onPause();
});

可用性

Android系统

可提供的 1.0.0 及更高版本

clearNotification

清除极光推送发送到状态栏的通知。

clearNotification({params}, callback(ret, err))

params

id：

类型：数字
默认值：无
描述：待清除的通知id（等同于消息ID），为-1时清除所有，iOS只支持清除所有，不能为空

callback(ret, err)

ret：

类型：JSON 对象
内部字段：

{
    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及更高版本

setPushTime

设置允许推送时间，只Android有效

setPushTime(params,callback(ret, err))

params

days：

类型：数字数组
默认值：无
描述：允许推送的日期，0表示星期天，1表示星期一，以此类推，（7天制，数组里面的每项范围为0到6），不能为空

startHour：

类型：数字
默认值：无
描述：允许推送的开始时间（24小时制：startHour的范围为0到23），不能为空

endHour：

类型：数字
默认值：无
描述：允许推送的结束时间（24小时制：endHour的范围为0到23），不能为空

callback(ret, err)

ret：

类型：JSON 对象
内部字段：

{
    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及更高版本

setSilenceTime

设置通知静默时间，只Android有效

setSilenceTime(params,callback(ret, err))

params

startHour：

类型：数字
默认值：无
描述：静音时段的开始小时（24小时制，范围：0~23），不能为空

startMinute：

类型：数字
默认值：无
描述：静音时段的开始分钟（范围：0~59），不能为空

endHour：

类型：数字
默认值：无
描述：静音时段的结束小时（24小时制，范围：0~23），不能为空

endMinute：

类型：数字
默认值：无
描述：静音时段的结束分钟（范围：0~59），不能为空

callback(ret, err)

ret：

类型：JSON 对象
内部字段：

{
    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及更高版本

stopPush

停止Push推送。

注意：iOS上面应该尽量不使用该方法，除非该版本和以后都不再使用远程推送功能。停止推送意味着从系统移除注册的远程通知功能，停止后再恢复在某些版本系统上面可能会有兼容问题。如果只是想实现不给某个用户推送，可以通过其它方式处理，如移除绑定的标签或别名，这样服务端就不会向该用户推送。

stopPush(callback(ret, err))

callback(ret, err)

ret：

类型：JSON 对象
内部字段：

{
    status:1               //操作成功状态值，1-成功，0-失败
}

示例代码

var jpushVip = api.require('jpushVip');
jpushVip.stopPush(function(ret) {
    if(ret && ret.status){
        //success
    }
});

可用性

iOS系统，Android系统

可提供的 1.0.0 及更高版本

resumePush

恢复Push推送。

注意：需要额外在config.xml里面配置，否则在iOS10中无法恢复推送。应避免停止推送，恢复推送在某些iOS版本系统上面可能会有兼容问题。

resumePush(callback(ret, err))

callback(ret, err)

ret：

类型：JSON 对象
内部字段：

{
    status:1               //操作成功状态值，1-成功，0-失败
}

示例代码

var jpushVip = api.require('jpushVip');
jpushVip.resumePush(function(ret) {
    if(ret && ret.status){
        //success
    }
});

可用性

iOS系统，Android系统

可提供的 1.0.0 及更高版本

isPushStopped

查询当前推送服务是否停止。

isPushStopped(callback(ret, err))

callback(ret, err)

ret：

类型：JSON 对象
内部字段：

{
    isStopped:1                  //推送服务是否停止状态，1-停止，0-未停止
}

示例代码

var jpushVip = api.require('jpushVip');
jpushVip.isPushStopped(function(ret) {
    if(ret && ret.isStopped){

    }
});

可用性

iOS系统，Android系统

可提供的 1.0.0 及更高版本

setBadge

设置应用图标右上角数字，只iOS有效。

setBadge({params})

params

badge：

类型：数字
描述：为0时清除应用图标数字，大于0时设置应用图标数字，同时该值会更新到激光推送服务器，不能为空

示例代码

var jpushVip = api.require('jpushVip');
jpushVip.setBadge({
    badge:0
});

可用性

iOS系统

可提供的 1.0.0 及更高版本

getRegistrationId

集成了JPush SDK的应用程序在第一次成功注册到JPush服务器时，JPush服务器会给客户端返回一个唯一的该设备的标识RegistrationID。JPush SDK会以广播的形式发送RegistrationID到应用程序。应用程序可以把此RegistrationID保存于自己的应用服务器上，然后就可以根据 RegistrationID来向设备推送消息或者通知

getRegistrationId(callback(ret, err))

callback(ret, err)

ret：

类型：JSON 对象
内部字段：

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

自定义推送声音

init方法中需要传audioName参数
下载 notificationSound，将音频文件放到notificationSound.aar\res\raw路径下即可（aar也是标准zip包可用解压缩工具打开），音频文件名要与步骤1中的audioName一致
放入音频后将notificationSound插件以自定义插件的方式与jpushVip一起打包即可
服务端推送的时候需要下发通知的channelId，这样才能出发自定义通知铃声，详见官方文档如何实现自定义铃声

// 示例
{
    "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：网络连接超时

是否仍需要帮助？请保持联络！

最后更新于 2024/11/18

jpushVip

概述

Android极光推送角标设置应用入口Activity类：com.uzmap.pkg.LauncherUI

Android极光推送华为接收推送参数：

setAuth

params

callback(ret)

示例代码

可用性

init

params

callback(ret, err)

示例代码

可用性

setListener

callback(ret, err)

示例代码

可用性

removeListener

示例代码

可用性

bindAliasAndTags

params

callback(ret, err)

示例代码

可用性

setTags

params

callback(ret)

示例代码

可用性

deleteTags

params

callback(ret, err)

示例代码

可用性

clearTags

params

callback(ret, err)

示例代码

可用性

setAlias

params

callback(ret)

示例代码

可用性

**deleteAlias **

params

callback(ret, err)

示例代码

可用性

onResume

示例代码

可用性

onPause

示例代码

可用性

clearNotification

params

callback(ret, err)

示例代码

可用性

setPushTime

params

callback(ret, err)

示例代码

补充说明

可用性

setSilenceTime

params

callback(ret, err)

示例代码

补充说明

可用性

stopPush

callback(ret, err)

示例代码

可用性

resumePush

callback(ret, err)

deleteAlias