有推客户端中间件API使用说明书

《有推客户端中间件API使用说明书》由会员分享，可在线阅读，更多相关《有推客户端中间件API使用说明书（21页珍藏版）》请在装配图网上搜索。

1、有推客户端中间件（AOE_SDK） API使用说明书文档版本V1.2.2发布日期2016-07-18目录1、概述 31.1 有推系统介绍31.2 有推系统示意图31.3 术语解释42、接入说明42.1 导入工程或者引用开发包42.2 第一步继承 AoiCallback52.3 第二步声明 AoiSDK 对象62.4第三步配置AndroidMenifest.xml （以demo中配置文件为准）62.5 第四步实现需要的广播和 Service错误！未定义书签。2.6 调试113、常见问题列表FAQ124、升级集成说明165、编制历史181、概述1.1 有推系统介绍有推系统是中国移动定义的永远在线平

2、台，手机应用平台可以通过有推系统向终端发送 消息。有推系统由终端中间件（AOE）、AOI网关、服务端中间件（AOI_SDK）三部分组成。1. AOE集成在手机终端应用中，管理与AOI网关的长连接并处理下发和上行的消息，它可 以将收到的消息（下行）转发给终端应用，也可以将终端应用的消息转发给AOI网关（上 行） 。2. AOI 网关是有推系统的核心网元，它主要负责终端连接管理及处理消息上下行。3. 服务端中间件（AOI_SDK）集成在与手机终端应用对应的应用平台中，管理应用平台和 AOI 网关之间的连接及处理消息的上下行。对于无应用平台的终端应用无需集成 AOI_SDK，可通过有推网站进行推送（

3、htt p:/1.2 有推系统示意图下图为有推系统的示意图，图中的方框代表软件，AOE是由手机应用集成的，AOI-SDK 是由应用平台集成的。AOI网关是中间一个独立系统。终端应川T-仃服务器宜泪T台抉并AOI SDK1.3 术语解释术语解释下行消息流向为应用平台（或者有推网站）一 AOI网关手机终端 应用的消息上行消息流向为手机终端应用AOI网关应用平台的消息AOEAlways Online Engine,永远在线推送基础平台AOIAlways Online Infrastructure,永远在线推送基础平台2、接入说明2.1导入工程或者引用开发包将AOE DEMO源码导入IDE（此处使用E

4、clipse）, DEMO对应的工程名为AoeDemo,导入后如 下图所示：丿羽libs2? android-support-v4.jar丿羽res 凸 drawable-hdpi凸 drawable-ldpi 凸 drawable-mdpi （S? drawahle-xhdpi D drawable-xxhdpi丿 & layciut旦 activity_first.xml口 activity_init.xml 口 activity_main.xmlIjOjaleiessa&xmJ1、检查 libs 中是否成功引用了 jar 包（此处以 1.2.0 版本为例,最新版本请登录 进行下载）。2、

5、alert_message.xml是对下载框的样式定义，使用点击“下载功能”必须将该文件拷贝到 目标工程的layout目录下，可以根据自己需要更改下载框字体的大小。其它的xml文件 为 demo 自身为演示而使用的, APP 集成时可以不需要关注。2.2 第一步 继承 AoiCallback第1步，新建class继承AoiCallback (当然也可以根据自身业务需求，在既有类基础上继承AoiCallback 类)/*第一步：继承AoiCallback类，重写onInit和onNotifyData方法。其它方法可以根须需要 备选，参见ThreeCallback类。*第二步：配置AndroidM

6、enifes t.xml中相关权限、组件参数，可参考demo配置*第三步：启动BindAoeService,内部有对应初始化方法*当前为第一步。*/public class AoeCallback extends AoiCallback Override/用于获得注册成功后返回的t oken，应用可根据t oken是否改变自行增加业务public void onInit(int result, String token) / TODO Auto-generated method stubOverridepublic void onNotifyData(int result, byte data

7、) / TODO Auto-generated method stubOverridepublic void onUnregister(int error) / TODO Auto-generated method stubOverridepublic void setContext(Context context) / TODO Auto-generated method stubOverride/用于APP获取当前的推送服务运行状态，具体状态值参考附录列表public void onState(int state) / TODO Auto-generated method stub/重写o

8、nInit、onNoti fyDa ta和se tCo nt ex t方法，主要示例代码如下：private static final String TAG = AoeDemo;private Context mContext;Override/用于获得注册成功后返回的t oken,APP可保存t oken值，当t oken发生改变时，接收消息 或t oken发生变化后，进行对应业务调控public void onInit(int result, String token) if(mContext!=null) Toast.makeText(mContext, TAG + token:+ to

9、ken,Toas t. LENGMLONG).show();Override用于获得服务端推送给APP的消息，data指消息内容，为通过服务端下发透传消息的内容 public void onNotifyData(int result, byte data) String temp = new String(data);if (mContext != null) Toast.makeText(mContext, TAG + notify:+temp,Toas t. LENGTLONG).show();Override/用于APP获取当前的推送服务运行状态，具体状态值参考附录列表public vo

