pushGeTui

来自于：个推立即使用

initialize registerDeviceToken

概述

pushGeTui封装了个推消息推送平台的SDK，使用此模块可轻松实现服务端向客户端推送通知和透传消息的功能。

名词解释：

CID：用于标识推送目标的用户ID；CID全局唯一；同一手机不同包名的应用拥有不同的CID；正常情况下，CID会在SD卡进行存储，因此即使应用卸载重装，CID也保持不变；但SD卡缓存文件被清理的情况下，应用卸载重装CID会变更，第三方应用需要及时将最新的CID更新到第三方服务端

APPKEY/APPID：从个推平台上的获得的应用标识

个推支持以下三种消息推送形式：

1.指定单个CID进行消息单推；

2.指定一组CID进行消息批量推送；

3.指定同一APPID下的所有CID进行全量推送。

个推消息推送基本流程说明：

1.在个推开放平台（ http://dev.getui.com ）注册帐号，并创建应用，获取APPKEY/APPID/APPSECRET参数。具体流程常见“个推开放API配置指南”

2.在config中配置pushGeTui feature，填写上述应用参数

3.应用启动后调用initialize进行推送SDK初始化，并调用register接口注册透传消息监听器；

4.推送服务获取到推送标识CID后返回给JS层，应用一般需要将该CID和用户ID做一个绑定，记录到服务端；

5.服务端指定CID进行透传消息推送（可以通过个推开放平台直接操作，也可以使用服务端SDK调用消息推送接口），携带透传消息内容Payload

6.推送服务接收到消息后，通过register接口注册的消息监听器回调给JS层

7.JS层处理透传消息内容Payload，进行相应的处理。

8.服务端也可以指定CID进行通知消息推送，通知点击后启动APICloud应用。

9.补充说明，如果用户需要点击通知并执行相应的后续动作，例如跳转至指定的界面等，则需要在个推开发者平台的推送通知界面，点击高级设置中的透传消息，配置相应的透传信息，这样用户点击通知后，应用将会收到通知附带的透传信息，在 initialize(callback(ret, err)) 中有回调，用于执行后续动作；如果采用的是个推服务端的SDK，则流程同理。

关于透传消息的

受到JS层目前机制限制，如果apicloud应用未运行，JS层是无法处理透传数据的。

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

  1. 名称：pushGeTui
  2. 参数：android_appkey,android_appid,android_appsecret,android_groupid
  3. 描述：配置个推应用信息
  1.     <feature name="pushGeTui">
  2.         <param name="ios_appkey" value="xCGkZR1bCp6gscLUB20Dl4" />
  3.         <param name="ios_appid" value="G5lfFkQZ008VoZUXydA2r2" />
  4.         <param name="ios_appsecret" value="RuxlC8ExWA7T4NFoJhQFd6" />
  5.         <param name="android_appkey" value="aiMe49ehZa7IK8sevOTiY8" />
  6.         <param name="android_appid" value="h5AH1rK4KW7vfFGZjT7fG" />
  7.         <param name="android_appsecret" value="wx7779c7c063a9d4d9" />
  8.         <param name="android_groupid" value="" />
  9.     </feature>

字段描述:

  1.     1.android_appkey：通过个推平台获得
  2.     2.android_appid：应用ID，通过个推平台获得
  3.     3.android_appsecret：通过个推平台获得
  4.     4.android_groupid: 目前留空即可

接口设计说明 一、cid、payload、occurError都使用通过initialize传递进去的callback，所有的回调里面都定义了一个type参数，我们可以通过判断type参数来判断回调的类型. type类型参数说明： 1、cid:初始化（initialize）回调回来的cid； 2、payload：下发payload消息； 3、apns: 苹果官方 APNs 推送，即应用在后台时收到的推送消息，若通过点击该推送消息打开应用，则收到该类型的回调，可用于判断是否点击推送消息打开应用； 4、occurError：所有发生错误时候的回调；

二、返回值result值说明： 1、0：失败 2、1：成功 3、-100：不支持的接口

  1. function callback(ret, err){
  2.       var log;
  3.       switch(ret.type)
  4.       {
  5.           case 'cid':
  6.           log='cid:'+ret.cid;
  7.           break;
  8.           case 'payload':
  9.           log='payload:'+ret.payload;
  10.           break;
  11.           case 'occurError':
  12.           log='occurError';
  13.           break;
  14.       }
  15.     }

