史上最好用的 Android 全量版本更新库 XUpdate 使用指南
项目简介
XUpdate是一个轻量级、高可用性的Android全量版本更新框架。
XUpdate是为了解决在不同项目组、不同平台之间进行统一的Android全量版本更新的库。它具有轻量、灵活、低耦合、高可用等特点,可以很方便地定制属于自己的版本更新。
设计原由
在没有XUpdate之前的版本更新,Android版本更新基本都是靠写各种版本更新工具类来实现版本更新,更可怕的是有时在不同项目组或者平台之间,它们的版本更新完全是不一样的,这样的结果就是会写无数的版本更新工具类,并且每次更换一个项目组或者平台就需要从头重写再写一遍,非常得麻烦。当时我就在想,版本更新作为一个Android应用基本都有,且内容相对稳定的功能,有没有可能设计出一个通用的、不为业务或者平台所影响的基础库呢?
设计思路
在着手写XUpdate之前,我特地去Github上搜了一圈有关Android版本更新的内容,发现AppUpdate这个项目star数量最多。但是当我翻阅它的源码之后发现,它设计得并不优美,内部耦合非常严重,不过优点就是Android版本更新的功能基本都涵盖了。于是我就照着它所拥有的功能,结合了我对版本更新的理解进行了重新设计,感兴趣的可[点击查看框架UML设计图](https://github.com/xuexiangjys/XUpdate/blob/master/img/xupdate_uml.png)。
解决痛点
使用简单,只需一行代码即可完成版本更新功能。
功能强大,兼容Android6.0、7.0、8.0、9.0和10.0,支持静默更新和自动更新,支持国际化。
扩展性强,可自定义请求API接口、提示弹窗、下载服务、文件加密器等。
搭建简单,只需提供json内容即可支持版本更新。
配套齐全,默认提供了后台服务、管理界面以及各类插件。
项目地址
为了方便大家使用, XUpdate提供了一整套的全量版本更新解决方案.
Android基础库: https://github.com/xuexiangjys/XUpdate
React-Native插件: https://github.com/xuexiangjys/react-native-xupdate
项目演示
客户端效果
默认版本更新
后台更新
强制版本更新
可忽略版本更新
自定义提示弹窗主题
使用系统弹窗提示
后台管理界面
登录页面
后台管理主页
应用版本添加
应用版本修改
集成指南
添加Gradle依赖
1.先在项目根目录的 build.gradle 的 repositories 添加:
2.然后在dependencies添加:
以下是版本说明,选择一个即可。
androidx版本:2.0.0及以上
support版本:1.1.6及以下
初始化SDK
在Application进行初始化配置:
【注意】这里需要注意的是,IUpdateHttpService
必须设置,否则框架将无法正常使用!IUpdateHttpService
的实现可参照Demo中的实现
【注意】:如果出现任何问题,可开启debug模式来追踪问题。如果你还需要将日志记录在磁盘上,可实现以下接口
混淆配置
基础使用
默认版本更新
直接调用如下代码即可完成版本更新操作:
需要注意的是,使用默认版本更新,请求服务器返回的json格式应包括如下内容:
自动版本更新
自动版本更新:自动检查版本 + 自动下载apk + 自动安装apk(静默安装)。
只需要设置isAutoMode(true)
,不过如果设备没有root权限的话,是无法做到完全的自动更新(因为静默安装需要root权限)。除此之外,对于某些特殊设备可能需要自定义安装监听才能实现静默安装。
支持后台更新
开启支持后台更新后, 用户点击“后台更新”按钮后,就可以进入到后台更新,不用一直在更新界面等待.
自定义版本更新主题样式
通过设置更新顶部图片、主题色、按钮文字颜色、宽高比率等来实现自定义主题样式.
promptThemeColor: 设置主题颜色
promptButtonTextColor: 设置按钮的文字颜色
promptTopResId: 设置顶部背景图片
promptWidthRatio: 设置版本更新提示器宽度占屏幕的比例,默认是-1,不做约束
promptHeightRatio: 设置版本更新提示器高度占屏幕的比例,默认是-1,不做约束
强制版本更新
就是用户不更新的话,程序将无法正常使用。
如果你使用的是默认版本更新返回api的话, 只需要服务端返回
UpdateStatus
字段为2即可。
如果你自定义请求返回api的话,只需要设置
UpdateEntity
的mIsForce
字段为true即可。
进阶使用
版本更新信息实体
UpdateEntity作为框架各个环节接口的通信媒介,了解它们的作用对后面接口的自定义非常关键。
UpdateEntity字段属性
字段名 | 类型 | 默认值 | 备注
:-|:-:|:-:|:-
mHasUpdate | boolean | false | 是否有新版本
mIsForce | boolean | false | 是否强制安装:不安装无法使用app
mIsIgnorable | boolean | false | 是否可忽略该版本
mVersionCode | int | 0 | 最新版本code
mVersionName | String | unknown_version | 最新版本名称
mUpdateContent | String | "" | 更新内容
mDownloadEntity | DownloadEntity | / | 下载信息实体
mIsSilent | boolean | false | 是否静默下载:有新版本时不提示直接下载
mIsAutoInstall | boolean | true | 是否下载完成后自动安装
DownloadEntity字段属性
字段名 | 类型 | 默认值 | 备注
:-|:-:|:-:|:-
mDownloadUrl | String | "" | 下载地址
mCacheDir | String | "" | 文件下载的目录
mMd5 | String | "" | 下载文件的md5值,用于校验,防止下载的apk文件被替换(最新演示demo中有计算md5值的工具)
mSize | long | 0 | 下载文件的大小【单位:KB】
mIsShowNotification | boolean | false | 是否在通知栏上显示下载进度
PromptEntity字段属性
字段名 | 类型 | 默认值 | 备注
:-|:-:|:-:|:-
mThemeColor | int | R.color.xupdatedefaulttheme_color | 主题色(进度条和按钮的背景色)
mTopResId | int | R.drawable.xupdatebgapp_top | 顶部背景图片资源id
mButtonTextColor | int | 0 | 按钮文字颜色
mSupportBackgroundUpdate | boolean | false | 是否支持后台更新
mWidthRatio | float | -1(无约束) | 版本更新提示器宽度占屏幕的比例
mHeightRatio | float | -1(无约束) | 版本更新提示器高度占屏幕的比例
组成结构
在了解了版本更新的结构和各部分的功能后,我们就可以根据我们实际的需求进行自定义了.以下是版本更新的组成结构:
版本更新检查器
IUpdateChecker
:检查是否有最新版本。
版本更新解析器
IUpdateParser
:解析服务端返回的数据结果。
版本更新提示器
IUpdatePrompter
:展示最新的版本信息。
版本更新下载器
IUpdateDownloader
:下载最新的版本APK安装包。
网络请求服务接口
IUpdateHttpService
:定义了进行网络请求的相关接口。
除此之外,还有两个监听器:
版本更新失败的监听器
OnUpdateFailureListener
。
版本更新apk安装的监听器
OnInstallListener
。
更新调度核心:
版本更新业务代理
IUpdateProxy
:负责版本更新的流程控制,调用update开始进行版本更新流程。
理论上,以上所有组成部分都开放了自定义的api,我们只需要根据我们的需求实现对应的接口即可完成自定义.
自定义版本更新解析器
如果你不想使用默认版本更新返回的接口数据, 那么你可以实现IUpdateParser
接口即可实现解析器的自定义, 示例如下:
自定义版本更新检查器+版本更新解析器+版本更新提示器
实现
IUpdateChecker
接口即可实现检查器的自定义。
实现
IUpdateParser
接口即可实现解析器的自定义。
实现
IUpdatePrompter
接口即可实现提示器的自定义。
自定义文件加密校验器
本框架默认使用的文件加密校验方法是MD5加密方式,当然如果你不想使用MD5加密,你也可以自定义文件加密器IFileEncryptor
,以下是MD5文件加密器的实现供参考:
最后再调用XUpdate.get().setIFileEncryptor
方法设置即可生效。
只使用XUpdate的下载器功能进行apk的下载
只使用XUpdate的APK安装的功能
如果你的apk安装与众不同,你可以实现自己的apk安装器。你只需要实现OnInstallListener接口,并通过XUpdate.setOnInstallListener
进行设置即可生效。
常见问题
接入的问题
1.问:为什么我刚接入的时候,一直报错`updateHttpService == null`?
答:你需要仔细阅读接入文档,必须在Application中按要求初始化XUpdate
,而其中IUpdateHttpService
必须设置,除非你自定义版本检查器和版本更新下载器,否则框架将无法正常使用!
2.问:为什么我在开发调试的时候,能够出现最新版本的提示,但是打出来的包却什么反应也没有?
答:出现这个问题,一般是少了混淆配置。如果你使用了自定义的版本更新解析器,请对你的接口实体进行混淆配置。
3.问:为什么我点击下载后文件是能下载下来的,但是进度条不更新,或者打印出进度条的值是-1?
答:出现这种情况可以从两个方面来排查。
如果你打印出进度条的值是-1,那很有可能是服务端提供的下载服务本身就不支持进度。因为如果你在请求服务端下载文件的时候,服务端在请求头中没有返回数据长度,即
contentLength
(Content-Length)没有设置,是未知的,那么是不可能有进度的。这个你可以通过抓包来查看响应头中是否设置了“Content-Length”。
如果你使用的服务端本身已经确认是支持进度的。那么就可能需要考虑是不是你的
IUpdateHttpService
的download
接口实现有问题,你务必要保证接口DownloadCallback
的onProgress
方法能被正常执行。
4.问:为什么我执行了版本更新的方法,它却一直提示无最新版本或者是一直在进行版本更新?
答:出现这个问题,你首先得明确一点的是,你判断是否有最新版本的依据是什么。到底是依据VersionCode
还是VersionName
,这个取决于你实际使用的场景。明确完这一点,你才可以根据日志去判断到底是前端出了问题还是后端出了问题。
5.问:这个最新版本我已经下载过了,只不过没安装,在下一次进行版本更新的检查时,为什么我还要重新下载一次?
答:出现这个问题,只能证明你的后端在返回版本信息的时候并没有返回最新版本文件的MD5值,或者返回了你没有设置。如果你设置了MD5值,那么就是你设置的MD5值和文件计算出来的MD5值不匹配,这种情况下,你的APK文件极有可能被篡改了(当然在这种情况下,你也不能正常安装),或者是你们前后端的MD5值计算算法不一致(一般不存在这种情况)。
6.问:为什么我最新的应用下载了,但是点击`安装`按钮后一直提示更新失败呢?
答:出现这种问题的情况有很多种。
首先你需要确保能否找到下载下来的最新APK,如果你设置了MD5值的话,还需要判断下载下来的最新APK计算出来的MD5值和后台接口返回的MD5值是否一致(计算文件的MD5值Demo中有对应的方法);
其次你需要手动安装一下APK,确保APK文件没问题(签名一致、文件完整),能正常安装;
最后你可以在多台设备上尝试一下,确保不是设备自身的问题。
如果以上方法都不能解决问题,很遗憾,那么你只能自定义安装监听器
OnInstallListener
接口,实现能够正确安装APK的方法了。
7.问:在版本更新的过程中出现了错误,我该如何进行排查?
答:最好的解决方法当然是打断点逐个进行排查啦!当然在打断点前,我们需要调用XUpdate.get().debug(true)
开启debug模式,打印相关日志,明确出错的位置,这样才能更快地解决问题啦!
8.问:为什么版本更新弹窗弹不出来,报`System.err: at com.xuexiang.xupdate.widget.BaseDialog.init(BaseDialog.java:72) `错误?
答:最好的解决方法就是传入的context使用的是AppCompatActivity
, 而不是Activity
或者FragmentActivity
!如果你一定要使用Activity
或者FragmentActivity
,那么请设置其主题为Theme.AppCompat
类型的主题。
自定义的问题
经常有使用者反馈不知道该如何自定义接口(面对一堆接口,不知道该如何下手),进行个性化的定制,以满足版本更新实现的需求,下面我将一一列举问题和解决的方法。
1.问:我使用的是retrofit自定义的接口,不想使用`IUpdateHttpService`那套通用请求方式来查询最新版本,我该怎么办?
答:可以自定义版本更新检查器IUpdateChecker
,它主要负责的是查询是否存在最新版本。可参考框架默认提供的版本更新检查器来自定义。
2.问:我不想使用框架默认的请求服务器返回的json格式,因为公司的后端有自己的一套数据返回格式,我该怎么办?
答:可以自定义版本更新解析器IUpdateParser
,它主要负责的是解析服务端返回的数据结果,并构建更新信息实体UpdateEntity
。具体可参考自定义版本更新解析器, 也可参考[框架默认提供的版本更新解析器](https://github.com/xuexiangjys/XUpdate/blob/master/xupdate-lib/src/main/java/com/xuexiang/xupdate/proxy/impl/DefaultUpdateParser.java)来自定义。
3.问:我觉得框架提供的一套默认的版本更新提示界面不符合我们公司的UI风格,我能自定义一套自己的版本更新提示界面吗?
答:可以自定义版本更新提示器IUpdatePrompter
,它主要负责的是展示最新的版本信息。具体可参考自定义版本更新提示器, 也可参考[框架默认提供的版本更新提示器](https://github.com/xuexiangjys/XUpdate/blob/master/xupdate-lib/src/main/java/com/xuexiang/xupdate/proxy/impl/DefaultUpdatePrompter.java)来自定义。
4.问:我总觉得框架中提供的最新版本APK下载服务速度不行,我想实现自己的下载服务,并做相关下载进度的提示,可以吗?
答:可以自定义版本更新下载器IUpdateDownloader
,它主要负责的是下载最新的版本APK安装包。可参考框架默认提供的版本更新下载器来自定义。
5.问:我的应用和普通应用有些特别,并不能使用系统的安装api安装程序,我该怎么办?
答:如果你的apk安装与众不同,你可以实现自己的apk安装器。你只需要实现OnInstallListener
接口,并通过XUpdate.setOnInstallListener
进行设置即可生效。
【注意】以上实现的自定义接口,都可以通过XUpdate
进行全局和局部的设置。
错误码
错误码 | 备注
:-|:-
2000 | 查询更新失败
2001 | 没有wifi
2002 | 没有网络
2003 | 正在进行版本更新
2004 | 无最新版本
2005 | 版本检查返回空
2006 | 版本检查返回json解析失败
2007 | 已经被忽略的版本
2008 | 应用下载的缓存目录为空
3000 | 版本提示器异常错误
3001 | 版本提示器所在Activity页面被销毁
4000 | 新应用安装包下载失败
4001 | 读写权限申请失败
5000 | apk安装失败
5100 | 未知错误
资源链接
Android基础库: https://github.com/xuexiangjys/XUpdate
React-Native插件: https://github.com/xuexiangjys/react-native-xupdate
微信公众号
更多资讯内容,欢迎扫描关注我的个人微信公众号:【我的Android开源之旅】
版权声明: 本文为 InfoQ 作者【翔】的原创文章。
原文链接:【http://xie.infoq.cn/article/334b365bf5ee714dddd8defa4】。文章转载请联系作者。
评论