概述

#个推 APICloud iOS SDK 集成文档

基础接口
扩展接口
高级接口

概述

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

名词解释：

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

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

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

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

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

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

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

在个推开放平台（ http://dev.getui.com ）注册帐号，并创建应用，获取APPKEY/APPID/APPSECRET参数。具体流程常见“个推开放API配置指南”
在config中配置pushGeTui feature，填写上述应用参数
应用启动后调用initialize进行推送SDK初始化，并调用register接口注册透传消息监听器；
推送服务获取到推送标识CID后返回给JS层，应用一般需要将该CID和用户ID做一个绑定，记录到服务端；
服务端指定CID进行透传消息推送（可以通过个推开放平台直接操作，也可以使用服务端SDK调用消息推送接口），携带透传消息内容Payload
推送服务接收到消息后，通过register接口注册的消息监听器回调给JS层
JS层处理透传消息内容Payload，进行相应的处理。
服务端也可以指定CID进行通知消息推送，通知点击后启动APICloud应用。

关于透传消息的

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

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

名称：pushGeTui
参数：android_appkey,android_appid,android_appsecret,android_groupid
描述：配置个推应用信息

	<feature name="pushGeTui">
	  <param name="ios_appkey" value="xCGkZR1bCp6gscLUB20Dl4" />
		<param name="ios_appid" value="G5lfFkQZ008VoZUXydA2r2" />
		<param name="ios_appsecret" value="RuxlC8ExWA7T4NFoJhQFd6" />
		<param name="android_appkey" value="aiMe49ehZa7IK8sevOTiY8" />
		<param name="android_appid" value="h5AH1rK4KW7vfFGZjT7fG" />
		<param name="android_appsecret" value="wx7779c7c063a9d4d9" />
		<param name="android_groupid" value="" />
	</feature>

字段描述:

	1.android_appkey：通过个推平台获得
	2.android_appid：应用ID，通过个推平台获得
	3.android_appsecret：通过个推平台获得
	4.android_groupid: 目前留空即可
    5.active_show_notification iOS平台前台收到通知是否展示
    6.ios_appsecret：通过个推平台获得
    7.ios_appid：应用ID，通过个推平台获得
    8.ios_appkey：通过个推平台获得

接口设计说明 一、cid、payload、occurError都使用通过initialize传递进去的callback，所有的回调里面都定义了一个type参数，我们可以通过判断type参数来判断回调的类型. type类型参数说明： 1、cid:初始化（initialize）回调回来的cid；

2、payload：下发payload消息；

3、occurError：所有发生错误时候的回调；

4、status：SDK运行状态通知

5、tags：设置标签回调

6、queryTag：查询当前绑定tag结果返回

7、alias：SDK绑定、解绑回调
8、apns: 苹果官方 APNs 推送，即应用在后台时收到的推送消息，若通过点击该推送消息打开应用，则收到该类型的回调，可用于判断是否点击推送消息打开应用；

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

function callback(ret,err){
      var log;
      switch(ret.type)
      {
          case 'cid':
            log='cid:'+ret.cid;
          break;
          case 'payload':
            log='payload:'+ret.payload;
          break;
          case 'apns':
            log='apns click:'+ret.result+' msg:'+ret.msg;
          break;
          case 'willPresentNotification':
            log='willPresentNotification:'+ret.result+' msg:'+ret.msg;
          break;
          case 'openSettings':
            log='openSettingsForNotification:';
          break;
          case'occurError':
            log='occurError';
          break;
          case 'sendMsgFeedback':
            log='sendMsgFeedback:'+ret.result+' messageid:'+ret.messageId;
          break;
          case 'AppLinkPayload':
            log='applink:'+ret.result+' msg:'+ret.payload;
          break;
      }
    }

错误类型回调json

{
    code:300,
    description:"error msg",
    type:"occurError"
}

initialize

registerDeviceToken

# **initialize**

初始化推送服务

initialize(callback(ret, err))

callback(ret, err)

ret：

类型：JSON对象

内部字段：

// cid
{
	result:1                              //操作成功状态值
	type:"cid"                              //CID 类型
  cid:"sdwe435236fdfd"                   //返回的cid的值
}
// payload
{
	result:1                              //操作成功状态值
	type:"payload"                          //payload 类型
	taskId:"taskId"                         //taskId 值
	messageId:"messageId"                   //messageId 值
	payload:"payload"                       //payload 内容
}
// occurError
{
	code:"errorCode"                        //错误吗
	description:"error description"         //错误描述
	type:"occurError"                       //occurError 类型
}