错误类型回调json

  1. {
  2.     code:300,
  3.     description:"error msg",
  4.     type:"occurError"
  5. }

initialize

初始化推送服务

initialize(callback(ret, err))

callback(ret, err)

ret：

  • 类型：JSON 对象

内部字段：

  1. // cid
  2. {
  3.     result:1                              //操作成功状态值
  4.     type:"cid"                              //CID 类型
  5.   cid:"sdwe435236fdfd"                   //返回的cid的值
  6. }
  7. // payload
  8. {
  9.     result:1                                //操作成功状态值
  10.     type:"payload"                          //payload 类型
  11.     taskId:"taskId"                         //taskId 值
  12.     messageId:"messageId"                   //messageId 值
  13.     payload:"payload"                       //payload 内容
  14.     offLine:"true"                          //判断推送时app是杀死还是启动状态
  15. }
  16. // apns
  17. {
  18.     result:1                              //操作成功状态值
  19.     type:"apns"                           //apns 类型
  20.     msg:"msg"                               //apns 消息体
  21. }
  22. // occurError
  23. {
  24.     code:"errorCode"                        //错误吗
  25.     description:"error description"         //错误描述
  26.     type:"occurError"                       //occurError 类型
  27. }
  28. // onNotificationMessageArrived
  29. {
  30.      type:"onNotificationMessageArrived"     //通知到达
  31.      taskid:"tasid"                          //taskid
  32.      messageid:"messageid"                   //消息id
  33.      title:"title"                           //消息标题
  34.      content:"content"                       //消息内容
  35. }
  36. // AppLinkReceive
  37. {
  38.       result:1
  39.       type:"AppLinkPayload"
  40.       payload:"msg"
  41. }

err：

  • 类型：JSON 对象

内部字段：

  1. {
  2.     code:0       //错误码（详见错误码常量）
  3.     msg:""       //错误描述
  4. }

示例代码

  1. var uzgetuisdk = api.require('pushGeTui');
  2. uzgetuisdk.initialize(function(ret) {
  3.     var value = "";
  4.     switch (ret.type) {
  5.         case 'cid':
  6.             value = 'cid:' + ret.cid;
  7.             break;
  8.         case 'payload':
  9.             value = 'payload:' + ret.payload;
  10.             break;
  11.         case 'occurError':
  12.             value = 'occurError';
  13.             break;
  14.         case'onNotificationMessageClicked':
  15.           value = 'onNotificationMessageClicked' + ret.onNotificationMessageClicked
  16.           break;
  17.         case'onNotificationMessageArrived':
  18.           value = 'onNotificationMessageArrived' + ret.onNotificationMessageArrived
  19.           break;
  20.     }
  21. });

补充说明

在每次应用启动的初始化过程中，都需要调用个推SDK初始化函数。这时候传递的参数callback将会用于cid、payload、occurError的回调。

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

registerDeviceToken

注册deviceToken

registerDeviceToken(callback(ret, err))

callback(ret, err)

ret：

  • 类型：JSON 对象

内部字段：

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

示例代码

  1. function registerDeviceToken() {
  2.     var param = {
  3.         deviceToken: api.deviceToken,
  4.     };
  5.     uzgetuisdk.registerDeviceToken(param, function(ret, err) {
  6.         var log = 'registerDeviceToken:' + ret.result;
  7.         console.log(log);
  8.     });
  9. }

补充说明

如果发生错误会在occurError里面回调。

可用性

iOS系统

可提供的1.0.0及更高版本

setTag bindAlias unBindAlias stopService sendFeedbackMessage fetchClientId setBadge

setTag

为用户设置标签。针对单个CID设置标签（tag）列表，服务端推送可以指定标签进行定向群发

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

params

tags：

  • 类型：字符串
  • 默认值：无
  • 描述：标签列表，以逗号(,)分割，标签名建议采用英文和数字的组合

callback(ret, err)

ret：

  • 类型：JSON 对象

内部字段：

  1. {
  2.     result:1               //操作成功状态值
  3. }

err：

  • 类型：JSON 对象

内部字段：

  1. {
  2.     code:0       //错误码（详见错误码常量）
  3.     msg: ""      //错误描述
  4. }

