ajpush

  • Method
  • 论坛示例

    为帮助用户更好更快的使用模块,论坛维护了一个示例,示例中包含示例代码、知识点讲解、注意事项等,供您参考。

    #概述

    ajpush模块封装了极光推送平台的SDK,使用此模块可实现接收推送通知和透传消息功能。

    注意:使用了ajpush或者其他非APICloud提供的push服务,如个推等,请登录官网,在推送设置界面将官方的推送关闭,并去掉push模块,避免因同时使用多个推送服务而带来设备资源的更多消耗,如耗电量增加等。

    ###使用极光推送基本流程说明:

    1.在极光推送网站( https://www.jiguang.cn/ )注册帐号,并创建应用,获取APP_KEY

    2.在config.xml中配置ajpush feature,填写app_key及channel参数

    3.前端调用ajpush模块方法,初始化和监听推送消息。

    ios使用此模块之前需先配置config文件的Feature,方法如下

    名称:ajpush
    参数:app_key, channel
    描述:配置极光推送应用信息
    
        <feature name="ajpush">
            <param name="app_key" value="123456789" />
            <param name="channel" value="your channel" />
        </feature>
    

    字段描述:

        1. app_key:通过极光推送网站获得
        2. channel: 渠道号
        3. requestPermission: 是否自动请求通知权限,布尔类型,只支持iOS。模块默认会向系统请求通知权限,亦可以根据需要配置为false,然后调用api.requestPermission方法请求通知权限。
    

    Android使用此模块之前需先配置config文件,方法如下

    <meta-data name="JPUSH_CHANNEL" value="极光推送channel"/>
    <meta-data name="JPUSH_APPKEY"  value="极光推送appkey"/>
    

    4.使用该插件前,需要先调用setAuth接口进行隐私协议授权,用户同意隐私协议后才能进行初始化等操作,极光隐私政策可以参阅隐私政策与合规引导

    #setAuth

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

    setAuth(callback(ret))

    ##params

    auth:

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

    ##callback(ret)

    ret:

    • 类型:JSON 对象

    内部字段:

    {
        status:1       //操作成功状态值,1-同意,0-不同意
    }
    

    ##示例代码

    var ajpush = api.require('ajpush');
    ajpush.setAuth({
        auth:true
    },function(ret) {
        if (ret && ret.status){
            //success
        }
    });
    

    ##可用性

    ios系统,Android系统

    可提供的1.0.0及更高版本

    #init

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

    init(callback(ret, err))

    ##callback(ret, err)

    ret:

    • 类型:JSON 对象

    内部字段:

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

    ##示例代码

    var ajpush = api.require('ajpush');
    
    ajpush.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:{}            //额外键值对,可能为空
        isNotification:     //是否是通知,只支持iOS,布尔类型
    }
    

    ##示例代码

    var ajpush = api.require('ajpush');
    ajpush.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 ajpush = api.require('ajpush');
    ajpush.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 ajpush = api.require('ajpush');
    var param = {alias:'myalias',tags:['tag1','tag2']};
    ajpush.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('ajpush');
    var param = {sequence:100,tags:['tag1','tag2']};
    ajpush. setTags(param,function(ret) {
            var statusCode = ret.statusCode;
    });
    

    可用性

    iOS系统 ,Android系统

    可提供的 1.1.8 及更高版本

    #deleteTags

    删除标签

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

    ##params

    sequence:

    • 类型:数字类型
    • 描述:操作序列号, 同操作结果一起返回

    tags:

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

    ##callback(ret, err)

    ret:

    • 类型:JSON 对象

    内部字段:

    {
        status:,               //布尔类型,是否成功
         sequence:,           //数字类型;操作序列号
    }
    

    ##示例代码

    var ajpush = api.require('ajpush');
    var param = {sequence:101,tags:['tag1','tag2']};
    ajpush.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 ajpush = api.require('ajpush');
    var param = {sequence:102};
    ajpush.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('ajpush');
    var param = {alias:'myalias', sequence:101};
    ajpush.setAlias(param,function(ret) {
            var statusCode = ret.statusCode;
    });
    

    可用性

    iOS系统 ,Android系统

    可提供的 1.1.8 及更高版本

    #deleteAlias

    删除别名

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

    ##params

    sequence:

    • 类型:数字类型
    • 描述:操作序列号, 同操作结果一起返回

    ##callback(ret, err)

    ret:

    • 类型:JSON 对象
    • 内部字段:
    {
        status:,               //布尔类型,是否成功
         sequence:,           //数字类型;操作序列号
    }
    

    ##示例代码

    var ajpush = api.require('ajpush');
    var param = {sequence:102};
    ajpush.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 ajpush = api.require('ajpush');
        ajpush.onResume();
    });
    

    ##可用性

    Android系统

    可提供的1.0.0及更高版本

    #onPause

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

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

    onPause()

    ##示例代码

    api.addEventListener({name:'pause'}, function(ret,err) {
        var ajpush = api.require('ajpush');
        ajpush.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 ajpush = api.require('ajpush');
    var param = {id:-1};
    ajpush.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 ajpush = api.require('ajpush');
    var params = {};
    params.days = [1,2];
    params.startHour = 8;
    params.endHour = 20;
    ajpush.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 ajpush = api.require('ajpush');
    var params = {};
    params.startHour = 8;
    params.startMinute = 0;
    params.endHour = 20;
    params.endMinute = 59;
    ajpush.setPushTime(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 ajpush = api.require('ajpush');
    ajpush.stopPush(function(ret) {
        if(ret && ret.status){
            //success
        }
    });
    

    ##可用性

    iOS系统、Android系统

    可提供的1.0.0及更高版本

    #resumePush

    恢复Push推送。

    注意:需要额外在config.xml里面配置 <preference name="backgroundMode" value="remote-notification"/>,否则在iOS10中无法恢复推送。应避免停止推送,恢复推送在某些iOS版本系统上面可能会有兼容问题。

    resumePush(callback(ret, err))

    ##callback(ret, err)

    ret:

    • 类型:JSON 对象

    内部字段:

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

    ##示例代码

    var ajpush = api.require('ajpush');
    ajpush.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 ajpush = api.require('ajpush');
    ajpush.isPushStopped(function(ret) {
        if(ret && ret.isStopped){
    
        }
    });
    

    ##可用性

    iOS系统、Android系统

    可提供的1.0.0及更高版本

    #setBadge

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

    setBadge({params})

    ##params

    badge:

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

    ##示例代码

    var ajpush = api.require('ajpush');
    ajpush.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 ajpush = api.require('ajpush');
    ajpush.getRegistrationId(function(ret) {
        var registrationId = ret.id;
    });
    

    ##可用性

    iOS系统,Android系统

    可提供的1.0.0及更高版本

    #其他重要信息

    在Android平台,使用极光推送发送通知、消息等类型推送时,极光推送模块会往设备状态栏上发送通知,当通知被点击后,APICloud会将本次推送的内容通过事件监听回调的方式交给开发者。具体使用如下:

    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方法监听到,若应用在后台,系统会往设备通知栏发送通知,当通知被点击后,APICloud会将本次推送的内容通过事件监听回调的方式交给开发者。具体使用如下:

    api.addEventListener({
        name: 'noticeclicked'
    }, function(ret, err) {
        if (ret && ret.value) {
            var ajpush = ret.value;
            var content = ajpush.content;
            var extra = ajpush.extra;
        }
    })
    

    #自定义推送声音

    参考论坛帖子详细步骤:官方版极光推送(ajpush)demo

    #客户端错误码定义

    以下错误码可能在发生在调用本模块的任意接口发生错误时返回,应根据错误码产生的原因进行排查问题。

    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:网络连接超时

    论坛示例

    为帮助用户更好更快的使用模块,论坛维护了一个示例,示例中包含示例代码、知识点讲解、注意事项等,供您参考。

    是否仍需要帮助? 请保持联络!
    最后更新于 2023/06/2