ajpush

Method

论坛示例

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

概述

ajpush原生插件封装了极光推送平台的SDK，使用此原生插件可实现接收推送通知和透传消息功能。

注意：使用了ajpush或者其他非YonBuilder移动开发平台提供的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>
    // <!--   HarmonyOS start -->
     <feature name="ajpush">
        <param name="HarmonyOS_APPKEY" value="123456789" />   <!--   极光申请的appKey-->
    </feature>
   //  <!--  HarmonyOS end  -->

字段描述:

    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"/>

HarmonyOS 极光推送重要配置说明：

极光鸿蒙sdk配置引导参考极光官网：https://docs.jiguang.cn/jpush/client/HarmonyOS/hmos_guid
需要在本地工程配置应用的 client_id、配置通知跳转页以及配置自定义信息等可以在widget/res/hos目录下新建module.json5文件，在module.json5文件中配置按照极光官网配置引导自行配置，此文件编译时会合并到工程的module.json5中。

module.json5文件配置示例：

{
  "module": {
     "metadata": [
      {
        "name": "client_id",
        "value": "112282737(替换为自己申请的client_id)"
      }
    ],
    "proxyData":[{
      "uri": "datashareproxy://com.yonyou.jpushvip(替换为自己的包名)/PushMessage",
      "requiredWritePermission": "ohos.permission.WRITE_PRIVACY_PUSH_DATA",
      "metadata":{
        "name": "dataProperties",
        "resource": "$profile:PushMessage"
      }
    }],
    "extensionAbilities": [
      {
        "name": "RemoteNotificationExtAbility",
        "type": "remoteNotification",
        "srcEntry": "./ets/entryability/EntryAbility.ets",//点击通知栏通知打开应用首页
        "description": "RemoteNotificationExtAbility test",
        "exported": false,
        "skills": [
          {
            "actions": ["action.hms.push.extension.remotenotification"]
          }
        ]
      }
    ]
  }
}
```js


# **setAuth**<div id="setAuth"></div>

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

setAuth(callback(ret))

## params

auth：

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

## callback(ret)

ret：

- 类型：JSON 对象

内部字段：

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

示例代码

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

可用性

ios系统，Android系统、harmonyOS

可提供的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系统、harmonyOS

可提供的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系统、harmonyOS

可提供的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系统、harmonyOS

可提供的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系统、harmonyOS

可提供的 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系统、harmonyOS

可提供的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系统、harmonyOS

可提供的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系统、harmonyOS

可提供的 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系统、harmonyOS

可提供的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系统、harmonyOS

可提供的1.0.0及更高版本

resumePush

恢复Push推送。

注意：需要额外在config.xml里面配置 js <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系统、harmonyOS

可提供的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系统、harmonyOS

可提供的1.0.0及更高版本

setBadge

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

setBadge({params})

params

badge：

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

示例代码

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

可用性

Android系统、iOS系统、harmonyOS

可提供的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系统、harmonyOS

可提供的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;
    }
})

注意：HarmonyOs平台目前不支持api.addEventListener方法，点击通知可以在setListener接口中获取到通知具体内容

自定义推送声音

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

论坛示例

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

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

最后更新于 2024/12/2