10、id onState(int state) / TODO Auto-generated method stubOverridepublic void setContext(Context context) mContext = context;2.3 第二步 配置 AndroidMenifest.xml (参考 demo 中配置)1）添加 SDK 运行所需要的系统权限 android:name=android.permission.RECEZVE_SMS / android:name=android.permission.READ_PHONE_STATE / android:name=andr

11、oid.permission.ZNTERNET / android:name=android.permission.ACCESS_NETWORK_STATE / android:name=android.permission.CHANGE_NETWORK_STATE / android:name= android.permission.ACCES WIFI_STATE / android:name= android.permission.CHANG WIFI_STATE /uses-permissionuses-permission uses-permission uses-permissio

12、n uses-permissionuses-permission uses-permission uses-permission uses-permissionandroid:name= android.permission.DEVICE_POWERuses-permission uses-permission uses-permission uses-permission uses-permission uses-permission uses-permission uses-permission uses-permission android:name=android.permission

13、.WAKE_LOCK /android:name=android.permission.WRITE_SETTINGS / android:name=android.permission.READ_SYNC_ SETTINGS/ android:name=android.permission.KILL_BACKGROUND_PROCESSES / android:name=android.permission.RECEIVE_BO0T_COMPLETED / android:name=android.permission.VIBRATE / android:name=android.permis

14、sion.WRITE_EXTERNAL_STORAGE / android:name=android.permission.MOUNT_UNMOUNT_FILESYSTEMS / android:name=android.permission.RECEIVE_USER_PRESENT / android:name=android.permission.BROADCAST_STICKY /2）添加 AOE 用到的 BroadcastReceiver和 Service/activity/receiver/receiver/receiver/service!-注册AOE 中间件service -se

15、rviceandroid:name=com.cmcc.aoe.AoeServiceandroid:exported=trueandroid:persistent=trueandroid:process=com.cmcc.aoe.AOEService艮据SDK的版本，正确填写版本号- !-分配给应用Id号，必须填写真实有效的id -!-是否在开机和网络变化时主动建立链接n否 y是 -receiver android:name=com.cmcc.aoe.receiver.NotifyCationReceiver 注：1、aoicallback:回调方法路径，必须进行配置，否则会接收不到消息，根据应

16、用继承AoiCallback的具体实现类进行配置；1、service_version: aoe版本号，该示例中为1.2.0，必须根据使用的AOE版本号进行相应调整2、appid_wi th_aoe的value在实际集成中必须更换成申请有推能力时获得的APPID, NotifyCationReceiver中的配置也要做相应的修改。示例中的APPID为 1081000000042.4第三步 启动AOEService，运行推送功能启动AoeService，通过启动BlndAoeService，在对应里面包含对应的初始化方法/*第一步：继承AoiCallback类，重写onInit和onNotifyD

17、ata方法。其它方法可以根须需要备选，参见ThreeCallback类。*第二步：将Demo中AndroidMenifest.xml中配置拷贝到目标工程中*第三步：启动BindAoeService,内部有对应初始化方法*/public void onCreate(Bundle bundle) super.onCreate(bundle);set Con tentV iew(R.layou tmain);Intent intent = new Intent(this, com.cmcc.aoe.BindAoeService.class);startService(intent);注：init方法

