ajpush

来自于:ajpush 立即使用

init setListener removeListener bindAliasAndTags onResume onPause clearNotification setPushTime setSilenceTime stopPush resumePush isPushStopped setBadge getRegistrationId 其他重要信息 自定义推送声音 客户端错误码定义

论坛示例

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

概述

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

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

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

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

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

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

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

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

字段描述:

  1. 1. app_key:通过极光推送网站获得
  2. 2. channel: 渠道号

init

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

init(callback(ret, err))

callback(ret, err)

ret:

  • 类型:JSON 对象

内部字段:

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

示例代码

  1. var ajpush = api.require('ajpush');
  2. ajpush.init(function(ret) {
  3. if (ret && ret.status){
  4. //success
  5. }
  6. });

可用性

Android系统

可提供的1.0.0及更高版本

setListener

设置推送监听。

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

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

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

setListener(callback(ret, err))

callback(ret, err)

ret:

  • 类型:JSON 对象

内部字段:

  1. {
  2. id:'' //推送id,可能为空
  3. title:'' //推送标题,可能为空
  4. content:'' //推送内容
  5. extra:{} //额外键值对,可能为空
  6. isNotification: //是否是通知,只支持iOS,布尔类型
  7. }

示例代码

  1. var ajpush = api.require('ajpush');
  2. ajpush.setListener(
  3. function(ret) {
  4. var id = ret.id;
  5. var title = ret.title;
  6. var content = ret.content;
  7. var extra = ret.extra;
  8. }
  9. );

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

removeListener

移除消息监听

removeListener()

示例代码

  1. var ajpush = api.require('ajpush');
  2. ajpush.removeListener();

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

bindAliasAndTags

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

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

params

alias:

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

tags:

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

callback(ret, err)

ret:

  • 类型:JSON 对象

内部字段:

  1. {
  2. statusCode:0 //极光推送返回的状态码
  3. }

示例代码

  1. var ajpush = api.require('ajpush');
  2. var param = {alias:'myalias',tags:['tag1','tag2']};
  3. ajpush.bindAliasAndTags(param,function(ret) {
  4. var statusCode = ret.statusCode;
  5. });

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

onResume

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

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

onResume()

示例代码

  1. api.addEventListener({name:'resume'}, function(ret,err) {
  2. var ajpush = api.require('ajpush');
  3. ajpush.onResume();
  4. });

可用性

Android系统

可提供的1.0.0及更高版本

onPause

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

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

onPause()

示例代码

  1. api.addEventListener({name:'pause'}, function(ret,err) {
  2. var ajpush = api.require('ajpush');
  3. ajpush.onPause();
  4. });

可用性

Android系统

可提供的1.0.0及更高版本

clearNotification

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

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

params

id:

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

callback(ret, err)

ret:

  • 类型:JSON 对象

内部字段:

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

示例代码

  1. var ajpush = api.require('ajpush');
  2. var param = {id:-1};
  3. ajpush.clearNotification(param,function(ret) {
  4. if(ret && ret.status){
  5. //success
  6. }
  7. });

可用性

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 对象

内部字段:

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

示例代码

  1. var ajpush = api.require('ajpush');
  2. var params = {};
  3. params.days = [1,2];
  4. params.startHour = 8;
  5. params.endHour = 20;
  6. ajpush.setPushTime(params, function(ret) {
  7. if(ret && ret.status){
  8. //success
  9. }
  10. });

补充说明

默认情况下用户在任何时间都允许推送。即任何时候有推送下来,客户端都会收到,并展示。开发者可以调用此 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 对象

内部字段:

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

示例代码

  1. var ajpush = api.require('ajpush');
  2. var params = {};
  3. params.startHour = 8;
  4. params.startMinute = 0;
  5. params.endHour = 20;
  6. params.endMinute = 59;
  7. ajpush.setPushTime(params, function(ret) {
  8. if(ret && ret.status){
  9. //success
  10. }
  11. });

补充说明

默认情况下用户在收到推送通知时,客户端可能会有震动,响铃等提示。但用户在睡觉、开会等时间点希望为 “免打扰” 模式,也是静音时段的概念。开发者可以调用此 API 来设置静音时段。如果在该时间段内收到消息,则:不会有铃声和震动。

可用性

Android系统

可提供的1.0.0及更高版本

stopPush

停止Push推送。

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

stopPush(callback(ret, err))

callback(ret, err)

ret:

  • 类型:JSON 对象

内部字段:

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

示例代码

  1. var ajpush = api.require('ajpush');
  2. ajpush.stopPush(function(ret) {
  3. if(ret && ret.status){
  4. //success
  5. }
  6. });

可用性

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 对象

内部字段:

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

示例代码

  1. var ajpush = api.require('ajpush');
  2. ajpush.resumePush(function(ret) {
  3. if(ret && ret.status){
  4. //success
  5. }
  6. });

可用性

iOS系统、Android系统

可提供的1.0.0及更高版本

isPushStopped

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

isPushStopped(callback(ret, err))

callback(ret, err)

ret:

  • 类型:JSON 对象

内部字段:

  1. {
  2. isStopped:1 //推送服务是否停止状态,1-停止,0-未停止
  3. }

示例代码

  1. var ajpush = api.require('ajpush');
  2. ajpush.isPushStopped(function(ret) {
  3. if(ret && ret.isStopped){
  4. }
  5. });

可用性

iOS系统、Android系统

可提供的1.0.0及更高版本

setBadge

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

setBadge({params})

params

badge:

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

示例代码

  1. var ajpush = api.require('ajpush');
  2. ajpush.setBadge({
  3. badge:0
  4. });

可用性

iOS系统

可提供的1.0.0及更高版本

getRegistrationId

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

getRegistrationId(callback(ret, err))

callback(ret, err)

ret:

  • 类型:JSON 对象

内部字段:

  1. {
  2. id:'' //RegistrationID
  3. }

示例代码

  1. var ajpush = api.require('ajpush');
  2. ajpush.getRegistrationId(function(ret) {
  3. var registrationId = ret.id;
  4. });

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

其他重要信息

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

  1. api.addEventListener({
  2. name: 'appintent'
  3. }, function(ret, err) {
  4. if (ret && ret.appParam.ajpush) {
  5. var ajpush = ret.appParam.ajpush;
  6. var id = ajpush.id;
  7. var title = ajpush.title;
  8. var content = ajpush.content;
  9. var extra = ajpush.extra;
  10. }
  11. })

在iOS平台,使用极光推送发送通知时,若应用在前台运行,则推送内容可以通过setListener方法监听到,若应用在后台,系统会往设备通知栏发送通知,当通知被点击后,APICloud会将本次推送的内容通过事件监听回调的方式交给开发者。具体使用如下:

  1. api.addEventListener({
  2. name: 'noticeclicked'
  3. }, function(ret, err) {
  4. if (ret && ret.value) {
  5. var ajpush = ret.value;
  6. var content = ajpush.content;
  7. var extra = ajpush.extra;
  8. }
  9. })

自定义推送声音

参考论坛帖子详细步骤:官方版极光推送(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:网络连接超时

论坛示例

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