示例代码

  1. var uzgetuisdk = api.require('pushGeTui');
  2. var param = { tags: "tag1,tag2" };
  3. uzgetuisdk.setTag(param, function(ret) {
  4.     api.alert({ msg: "setTag result:" + ret.result });
  5. });

补充说明

（暂无）

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

bindAlias

绑定用户别名。针对单个CID设置别名，一个别名可以对应多个CID。可以指定别名进行消息推送

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

params

alias：

  • 类型：字符串
  • 默认值：无
  • 描述：别名，建议采用英文和数字组合

callback(ret, err)

ret：

  • 类型：JSON 对象

内部字段：

  1. {
  2.     result:1               //操作成功状态值
  3. }

err：

  • 类型：JSON 对象

内部字段：

  1. {
  2.     code:0       //错误码（详见错误码常量）
  3.     msg: ""      //错误描述
  4. }

示例代码

  1. var uzgetuisdk = api.require('pushGeTui');
  2. var param = { alias: "myalias" };
  3. uzgetuisdk.bindAlias(param, function(ret) {
  4.     api.alert({ msg: "bindAlias result:" + ret.result });
  5. });

补充说明

（暂无）

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

unBindAlias

解绑用户别名。针对单个CID取消设置别名。

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

params

alias：

  • 类型：字符串
  • 默认值：无
  • 描述：别名，建议采用英文和数字组合

callback(ret, err)

ret：

  • 类型：JSON 对象

内部字段：

  1. {
  2.     result:"1"               //操作成功状态值
  3. }

err：

  • 类型：JSON 对象

内部字段：

  1. {
  2.     code:0       //错误码（详见错误码常量）
  3.     msg: ""      //错误描述
  4. }

示例代码

  1. var uzgetuisdk = api.require('pushGeTui');
  2. var param = { alias: "myalias" };
  3. uzgetuisdk.unBindAlias(param, function(ret) {
  4.     api.alert({ msg: "unbindAlias result:" + ret.result });
  5. });

补充说明

（暂无）

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

stopService

完全停止SDK的服务。停止推送服务，停止所有业务逻辑

stopService(callback(ret, err))

callback(ret, err)

ret：

  • 类型：JSON 对象

内部字段：

  1. {
  2.     result:"1"               //操作成功状态值
  3. }

err：

  • 类型：JSON 对象

内部字段：

  1. {
  2.     code:0       //错误码（详见错误码常量）
  3.     msg: ""      //错误描述
  4. }

示例代码

  1. var uzgetuisdk = api.require('pushGeTui');
  2. uzgetuisdk.stopService(function(ret) {
  3.     api.alert({ msg: "stopService result:" + ret.result });
  4. });

补充说明

（暂无）

可用性

Android系统

可提供的1.0.0及更高版本

sendFeedbackMessage

上行第三方自定义回执。第三方指定自定义actionid，便于对推送效果做统计分析。

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

params

taskid：

  • 类型：字符串
  • 默认值：无
  • 描述：接收的透传消息任务id

messageid：

  • 类型：字符串
  • 默认值：无
  • 描述：接收的透传消息id

actionid：

  • 类型：int
  • 默认值：无
  • 描述：自定义动作id，范围为90001-90999。第三方可以对支付、页面访问等用户操作进行打点。

callback(ret, err)

ret：

  • 类型：JSON 对象

内部字段：

  1. {
  2.     result:"1"               //操作成功状态值
  3. }

err：

  • 类型：JSON 对象

内部字段：

  1. {
  2.     code:0       //错误码（详见错误码常量）
  3.     msg: ""      //错误描述
  4. }

示例代码

  1. var uzgetuisdk = api.require('pushGeTui');
  2. var param = { taskid: "GT_1012_AKMw2kc2Oj5Tzy1DvXjMQA", messageid: "GT_1012_AKMw2kc2Oj5Tzy1DvXjMQA", actionid: 90001 };
  3. uzgetuisdk.sendFeedbackMessage(param, function(ret) {
  4.     api.alert({ msg: "sendFeedbackMessage result:" + ret.result });
  5. });

补充说明

（暂无）

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

fetchClientId

获取cid

fetchClientId(callback(ret, err))

callback(ret, err)

ret：

  • 类型：JSON 对象