18、中的第二个参数，在实际集成时需要修改为应用申请有推时分配的APPID,并与AndroidMenifest.xml中的配置保持一致。2.5 调试1）安装demo的APK后，启动应用，出现如下界面，各按钮的说明见右侧说明。1、p3？ pA)：Ptd：1UiLun6Abb4钊盹洒卸.歳去匸忸理悴g 捋:BiJml iS乖;却站忆点討普氓遍H aiQktnd30df)fil.n?tJRLaifllBft.jS f j ft tBtjFinlAc(!vit52、3、4、5、点击测试onlnit按钮可以查看已经获得的TOKEN， 如果尚未获得TOKEN，待获得后方能查看； 点击打开客户端按钮，会在手机的通

19、知栏中展示 一个通知，点击该通知可打开该demo点击打开URL按钮，会在手机的通知栏中展示一 个通知，点击打开百度首页点击下载文件按钮，会在手机的通知栏中展示一 个通知，点击打开下载页面点击打开 Acitivity, 会在手机的通知栏中展示一个 通知，点击打开对应的Activity界面2）直接使用demo进行真正推送调试，保持APPID为不变访问 http:/dev.10086.en/aoi/introduce/todemo.d，使用系统自测功能体验有推。1、 点击“自定义消息推送”在客户端可以看到“AOE DEMO CONTENT”字样，通过toast 展示；2、点击“通知打开网页”，在客户

20、端通知栏中会出现一条通知，点击将打开一个网页。3、点击“通知启动应用”，在客户端通知栏中会出现一条通知，点击将打开客户端的主界 面。3）使用自有APP、APPID集成AOE后调试访问http:/dev.10086.en/aoi/app/tolist.d，登录系统后可以自行编辑透传（自定义）和 通知消息。3、API 接口说明类 AoiSDKAoiSDK对外接口类java.lang.Object_xOOOD_ 匚 com.cmcc.aoe.sdk. AoiSDK3.1 方法摘要返回类型方法名voidsetDebug(boolean isDebug) 设置后台日志是否打印，默认值打印日志voidst

21、art(Context context) 尝试启动服务，多次调用不影响服务运行voidQueryState(Context context) 查询AOE运行状态，结果通过AOICallback的onstate反馈应用voidsyncMessage(Context context) 尝试去获取AOI的离线消息3.2 接口说明3.2.1 设置调试模式接口名称 public static void setDebug(Context context,booleanisDebug)参数名称作用isDebugFalse:非调试模式，true:调试模式(打印日志)context返回结果：无 示例：AoiSD

22、K.setDebug(true);/打开调试模式AoiSDK.setDebug(false);/ 关闭调试模式3.3.2 启动 AOEService接口名称 public static void start(Context context)参数名称作用context尝试启动服务，多次调用不影响服务运行返回结果：无示例：AoiSDK.start(context)3.3.3 查询状态接口名称 public static void QueryState(Context context)参数名称作用context查询AOE运行状态，结果通过AOICallback的onstate反馈应用返回结果：无 示

23、例：AoiSDK.QueryState (context)3.3.4 获取离线消息接口名称 public static void syncMessage(Context context)参数名称作用context尝试去获取AOI的离线消息返回结果：无 示例：AoiSDK.syncMessage(context)4、常见问题列表 FAQ1. 如果推送与服务器断开了，客户端要做处理么？A:有推推送的逻辑是：让开发者尽可能的无需关注和维护推送，而是让开发者更专注于 推送的功能来搭建自己的业务，无需开发者去处理的2. 有推推送需要付费么？A:有推推送是免费的，开发者可以免费使用而没有限制3. 推送可以

24、进行群发么？A:有推推送可以进行群发的，需要注册开发者账号并登陆。4. 推送的 APPID 与 APPKEY 值怎么得到？A:请登录中国移动能力池( 成功提交审核，就可自动生成APPID与APPKEY。5. APP 关闭后，还能进行推送么？A:默认情况是程序正常退出，推送服务继续在后台运行并能够接收到消息。6. 什么是有卡终端？什么是无卡终端A: 手机或其它终端内 SIM 卡属于中国移动，则认为是有卡终端。除此之外的皆认为是 无卡终端。7. 什么是长连接？A:手机或是其它终端为了保持与服务器端持续高效通讯，需要连上服务器，当有上下行 数据时，可以用这条已建立的通讯链路来传输数据。8. 长连接保

25、持的时间是多长？A:一直保持连接9. 为什么要区分有卡与无卡终端？A:便于对有卡提供更个性化的服务10. 当网络不稳定时（但有网络），长连接建立不成功怎么办？A:系统具备机制保证连接建立成功11. 无网络怎么办？A:无网络时连接可能会断掉，网络服务时系统会根据需要确定是否重新建立连接。12. 终端注册是否要发短信？A: 有卡会，无卡不会。13. 终端注册时发的短信是否要扣费？A:免费14. 终端注册成功后，是否还会发短信？A: 不会15. 软件缷后，重新安装，是否还会发短信注册？A：不会16. 如果多个应用集成了 AOE，是否每个应用都会走注册流程导致发送注册短信？A：不会17. 多个应用集成

26、AOE，会建立多条长连接？多个服务吗？A：只有一个服务，只有一条长连接18. 多个应用集成AOE，哪个应用来建立长连接A： 内嵌 AOE 版本最高的那个应用负责建立长连接。19. 收到唤醒短要付费吗？A:不要20. 集成AOE是否费电？A:AOE 只消费很少的电量21. AOE 是否有日志，存在哪儿？A:/SDCARD/.AOE/AOELOG.TXT22. 通知与自定义（透传）消息有什么区别？A:/产品角度的区别：通知：终端中间件将会将消息直接展示在通知栏中，发通知提醒、激活用户自定义消息：用于APP内部业务，APP可以根据需要自定义消息的组成。/开发者使用角度的区别：通知：终端中间件处理并展

27、示，无需 APP 处理；自定义消息：终端中间件将消息投递给APP，完全由APP进行处理。23. 基本架构A:有推包括 AOI 平台、AOI SDK、AOE（Always Online Engine）三部分。24. 能力调用A: 开发者在能力集市中创建应用，申请使用”有推“能力，能力池分配给开发者APP ID和APP KEY，在该界面中的能力配置，是必选配置，必须进行。在该页面中，会生成SPID （目前SPID值等同于APP ID）。开发者后续需持APPID、APP KEY、SPID进行应用的开发和能力的使用。25. 如何接入有推？26. 短信权限使用“短消息”能力时必须在 menifest 中

28、配置对 16861 端口的监听和 SMSNotifyReceiver 若不使用“短消息”能力时不要求以上权限。5、升级集成说明1) AOE1.0.6与1.0.5版本相比a) 增加了短消息能力，终端用户无数据网络时也能将消息送达。如果使用该功能需在Menifest.xml中增加如下配置。具体可参见demo源码或者本文档2.4节。receiverandroid:name=com.cmcc.aoe.receiver.SMSDataReceiver /receiver /receiverb) 可自定义下载框的样式，参见 demo 中的 layout 配置文件 alert_message.xml， 可根

