Skip to content

GetuiLaboratory/getui-apicloud-ios

Repository files navigation

#个推 APICloud iOS SDK 集成文档

概述

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应用。

关于透传消息的

受到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**

初始化推送服务

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及更高版本

About

个推官方提供的推送SDK APICloud 插件(支持iOS)

Topics

Resources

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published