getui-apicloud-android
工程,是基于 APICloud 架构之上的封装个推消息推送 SDK 的 Android 工程,使用此模块可轻松实现服务端向客户端推送通知和透传消息的功能。
CID:用于标识推送目标的用户ID;CID全局唯一;
同一手机不同包名的应用拥有不同的CID;正常情况下,CID会在SD卡进行存储,因此即使应用卸载重装,CID也保持不变;但SD卡缓存文件被清理的情况下,应用卸载重装CID会变更,第三方应用需要及时将最新的CID更新到第三方服务端
APPKEY/APPID:从个推平台上的获得的应用标识
-
指定单个CID进行消息单推;
-
指定一组CID进行消息批量推送;
-
指定同一APPID下的所有CID进行全量推送。
-
在个推开放平台注册帐号,并创建应用,获取
APPID
参数。具体流程常见个推开放API配置指南 -
在
APICloud Studio
中替换您APP应用参数
<meta-data name="GETUI_APPID" value="替换您在个推https://www.getui.com/注册的APPID"/>
<!-- 下面是多厂商参数 -->
<meta-data android:name="com.huawei.hms.client.appid" android:value="appid=替换您华为渠道APPID" />
<meta-data android:name="OPPOPUSH_APPKEY" android:value="OP_替换您OPPO渠道的APPKEY" />
<meta-data android:name="OPPOPUSH_APPSECRET" android:value="OP_替换您OPPO渠道的APPSECRET}" />
<meta-data android:name="com.vivo.push.app_id" android:value="替换您VIVO渠道的APPID" />
<meta-data android:name="com.vivo.push.api_key" android:value="替换您VIVO渠道的APPKEY" />
<meta-data android:name="MEIZUPUSH_APPID" android:value="MZ_替换您魅族渠道的APPID" />
<meta-data android:name="MEIZUPUSH_APPKEY" android:value="MZ_替换您魅族渠道的APPKEY" />
<meta-data android:name="MIPUSH_APPID" android:value="XM_替换您小米渠道的APPID" />
<meta-data android:name="MIPUSH_APPKEY" android:value="XM_替换您小米渠道的APPKEY" />
华为渠道接入需要完成配置文件读取
AGConnectServicesConfig config = AGConnectServicesConfig.fromContext(context);
config.overlayWith(new LazyInputStream(context) {
public InputStream get(Context context) {
try {
Log.d("Assist_", "-------->huawei------read config");
return context.getAssets().open("agconnect-services.json");
} catch (IOException e) {
return null;
}
}
});
-
应用启动后调用 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" />
</feature>
字段描述:
1.appkey:通过个推平台获得
2.appid:应用ID,通过个推平台获得
3.appsecret:通过个推平台获得
cid、payload、occurError,sendMessage都使用通过initialize传递进去的callback,所有的回调里面都定义了一个type参数,我们可以通过判断type参数来判断回调的类型. type类型参数说明: 1、cid:初始化(initialize)回调回来的cid; 2、payload:下发payload消息; 3、occurError:所有发生错误时候的回调;
function callback(ret,err){
var log;
switch(ret.type)
{
case 'cid':
log='cid:'+ret.cid;
break;
case 'payload':
log='payload:'+ret.payload;
break;
case'occurError':
log='occurError';
break;
case 'sendMsgFeedback':
log='sendMsgFeedback:'+ret.result+' messageid:'+ret.messageId;
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:"" //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 类型
}
// sendMsgFeedback
{
result:1 //操作成功状态值
type:"sendMsgFeedback" //sendMsgFeedback 类型
messageId:"messageId" //messageId
}
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;
case 'sendMsgFeedback':
value='sendMsgFeedback:'+ret.result+' messageid:'+ret.messageId;
break;
}
});
在每次应用启动的初始化过程中,都需要调用个推SDK初始化函数。
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>
为用户设置标签。针对单个CID设置标签(tag)列表,服务端推送可以指定标签进行定向群发
setTag({params},callback(ret, err))
tags:
- 类型:字符串
- 默认值:无
- 描述:标签列表,以逗号(,)分割,标签名建议采用英文和数字的组合
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及更高版本
绑定用户别名。针对单个CID设置别名,一个别名可以对应多个CID。可以指定别名进行消息推送
bindAlias({params},callback(ret, err))
alias:
- 类型:字符串
- 默认值:无
- 描述:别名,建议采用英文和数字组合
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及更高版本
解绑用户别名。针对单个CID取消设置别名。
unBindAlias({params},callback(ret, err))
alias:
- 类型:字符串
- 默认值:无
- 描述:别名,建议采用英文和数字组合
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系统(v3.0.0中已经废弃,不推荐使用)
可提供的1.0.0及更高版本
完全停止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))
taskid:
- 类型:字符串
- 默认值:无
- 描述:接收的透传消息任务id
messageid:
- 类型:字符串
- 默认值:无
- 描述:接收的透传消息id
actionid:
- 类型:int
- 默认值:无
- 描述:自定义动作id,范围为90001-90999。第三方可以对支付、页面访问等用户操作进行打点。
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});
});
(暂无)
Android系统
可提供的1.0.0及更高版本
#fetchClientId
获取cid
fetchClientId(callback(ret, err))
##callback(ret, err)
ret:
- 类型:JSON对象
内部字段:
{
cid:"0580dc70460e71d5e55a3fec4c0ae92x"
}
var uzgetuisdk = api.require('pushGeTui');
uzgetuisdk.fetchClientId(function(ret,err){
api.alert({msg:"cid:" + ret.cid});
});
(暂无)
iOS系统
可提供的1.0.0及更高版本
开启Push推送。继续服务端连接。常见turnOffPush
turnOnPush(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});
});
(暂无)
Android系统
可提供的1.0.0及更高版本
关闭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});
});
(暂无)
Android系统
可提供的1.0.0及更高版本
获取当前推送服务开关状态。该状态只和turnOnPush和turnOffPush操作相关
isPushTurnedOn(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});
});
(暂无)
Android系统
可提供的1.0.0及更高版本
获取SDK版本号。
getVerison(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系统
可提供的1.0.0及更高版本
设置SDK静默时间。在指定时间段内,暂停推送服务联网,可以避免用户打扰,同时起到省电省流量的作用。
setSilentTime({params},callback(ret, err))
beginHour:
- 类型:int
- 默认值:无
- 描述:静默时间段开始时间点,单位小时,取值范围:0-23
duration:
- 类型:int
- 默认值:无
- 描述:静默时间段持续时间,单位小时,取值范围:0-24
解释说明:
- 例如:beginHour=9、duration=12,含义为早9点到晚9点之间静默
- 例如:beginHour=21、duration=12,含义为晚9点到早9点之间静默
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及更高版本
发送上行消息,服务端使用MMP SDK接收客户端发送的上行消息。
sendMessage({params})
taskid:
- 类型:字符串
- 默认值:无
- 描述:由客户端生成的上行消息任务id,便于后续跟踪消息
extraData:
- 类型:字符串
- 默认值:无
- 描述:上行消息内容,由客户端自行定义,建议采用json格式
var uzgetuisdk = api.require('pushGeTui');
var param = {taskid:"SX_1111_ABCDEFG",extraData:"any_command"};
uzgetuisdk.sendMessage(param);
(暂无)
Android系统
可提供的1.0.0及更高版本
app 处于未启动状态时,点击通知打开程序获取透传消息。
payloadMessage(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及更高版本
在getui-apicloud-android工程中个推SDK插件配置完成后,在工程所在目录的终端命令行,运行./gradlew assembleRelease 指令,即可在build/outputs/aar目录下生成pushGeTui插件的产物。
APICloud的个推SDK接口文档,具体可见 https://docs.apicloud.com/Client-API/Open-SDK/pushGeTui 。