内部字段：

  1. {
  2.   result:1;
  3.     cid:"0580dc70460e71d5e55a3fec4c0ae92x"               
  4. }

示例代码

  1. var uzgetuisdk = api.require('pushGeTui');
  2. uzgetuisdk.fetchClientId(function(ret, err) {
  3.     api.alert({ msg: "cid:" + ret.cid });
  4. });

补充说明

（暂无）

可用性

android系统 iOS系统

可提供的1.0.0及更高版本

setBadge

设置角标功能,同步服务器角标计数

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

params

badge：

  • 类型：int
  • 默认值：无
  • 描述：角标值，0 为重置角标

callback(ret, err)

ret：

  • 类型：JSON 对象

内部字段：

  1. {
  2.     result:1               //操作成功状态值
  3. }

err：

  • 类型：JSON 对象

内部字段：

  1. {
  2.     code:0       //错误码（详见错误码常量）
  3.     msg: ""      //错误描述
  4. }

示例代码

  1. var uzgetuisdk = api.require('pushGeTui');
  2. var param = { badge: 1 };
  3. uzgetuisdk.setBadge(param, function(ret) {
  4.     api.alert({ msg: "setBadge result:" + ret.result });
  5. });

补充说明

（暂无）

可用性

iOS系统

可提供的大于 1.1.9 的版本

turnOnPush turnOffPush isPushTurnedOn getVersion setSilentTime sendMessage payloadMessage voipRegistration

turnOnPush

开启Push推送。继续服务端连接。常见turnOffPush

turnOnPush(callback(ret, err))

callback(ret, err)

ret：

  • 类型：JSON 对象

内部字段：

  1. {
  2.     result:1               //操作成功状态值
  3. }

err：

  • 类型：JSON 对象

内部字段：

  1. {
  2.     code:0       //错误码（详见错误码常量）
  3.     msg: ""      //错误描述
  4. }

示例代码

  1. var uzgetuisdk = api.require('pushGeTui');
  2. uzgetuisdk.turnOnPush(function(ret) {
  3.     api.alert({msg:"turnOnPush result:" + ret.result});
  4. });

补充说明

（暂无）

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

turnOffPush

关闭Push推送。暂停服务端连接，即使调用initialize也不会继续服务端连接。

turnOffPush(callback(ret, err))

callback(ret, err)

ret：

  • 类型：JSON 对象

内部字段：

  1. {
  2.     result:1              //操作成功状态值
  3. }

err：

  • 类型：JSON 对象

内部字段：

  1. {
  2.     code:0       //错误码（详见错误码常量）
  3.     msg: ""      //错误描述
  4. }

示例代码

  1. var uzgetuisdk = api.require('pushGeTui');
  2. uzgetuisdk.turnOffPush(function(ret) {
  3.     api.alert({msg:"turnOffPush result:" + ret.result});
  4. });

补充说明

（暂无）

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

isPushTurnedOn

获取当前推送服务开关状态。该状态只和turnOnPush和turnOffPush操作相关

isPushTurnedOn(callback(ret, err))

callback(ret, err)

ret：

  • 类型：JSON 对象

内部字段：

  1. {
  2.     result:1                   //操作成功状态值
  3.     isOn:"true"                  //推送服务状态
  4. }

err：

  • 类型：JSON 对象

内部字段：

  1. {
  2.     code:0       //错误码（详见错误码常量）
  3.     msg: ""      //错误描述
  4. }

示例代码

  1. var uzgetuisdk = api.require('pushGeTui');
  2. uzgetuisdk.isPushTurnedOn(function(ret) {
  3.     api.alert({msg:"isPushTurnedOn result:" + ret.isOn});
  4. });

补充说明

（暂无）

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

getVersion

获取SDK版本号。

getVerison(callback(ret, err))

callback(ret, err)

ret：

  • 类型：JSON 对象

内部字段：

  1. {
  2.     result:1                   //操作成功状态值
  3.     version:"2.3.0.0.apicloud"    //SDK版本号
  4. }

err：

  • 类型：JSON 对象

内部字段：

  1. {
  2.     code:0       //错误码（详见错误码常量）
  3.     msg: ""      //错误描述
  4. }

示例代码

  1. var uzgetuisdk = api.require('pushGeTui');
  2. uzgetuisdk.getVersion(function(ret) {
  3.     api.alert({msg:"getVersion result:" + ret.version});
  4. });