err：

类型：JSON对象

内部字段：

{
	code:0       //错误码（详见错误码常量）
	msg:""       //错误描述
}

示例代码

var uzgetuisdk = api.require('pushGeTui');
uzgetuisdk.initialize(function(ret) {
    var value = "";
    switch (ret.type) {
        case 'cid':
            value = 'cid:' + ret.cid;
            break;
        case 'payload':
            value = 'payload:' + ret.payload;
            break;
        case 'occurError':
            value = 'occurError';
            break;
    }
});

补充说明

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

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

registerDeviceToken

注册deviceToken

registerDeviceToken(callback(ret, err))

callback(ret, err)

ret：

类型：JSON对象

内部字段：

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

示例代码

function registerDeviceToken(){
        var param={
            deviceToken:api.deviceToken,
        };
        push.registerDeviceToken(param,function(ret,err){
            var log='registerDeviceToken:'+ret.result;
            printfLog(log);
        });
    }

补充说明

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

可用性

iOS系统

可提供的1.0.0及更高版本

<div><a href="#b1"> setTag </a></div>
<div><a href="#b2"> bindAlias </a></div>
<div><a href="#b3"> unBindAlias </a></div>
<div><a href="#b4"> stopService </a></div>
<div><a href="#b5"> sendFeedbackMessage </a></div>
<div><a href="#b6"> fetchClientId </a></div>
<div><a href="#b7"> setBadge </a></div>

setTag

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

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

params

tags：

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

callback(ret, err)

ret：

类型：JSON对象

内部字段：

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

err：

类型：JSON对象

内部字段：

{
    code:0       //错误码（详见错误码常量）
    msg: ""      //错误描述
}

示例代码

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

补充说明

（暂无）

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

bindAlias

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

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

params

alias：

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

callback(ret, err)

ret：

类型：JSON对象

内部字段：

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

err：

类型：JSON对象

内部字段：

{
    code:0       //错误码（详见错误码常量）
    msg: ""      //错误描述
}

示例代码

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

补充说明

（暂无）

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

unBindAlias

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

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

params

alias：

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

callback(ret, err)

ret：

类型：JSON对象

内部字段：

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

err：

类型：JSON对象

内部字段：

{
    code:0       //错误码（详见错误码常量）
    msg: ""      //错误描述
}

示例代码

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

补充说明

（暂无）

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

stopService

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

stopService(callback(ret, err))

callback(ret, err)

ret：

类型：JSON对象

内部字段：

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

err：

类型：JSON对象

内部字段：

{
    code:0       //错误码（详见错误码常量）
    msg: ""      //错误描述
}

示例代码

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

补充说明

（暂无）

可用性

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

内部字段：

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

err：

类型：JSON对象

内部字段：

{
    code:0       //错误码（详见错误码常量）
    msg: ""      //错误描述
}

示例代码

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

补充说明

（暂无）

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

fetchClientId

获取cid

fetchClientId(callback(ret, err))

callback(ret, err)

ret：

类型：JSON对象

内部字段：

{
  result:1;
	cid:"0580dc70460e71d5e55a3fec4c0ae92x"               
}

示例代码

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

补充说明

（暂无）

可用性

android系统 iOS系统

可提供的1.0.0及更高版本

setBadge

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

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

params

badge：

类型：int
默认值：无
描述：0

callback(ret, err)

ret：

类型：JSON对象

内部字段：

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

err：

类型：JSON对象

内部字段：

{
    code:0       //错误码（详见错误码常量）
    msg: ""      //错误描述
}

示例代码

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

补充说明

（暂无）

可用性

iOS系统

version > 1.1.9

# runBackgroundOn

允许SDK 后台运行

示例代码

var uzgetuisdk = api.require('pushGeTui');
uzgetuisdk.runBackgroundOn(function(ret) {
	api.alert({msg:"runBackgroundOn result:" + ret.result});
});

runBackgroundOff

不允许SDK 后台运行

示例代码

var uzgetuisdk = api.require('pushGeTui');
uzgetuisdk.runBackgroundOff(function(ret) {
	api.alert({msg:"runBackgroundOff result:" + ret.result});
});

lbsLocationOn

地理围栏功能，设置地理围栏运行

var uzgetuisdk = api.require('pushGeTui');
uzgetuisdk.lbsLocationOn(function(ret) {
	api.alert({msg:"lbsLocationOn result:" + ret.result});
});

