MQTT消息推送SDK说明书
- MQTT消息推送SDK说明书
- 1、 概述
- 2、 SDK集成
- 3、API说明
- 3.1 主要类
- 3.2 接口方法
- 3.2.1 Push服务初始化
- 3.2.2 获取设备唯一识别号
- 3.2.3 Push服务启动-startPush
- 3.2.4 停止Push服务-stopPush
- 3.2.5 查询Push服务是否停止- isPushEnabled
- 3.2.6 开启打印日志-enableDebug
- 3.2.7 设置免打扰时段- setNoDisturbMode
- 3.2.8 添加Tag-addTag
- 3.2.9 删除Tag-deleteTag
- 3.2.10 查询Tag-listTags
- 3.2.11 设置默认的Notification样式-setDefaultNotificationBuilder
- 3.2.12 获取绑定的结果-onBind
- 3.2.13 获取解绑的结果-onUnbind
- 3.2.14 接收推送消息-onMessage
- 3.2.15 接收推送消息-onNotificationArrived
- 3.2.16 接收用户点击消息-onNotificationClicked
- 3.2.17 接收添加Tag结果-onAddTag
- 3.2.18 接收删除Tag结果-onDeleteTag
- 3.2.19 接收查询Tag列表-onListTags
1、 概述
本SDK实现Android平台上的Push服务。利用推送云端与客户端建立的MQTT连接实现向客户端推送实时消息的服务，提供给Android开发者简单接口以开启、停止Push服务及接收实时消息。
1.1 主要功能
1.1.1 推送通知
向Android端推送并展现系统通知，支持APP设置通知展现类型。
1.1.2 推送透传消息
向Android端推送自定义的透传消息。
1.1.3 基于地理位置推送
基于APP的LBS信息进行推送。
1.1.4 基于标签推送
基于用户自定义的标签进行推送。
1.2 主要特点
1.2.1 稳定安全推送
基于MQTT实现的推送，具有轻量、稳定、安全、流量消耗低的特点。
2、 SDK集成
注意：本SDK具有单例服务，杀死后无法重启，目前仅可用于车机端Android系统，且要求车机端系统将PushService添加为系统服务，服务名称中包含ni_pushservice。所以，可以将进程名称中包含“ni_pushservice”的进程添加为白名单。
2.1 申请appKey
每一个将要继承此SDK的app都需要申请apiKey。
2.2 导入推送jar包
将解压后的libs文件夹中所有文件拷贝到您的工程的libs文件夹中。 org.eclipse.paho.client.mqttv3-1.1.0.jar：这是此SDK的支持库，SDK使用者无需关心，导入工程即可。 com.mapbar.android.guid.jar：这是此SDK的支持库，SDK使用者无需关心，导入工程即可。 com.mapbar.android.location.jar：这是此SDK的支持库，SDK使用者无需关心，导入工程即可。 pushservice-{$version}.jar：实现启动、关闭推送，基于位置或标签推送通知及透传消息。
2.3 配置AndroidManifest文件
在您的工程的AndroidManifest.xml文件中，添加权限和声明信息（请勿修改）：
*注意：相关权限在Android 6.0及其以上需要用户进行授权。
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<uses-permission android:name="android.permission.READ_PHONE_STATE" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.VIBRATE" />
<uses-permission android:name="android.permission.DISABLE_KEYGUARD" />
<uses-permission android:name="android.permission.WRITE_SETTINGS" />
配置Push service
<service
android:name="com.navinfo.android.push.service.PushService"
android:enabled="true"
android:exported="true"
android:process=":ni_pushservice"></service>
自定义BroadcastReceiver并继承PushMessageReceiver
<receiver android:name=".MyPushMessageReceiver">
<intent-filter>
<action android:name="com.navinfo.android.pushservice.action.RECEIVE"></action>
<action android:name="com.navinfo.android.pushservice.action.MESSAGE"></action>
<action android:name="com.navinfo.android.pushservice.action.notification.ARRIVED"></action>
<action android:name="com.navinfo.android.pushservice.action.notification.CLICK"></action>
<category android:name="${your apiKey}"></category>
</intent-filter>
</receiver>
权限说明
INTERNET 允许访问网络 ACCESS_WIFI_STATE 允许访问WI-FI网络状态信息 READ_PHONE_STATE 允许访问设备状态信息（必须） WRITE_EXTERNAL_STORAGE 允许写入设备外部存储（必须） ACCESS_NETWORK_STATE 允许访问设备网络状态 ACCESS_COARSE_LOCATION 允许访问设备大致位置（必须） ACCESS_FINE_LOCATION 允许访问设备精确位置（必须） VIBRATE 允许使用振动器 DISABLE_KEYGUARD 允许在不安全情况下禁用键盘锁 WRITE_SETTINGS 允许读写系统设置（必须）
2.4 初始化、启动云推送
自定义Application类，在其onCreate中，添加以下代码： PushApis.init(this, "apiKey");
另外，还可以设置通知样式相关属性：
DefaultPushNotificationBuilder builder = new DefaultPushNotificationBuilder();
//设置通知声音
builder.setNotificationSound(RingtoneManager.getDefaultUri(RingtoneManager.TYPE_NOTIFICATION).toString());
//设置通知震动参数
builder.setNotificationVibrate(new long[]{1000, 1000, 1000, 1000});
PushApis.setDefaultNotificationBuilder(builder);
最后，可以启动推送服务：
PushApis.startPush();
2.5 混淆说明
-libraryjars libs/com.mapbar.android.guid.jar
-dontwarn com.mapbar.android.guid.**
-keep class com.mapbar.android.guid.**{*; }
-libraryjars libs/com.mapbar.android.location.jar
-dontwarn com.mapbar.android.location.**
-keep class com.mapbar.android.location.**{*; }
-libraryjars libs/org.eclipse.paho.client.mqttv3-1.1.0.jar
-dontwarn org.eclipse.paho.client.mqttv3.**
-keep class org.eclipse.paho.client.mqttv3.**{*; }
-libraryjars libs/pushservice-1.0.0-alpha.jar
-dontwarn com.navinfo.android.pushservice.**
-keep class com.navinfo.android.pushservice.**{*; }
2.6 错误码
error_code 描述 - 200 成功 - 500 服务内部错误 - 1001 apiKey无效 - 2001 参数为空 - 2002 参数无效 - 3000 数据不存在 - 3001 数据已存在 - 3002 数据保存失败 - 9000 无权限 - 9001 网络不可用 - 9002 操作超时 - 9003 位置错误
3、API说明
3.1 主要类
类 描述 PushApis 所有Push服务的静态方法 PushMessageReceiver 自定义接收消息、通知、操作结果的父类 PushNotificationBuilder 自定义系统通知的样式父类 DefaultPushNotificationBuilder 默认的通知样式，支持基本的样式属性 PushConstants 所有Push服务涉及的常量
3.2 接口方法
SDK目前支持以下API： 类别 功能 API Push服务控制接口 控制Push服务 init,enableDebug,startPush,stopPush,isPushEnabled ,setNoDisturbMode,getDeviceGUID 通知管理接口 自定义通知样式 setDefaultNotificationBuilder, PushNotificationBuilder Tag管理接口 Tag创建、删除、查询 addTag, deleteTag, listTags 异步消息接收接口 自定义消息处理Receiver onBind,onUnbind,onMessage,onNotificationShowed ,onNotificationClicked,onNotificationDeleted ,onAddTag,onDeleteTag,onListTags
3.2.1 Push服务初始化
函数原型 public static void init (Context appContext, String appKey)
参数
1) appContext：应用的Context
2) appKey：应用的appKey
返回 通过自定义的Receiver里的onBind返回
3.2.2 获取设备唯一识别号
函数原型 public static String getDeviceGUID (Context context)
参数
1) context：应用的Context
返回 该设备的唯一识别号。
3.2.3 Push服务启动-startPush
函数原型 public static void startPush ()
参数
1) appContext：应用的Context
2) appKey：应用的appKey
返回 通过自定义的Receiver里的onBind返回
3.2.4 停止Push服务-stopPush
函数原型 public static void stopPush ()
返回 通过自定义的Receiver里的onUnbind返回
3.2.5 查询Push服务是否停止- isPushEnabled
函数原型 public static boolean isPushEnabled ()
返回
1) true：服务已启动
2) false：服务已停止
3.2.6 开启打印日志-enableDebug
函数原型 public static void enableDebug (boolean debug)
参数
1) debug：是否开启打印日志
3.2.7 设置免打扰时段- setNoDisturbMode
函数原型 public static void setNoDisturbMode(int startHour, int startMinute, int endHour, int endMinute)
如果开始时间小于结束时间，免打扰时段为当天的起始时间到结束时间；如果开始时间大于结束时间，免打扰时段为第一天起始时间到第二天结束时间；如果开始时间和结束时间的设置均为00:00时,取消免打扰时段功能。
参数
1) startHour，startMinute：起始时间，24小时制，取值范围0~23，0-59
2) endHour，endMinute：结束时间，24小时制，取值范围0~23，0-59
返回 空
3.2.8 添加Tag-addTag
函数原型 public static void addTag (String tag)
参数
1) tag：添加的tag
返回 通过自定义的Receiver里的onAddTag返回
3.2.9 删除Tag-deleteTag
函数原型 public static void deleteTag (String tag)
参数
1) tag：删除的Tag
返回 通过自定义的Receiver里的onDeleteTag返回
3.2.10 查询Tag-listTags
函数原型 public static void listTags ()
参数
1) appContext：应用的Context
返回 通过自定义的Receiver里的onListTags返回
3.2.11 设置默认的Notification样式-setDefaultNotificationBuilder
函数原型
public static void setDefaultNotificationBuilder ( PushNotificationBuilder pushNotificationBuilder)
参数
1) appContext：应用的Context
2) pushNotificationBuilder：自定义的通知样式
返回 空
自定义通知PushNotificationBuilder
setStatusbarIcon(icon) 设置通知栏icon的资源id。
setNotificationFlags(flags) 设置Anroid Notification里的flags。
setNotificationDefaults(defaults) 设置Anroid Notification里的defaults。
setNotificationSound(sound) 设置通知自定义的声音的资源路径
setNotificationVibrate(long[] vibratePattern) 设置自定义通知里的震动模式。
3.2.12 获取绑定的结果-onBind
函数原型 public void onBind (Context appContext, String errorCode)
参数
1) appContext：应用的Context
2) errorCode：返回结果值
3.2.13 获取解绑的结果-onUnbind
函数原型 public void onUnbind (Context appContext, String errorCode)
参数
1) appContext：应用的Context
2) errorCode：返回结果值
3.2.14 接收推送消息-onMessage
函数原型 public void onMessage (Context appContext, String id, String title, String content, String params)
参数
1) appContext：应用的Context
2) id：消息id
3) title：消息title
4) content：消息内容
5) params：消息附加
3.2.15 接收推送消息-onNotificationArrived
函数原型 public void onNotificationArrived (Context appContext, String id, String title, String content, String params)
参数
1) appContext：应用的Context
2) id：通知id
3) title：通知title
4) content：通知内容
5) params：通知附加
3.2.16 接收用户点击消息-onNotificationClicked
函数原型 public void onNotificationClicked (Context appContext, String id, String title, String content, String params)
参数
1) appContext：应用的Context
2) id：通知id
3) title：通知title
4) content：通知内容
5) params：通知附加
3.2.17 接收添加Tag结果-onAddTag
函数原型 public void onAddTag (Context appContext, String tag, String errorCode)
参数
1) appContext：应用的Context
2) tag：添加的Tag
3) errorCode：返回结果值
3.2.18 接收删除Tag结果-onDeleteTag
函数原型 public void onDeleteTag (Context appContext, String tag, String errorCode)
参数
1) appContext：应用的Context
2) tag：删除的Tag
3) errorCode：返回结果值
3.2.19 接收查询Tag列表-onListTags
函数原型
public void onListTags (Context appContext, String errorCode, List
参数