补充说明

（暂无）

可用性

Android系统，iOS系统

可提供的1.0.0及更高版本

setSilentTime

设置SDK静默时间。在指定时间段内，暂停推送服务联网，可以避免用户打扰，同时起到省电省流量的作用。

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

params

beginHour：

  • 类型：int
  • 默认值：无
  • 描述：静默时间段开始时间点，单位小时，取值范围：0-23

duration：

  • 类型：int
  • 默认值：无
  • 描述：静默时间段持续时间，单位小时，取值范围：0-24

解释说明：

  • 例如：beginHour=9、duration=12，含义为早9点到晚9点之间静默
  • 例如：beginHour=21、duration=12，含义为晚9点到早9点之间静默

callback(ret, err)

ret：

  • 类型：JSON 对象

内部字段：

  1. {
  2.     result:1              //操作成功状态值
  3. }

err：

  • 类型：JSON 对象

内部字段：

  1. {
  2.     code:0       //错误码（详见错误码常量）
  3.     msg: ""      //错误描述
  4. }

示例代码

  1. var uzgetuisdk = api.require('pushGeTui');
  2. var param = {beginHour:9,duration:12};
  3. uzgetuisdk.setSilentTime(param,function(ret) {
  4.     api.alert({msg:"setSilentTime result:" + ret.result});
  5. });

可用性

Android系统

可提供的1.0.0及更高版本

sendMessage

发送上行消息，服务端使用MMP SDK接收客户端发送的上行消息。

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

params

taskid：

  • 类型：字符串
  • 默认值：无
  • 描述：由客户端生成的上行消息任务id，便于后续跟踪消息

extraData：

  • 类型：字符串
  • 默认值：无
  • 描述：上行消息内容，由客户端自行定义，建议采用json格式

callback(ret, err)

ret：

  • 类型：JSON 对象

内部字段

  1. {
  2.   result:1                                //操作成功状态值
  3. }

err：

  • 类型：JSON 对象

内部字段：

  1. {
  2.     code:0       //错误码（详见错误码常量）
  3.     msg: ""      //错误描述
  4. }

示例代码

  1. var uzgetuisdk = api.require('pushGeTui');
  2. var param = { taskid: "SX_1111_ABCDEFG", extraData: "any_command" };
  3. uzgetuisdk.sendMessage(param, function(ret) {
  4.     api.alert({ msg: "sendMessage result:" + ret.result });
  5. });

补充说明

（暂无）

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

payloadMessage

app 处于未启动状态时，点击通知打开程序获取透传消息。

payloadMessage(callback(ret, err))

callback(ret, err)

ret：

  • 类型：JSON 对象

内部字段：

  1. {
  2.     payload:""               //透传内容
  3. }

err：

  • 类型：JSON 对象

内部字段：

  1. {
  2.     code:0       //错误码（详见错误码常量）
  3.     msg: ""      //错误描述
  4. }

示例代码

  1. uzgetuisdk.payloadMessage(function(ret) {
  2.     api.alert({msg:"payloadMessag:" + ret.payload});
  3. });

可用性

Android系统

可提供的1.0.0及更高版本

voipRegistration

推送voip通知。

voipRegistration(callback(ret, err))

callback(ret, err)

ret：

  • 类型：JSON 对象

内部字段：

  1. {
  2.     result:1                   // 操作成功状态值
  3.     payload:"payload msg"        // VoIP 推送消息体
  4.     gmid:""                        // 唯一标识
  5.     type:"voipPayload"            // 类型为 voipPayload
  6. }

err：

  • 类型：JSON 对象

内部字段：

  1. {
  2.     code:0       //错误码（详见错误码常量）
  3.     msg: ""      //错误描述
  4. }

示例代码

  1. var uzgetuisdk = api.require('pushGeTui');
  2. uzgetuisdk.voipRegistration(function(ret,err){
  3.     alert("voip callback = " + JSON.stringify(ret) + "err = " + JSON.stringify(err));
  4. });

补充说明

VoIP 功能需要添加后台运行权限，因此需要在 config.xml 添加如下字段：

  1.    <preference name="backgroundMode" value="remote-notification|voip"/>

可用性

iOS系统

可提供的2.0.2及更高版本