lbsLocationOff

地理围栏功能，设置地理围栏不运行

var uzgetuisdk = api.require('pushGeTui');
uzgetuisdk.lbsLocationOff(function(ret) {
	api.alert({msg:"lbsLocationOff result:" + ret.result});
});

turnOnPush

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

turnOnPush(callback(ret, err))

callback(ret, err)

ret：

类型：JSON对象

内部字段：

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

err：

类型：JSON对象

内部字段：

{
    code:0       //错误码（详见错误码常量）
    msg: ""      //错误描述
}

示例代码

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

补充说明

（暂无）

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

turnOffPush

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

turnOffPush(callback(ret, err))

callback(ret, err)

ret：

类型：JSON对象

内部字段：

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

err：

类型：JSON对象

内部字段：

{
    code:0       //错误码（详见错误码常量）
    msg: ""      //错误描述
}

示例代码

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

补充说明

（暂无）

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

isPushTurnedOn

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

isPushTurnedOn(callback(ret, err))

callback(ret, err)

ret：

类型：JSON对象

内部字段：

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

err：

类型：JSON对象

内部字段：

{
    code:0       //错误码（详见错误码常量）
    msg: ""      //错误描述
}

示例代码

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

补充说明

（暂无）

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

getVersion

获取SDK版本号。

getVerison(callback(ret, err))

callback(ret, err)

ret：

类型：JSON对象

内部字段：

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

err：

类型：JSON对象

内部字段：

{
    code:0       //错误码（详见错误码常量）
    msg: ""      //错误描述
}

示例代码

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

补充说明

（暂无）

可用性

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

内部字段：

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

err：

类型：JSON对象

内部字段：

{
    code:0       //错误码（详见错误码常量）
    msg: ""      //错误描述
}

示例代码

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

补充说明

（暂无）

可用性

Android系统

可提供的1.0.0及更高版本

sendMessage

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

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

params

taskid：

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

extraData：

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

callback(ret, err)

ret：

类型：JSON对象

内部字段

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

err：

类型：JSON对象

内部字段：

{
    code:0       //错误码（详见错误码常量）
    msg: ""      //错误描述
}

示例代码

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

补充说明

（暂无）

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

payloadMessage

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

payloadMessage(callback(ret, err))

callback(ret, err)

ret：

类型：JSON对象

内部字段：

{
	payload:""               //透传内容
}

err：

类型：JSON对象

内部字段：

{
    code:0       //错误码（详见错误码常量）
    msg: ""      //错误描述
}

示例代码

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

补充说明

（暂无）

可用性

Android系统

可提供的1.0.0及更高版本

Name		Name	Last commit message	Last commit date
Latest commit History 37 Commits
Demo		Demo
ModulesDevProject_iOS		ModulesDevProject_iOS
.gitignore		.gitignore
README.md		README.md
pushGeTui.md		pushGeTui.md
pushGeTui_2.4.0.0.zip		pushGeTui_2.4.0.0.zip
pushGeTui_2.4.1.0.zip		pushGeTui_2.4.1.0.zip
pushGeTui_2.6.8.0.zip		pushGeTui_2.6.8.0.zip
pushGeTui_3.0.7.0.zip		pushGeTui_3.0.7.0.zip

GetuiLaboratory/getui-apicloud-ios

Folders and files

Latest commit

History

Repository files navigation

概述

名词解释：

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

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

关于透传消息的

callback(ret, err)

示例代码

补充说明

可用性

registerDeviceToken

callback(ret, err)

示例代码

补充说明

可用性

setTag

params

callback(ret, err)

示例代码

补充说明

可用性

bindAlias

params

callback(ret, err)

示例代码

补充说明

可用性

unBindAlias

params

callback(ret, err)

示例代码

补充说明

可用性

stopService

callback(ret, err)

示例代码

补充说明

可用性

sendFeedbackMessage

params

callback(ret, err)

示例代码

补充说明

可用性

fetchClientId

callback(ret, err)

示例代码

补充说明

可用性

setBadge

params

callback(ret, err)

示例代码

补充说明

可用性

示例代码

runBackgroundOff

示例代码

lbsLocationOn

lbsLocationOff

turnOnPush

callback(ret, err)

示例代码

补充说明

可用性

turnOffPush

callback(ret, err)

示例代码

补充说明

可用性

isPushTurnedOn

callback(ret, err)

示例代码

补充说明

可用性

getVersion

Packages