29、据需要自行修改字体大小、颜色、按钮名称，请勿修改控件id。c) 增加对“b”中下载按钮点击事件的统计，该功能由AOE自行完成，开发者不 需要额外开发。d) 取消配置文件Menifest.xml中读取短信权限的声明，不再需要声 明。2) AOE1.0.9与1.0.6版本相比a) 在配置文件和使用方式上没有变化；b) 直接替换之前的 AOE jar 包即可。3) AOE1.1.6 与 1.0.9 版本相比a) 在配置文件和使用方式上没有变化；b) 直接替换之前的 AOE jar 包即可。4) AOE1.1.9 与 1.1.6 相比a) 修改配置文件1) 增加权限uses-permission an

30、droid:name=android.permission.RECEIVE_USER_PRESENT / uses-permission android:name=android.permission.BROADCAST_STICKY /2) receiver android:name=com.cmcc.aoe.receiver.BootReceiver intent-filterintent-filter intent-filter/receiver3) service android:name=com.cmcc.aoe.BindAoeServiceandroid:exported=true

31、 android:persistent=true 4) intent-filter 5)value 值修改为自己 app 实现 AoeCallback 的路径，比如 com.iss.sric.aoe.ThreeCallbackb) 直接替换之前的 AOE jar 包即可。6、编制历史版本号更新时间主要内容或重大修改1.0.02012-8-21创建1.0.12013-9-12增加通知功能1.0.22014-1-16解决升级覆盖的问题，较少开发包大小1.0.32014-3-26增加配置参数aoe_ne twork_s tate，控制中间件是否自动联网1.0.42014-04-14增加对开锁及安装a

32、pp的监听1.0.52014-5-13新增对点击通知下载和点击通知打开指定界面功能的支持1.0.62014-6-5增加对短消息的支持，修改下载框默认字 体，增加对“下载”按钮点击的流水上报1.0.72014-6-26内部版本1.0.82014-7-10内部版本1.0.92014-7-30优化终端注册机制、解决终端重复收消息 的问题、解决部分终端重复提示上行短信 的问题1.1.62014-11-121.1.0至1.1.5均为内部版本，与1.0.9 相比优化了 A0E服务的健壮性、解决了一些 bug、适配了 2.3以下的操作系统等1.1.92015-2-121.1.7至1.1.8均为内部版本，1.

33、1.9版本 与之前版本相比修改了一些bug，提咼AOE 服务的健壮性1.2.02016-1-291、优化连接机制，提升弱网环境下的稳定 性2、优化保活策略，提升达到率。1.2.12016-5-311.添加AoiCallback的状态查询进行2新增接口说明，用于应用获取推送运行 情况7、附录7.1 状态码说明编码段详细编码返回信息说明1000AOE SERVICE RUNNEDAOE服务运行中1001AOE SERVICE NOT RUNNEDAOE服务未运行2010AOI_DNS_REG_SUCCDNS注册成功2011AOI DNS REGINGDNS注册中2012AOI DNS REG FA

34、ILEDDNS注册失败2013AOI DNS REG TIMEOUTDNS注册超时2020AOI PASSKEY GET SUCC网关密钥获取成功2021AOI PASSKEY GETTING网关密钥获取中2022AOI pASSKEY GET FAILED网关密钥获取失败2023AOI PASSKEY GET TIMEOUT:网关密钥获取超时2030AOI GW DATA CONNECTION OPEN推送通道认证成功2031AOI GW REGING推送通道认证2033aoi gw Reg timeout推送通道认证失败3000NETWORK AVAILABLE网络状态正常3001NETWORK NOT AVAILABLE网络状态不可用