XUpdate是一个轻量级、高可用性的Android全量版本更新框架。
XUpdate是为了解决在不同项目组、不同平台之间进行统一的Android全量版本更新的库。它具有轻量、灵活、低耦合、高可用等特点,可以很方便地定制属于自己的版本更新。
在没有XUpdate之前的版本更新,Android版本更新基本都是靠写各种版本更新工具类来实现版本更新,更可怕的是有时在不同项目组或者平台之间,它们的版本更新完全是不一样的,这样的结果就是会写无数的版本更新工具类,并且每次更换一个项目组或者平台就需要从头重写再写一遍,非常得麻烦。当时我就在想,版本更新作为一个Android应用基本都有,且内容相对稳定的功能,有没有可能设计出一个通用的、不为业务或者平台所影响的基础库呢?
在着手写XUpdate之前,我特地去Github上搜了一圈有关Android版本更新的内容,发现AppUpdate这个项目star数量最多。但是当我翻阅它的源码之后发现,它设计得并不优美,内部耦合非常严重,不过优点就是Android版本更新的功能基本都涵盖了。于是我就照着它所拥有的功能,结合了我对版本更新的理解进行了重新设计,感兴趣的可点击查看框架UML设计图。
为了方便大家使用, XUpdate提供了一整套的全量版本更新解决方案.
xupdate_default.png
xupdate_background.png
xupdate_force.png
xupdate_ignore.png
xupdate_custom.png
xupdate_system.png
xupdate_management_1.png
xupdate_management_2.png
xupdate_management_3.png
xupdate_management_4.png
1.先在项目根目录的 build.gradle 的 repositories 添加:
allprojects {
repositories {
...
maven { url "https://jitpack.io" }
}
}
2.然后在dependencies添加:
以下是版本说明,选择一个即可。
dependencies {
...
// androidx版本
implementation 'com.github.xuexiangjys:XUpdate:2.0.2'
}
dependencies {
...
// support版本
implementation 'com.github.xuexiangjys:XUpdate:1.1.6'
}
在Application进行初始化配置:
【注意】这里需要注意的是,IUpdateHttpService
必须设置,否则框架将无法正常使用!IUpdateHttpService
的实现可参照Demo中的实现
XUpdate.get()
.debug(true)
.isWifiOnly(true) //默认设置只在wifi下检查版本更新
.isGet(true) //默认设置使用get请求检查版本
.isAutoMode(false) //默认设置非自动模式,可根据具体使用配置
.param("versionCode", UpdateUtils.getVersionCode(this)) //设置默认公共请求参数
.param("appKey", getPackageName())
.setOnUpdateFailureListener(new OnUpdateFailureListener() { //设置版本更新出错的监听
@Override
public void onFailure(UpdateError error) {
if (error.getCode() != CHECK_NO_NEW_VERSION) { //对不同错误进行处理
ToastUtils.toast(error.toString());
}
}
})
.supportSilentInstall(true) //设置是否支持静默安装,默认是true
.setIUpdateHttpService(new OKHttpUpdateHttpService()) //这个必须设置!实现网络请求功能。
.init(this);
【注意】:如果出现任何问题,可开启debug模式来追踪问题。如果你还需要将日志记录在磁盘上,可实现以下接口
XUpdate.get().setILogger(new ILogger() {
@Override
public void log(int priority, String tag, String message, Throwable t) {
//实现日志记录功能
}
});
-keep class com.xuexiang.xupdate.entity.** { *; }
//注意,如果你使用的是自定义Api解析器解析,还需要给你自定义Api实体配上混淆,如下是本demo中配置的自定义Api实体混淆规则:
-keep class com.xuexiang.xupdatedemo.entity.** { *; }
直接调用如下代码即可完成版本更新操作:
XUpdate.newBuild(getActivity())
.updateUrl(mUpdateUrl)
.update();
需要注意的是,使用默认版本更新,请求服务器返回的json格式应包括如下内容:
{
"Code": 0, //0代表请求成功,非0代表失败
"Msg": "", //请求出错的信息
"UpdateStatus": 1, //0代表不更新,1代表有版本更新,不需要强制升级,2代表有版本更新,需要强制升级
"VersionCode": 3,
"VersionName": "1.0.2",
"ModifyContent": "1、优化api接口。\r\n2、添加使用demo演示。\r\n3、新增自定义更新服务API接口。\r\n4、优化更新提示界面。",
"DownloadUrl": "https://raw.githubusercontent.com/xuexiangjys/XUpdate/master/apk/xupdate_demo_1.0.2.apk",
"ApkSize": 2048
"ApkMd5": "..." //md5值没有的话,就无法保证apk是否完整,每次都会重新下载。
}
自动版本更新:自动检查版本 + 自动下载apk + 自动安装apk(静默安装)。只需要设置isAutoMode(true)
,不过如果设备没有root权限的话,是无法做到完全的自动更新(因为静默安装需要root权限)。除此之外,对于某些特殊设备可能需要自定义安装监听才能实现静默安装。
XUpdate.newBuild(getActivity())
.updateUrl(mUpdateUrl)
.isAutoMode(true) //如果需要完全无人干预,自动更新,需要root权限【静默安装需要】
.update();
开启支持后台更新后, 用户点击“后台更新”按钮后,就可以进入到后台更新,不用一直在更新界面等待.
XUpdate.newBuild(getActivity())
.updateUrl(mUpdateUrl)
.supportBackgroundUpdate(true)
.update();
通过设置更新顶部图片、主题色、按钮文字颜色、宽高比率等来实现自定义主题样式.
XUpdate.newBuild(getActivity())
.updateUrl(mUpdateUrl)
.promptThemeColor(ResUtils.getColor(R.color.update_theme_color))
.promptButtonTextColor(Color.WHITE)
.promptTopResId(R.mipmap.bg_update_top)
.promptWidthRatio(0.7F)
.update();
就是用户不更新的话,程序将无法正常使用。
UpdateStatus
字段为2即可。UpdateEntity
的mIsForce
字段为true即可。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 | 是否下载完成后自动安装 |
字段名 | 类型 | 默认值 | 备注 |
---|---|---|---|
mDownloadUrl | String | "" | 下载地址 |
mCacheDir | String | "" | 文件下载的目录 |
mMd5 | String | "" | 下载文件的md5值,用于校验,防止下载的apk文件被替换(最新演示demo中有计算md5值的工具) |
mSize | long | 0 | 下载文件的大小【单位:KB】 |
mIsShowNotification | boolean | false | 是否在通知栏上显示下载进度 |
字段名 | 类型 | 默认值 | 备注 |
---|---|---|---|
mThemeColor | int | R.color.xupdate_default_theme_color | 主题色(进度条和按钮的背景色) |
mTopResId | int | R.drawable.xupdate_bg_app_top | 顶部背景图片资源id |
mButtonTextColor | int | 0 | 按钮文字颜色 |
mSupportBackgroundUpdate | boolean | false | 是否支持后台更新 |
mWidthRatio | float | -1(无约束) | 版本更新提示器宽度占屏幕的比例 |
mHeightRatio | float | -1(无约束) | 版本更新提示器高度占屏幕的比例 |
在了解了版本更新的结构和各部分的功能后,我们就可以根据我们实际的需求进行自定义了.以下是版本更新的组成结构:
IUpdateChecker
:检查是否有最新版本。IUpdateParser
:解析服务端返回的数据结果。IUpdatePrompter
:展示最新的版本信息。IUpdateDownloader
:下载最新的版本APK安装包。IUpdateHttpService
:定义了进行网络请求的相关接口。除此之外,还有两个监听器:
OnUpdateFailureListener
。OnInstallListener
。更新调度核心:
IUpdateProxy
:负责版本更新的流程控制,调用update开始进行版本更新流程。理论上,以上所有组成部分都开放了自定义的api,我们只需要根据我们的需求实现对应的接口即可完成自定义.
如果你不想使用默认版本更新返回的接口数据, 那么你可以实现IUpdateParser
接口即可实现解析器的自定义, 示例如下:
XUpdate.newBuild(getActivity())
.updateUrl(mUpdateUrl3)
.updateParser(new CustomUpdateParser()) //设置自定义的版本更新解析器
.update();
public class CustomUpdateParser implements IUpdateParser {
@Override
public UpdateEntity parseJson(String json) throws Exception {
CustomResult result = JsonUtil.fromJson(json, CustomResult.class);
if (result != null) {
return new UpdateEntity()
.setHasUpdate(result.hasUpdate)
.setIsIgnorable(result.isIgnorable)
.setVersionCode(result.versionCode)
.setVersionName(result.versionName)
.setUpdateContent(result.updateLog)
.setDownloadUrl(result.apkUrl)
.setSize(result.apkSize);
}
return null;
}
}
IUpdateChecker
接口即可实现检查器的自定义。IUpdateParser
接口即可实现解析器的自定义。IUpdatePrompter
接口即可实现提示器的自定义。XUpdate.newBuild(getActivity())
.updateUrl(mUpdateUrl3)
.updateChecker(new DefaultUpdateChecker() {
@Override
public void onBeforeCheck() {
super.onBeforeCheck();
CProgressDialogUtils.showProgressDialog(getActivity(), "查询中...");
}
@Override
public void onAfterCheck() {
super.onAfterCheck();
CProgressDialogUtils.cancelProgressDialog(getActivity());
}
})
.updateParser(new CustomUpdateParser())
.updatePrompter(new CustomUpdatePrompter(getActivity()))
.update();
public class CustomUpdatePrompter implements IUpdatePrompter {
private Context mContext;
public CustomUpdatePrompter(Context context) {
mContext = context;
}
@Override
public void showPrompt(@NonNull UpdateEntity updateEntity, @NonNull IUpdateProxy updateProxy, @NonNull PromptEntity promptEntity) {
showUpdatePrompt(updateEntity, updateProxy);
}
/**
* 显示自定义提示
*
* @param updateEntity
* @param updateProxy
*/
private void showUpdatePrompt(final @NonNull UpdateEntity updateEntity, final @NonNull IUpdateProxy updateProxy) {
String updateInfo = UpdateUtils.getDisplayUpdateInfo(mContext, updateEntity);
new AlertDialog.Builder(mContext)
.setTitle(String.format("是否升级到%s版本?", updateEntity.getVersionName()))
.setMessage(updateInfo)
.setPositiveButton("升级", new DialogInterface.OnClickListener() {
@Override
public void onClick(DialogInterface dialog, int which) {
updateProxy.startDownload(updateEntity, new OnFileDownloadListener() {
@Override
public void onStart() {
HProgressDialogUtils.showHorizontalProgressDialog(mContext, "下载进度", false);
}
@Override
public void onProgress(float progress, long total) {
HProgressDialogUtils.setProgress(Math.round(progress * 100));
}
@Override
public boolean onCompleted(File file) {
HProgressDialogUtils.cancel();
return true;
}
@Override
public void onError(Throwable throwable) {
HProgressDialogUtils.cancel();
}
});
}
})
.setNegativeButton("暂不升级", null)
.setCancelable(false)
.create()
.show();
}
本框架默认使用的文件加密校验方法是MD5加密方式,当然如果你不想使用MD5加密,你也可以自定义文件加密器IFileEncryptor
,以下是MD5文件加密器的实现供参考:
/**
* 默认的文件加密计算使用的是MD5加密
*
* @author xuexiang
* @since 2019-09-06 14:21
*/
public class DefaultFileEncryptor implements IFileEncryptor {
/**
* 加密文件
*
* @param file
* @return
*/
@Override
public String encryptFile(File file) {
return Md5Utils.getFileMD5(file);
}
/**
* 检验文件是否有效(加密是否一致)
*
* @param encrypt 加密值, 如果encrypt为空,直接认为是有效的
* @param file 需要校验的文件
* @return 文件是否有效
*/
@Override
public boolean isFileValid(String encrypt, File file) {
return TextUtils.isEmpty(encrypt) || encrypt.equalsIgnoreCase(encryptFile(file));
}
}
最后再调用XUpdate.get().setIFileEncryptor
方法设置即可生效。
XUpdate.newBuild(getActivity())
.apkCacheDir(PathUtils.getExtDownloadsPath()) //设置下载缓存的根目录
.build()
.download(mDownloadUrl, new OnFileDownloadListener() { //设置下载的地址和下载的监听
@Override
public void onStart() {
HProgressDialogUtils.showHorizontalProgressDialog(getContext(), "下载进度", false);
}
@Override
public void onProgress(float progress, long total) {
HProgressDialogUtils.setProgress(Math.round(progress * 100));
}
@Override
public boolean onCompleted(File file) {
HProgressDialogUtils.cancel();
ToastUtils.toast("apk下载完毕,文件路径:" + file.getPath());
return false;
}
@Override
public void onError(Throwable throwable) {
HProgressDialogUtils.cancel();
}
});
_XUpdate.startInstallApk(getContext(), FileUtils.getFileByPath(PathUtils.getFilePathByUri(getContext(), data.getData()))); //填写文件所在的路径
如果你的apk安装与众不同,你可以实现自己的apk安装器。你只需要实现OnInstallListener接口,并通过XUpdate.setOnInstallListener
进行设置即可生效。
updateHttpService == null
?答:你需要仔细阅读接入文档,必须在Application中按要求初始化XUpdate
,而其中IUpdateHttpService
必须设置,除非你自定义版本检查器和版本更新下载器,否则框架将无法正常使用!
答:出现这个问题,一般是少了混淆配置。如果你使用了自定义的版本更新解析器,请对你的接口实体进行混淆配置。
答:出现这种情况可以从两个方面来排查。
contentLength
(Content-Length)没有设置,是未知的,那么是不可能有进度的。这个你可以通过抓包来查看响应头中是否设置了“Content-Length”。IUpdateHttpService
的download
接口实现有问题,你务必要保证接口DownloadCallback
的onProgress
方法能被正常执行。答:出现这个问题,你首先得明确一点的是,你判断是否有最新版本的依据是什么。到底是依据VersionCode
还是VersionName
,这个取决于你实际使用的场景。明确完这一点,你才可以根据日志去判断到底是前端出了问题还是后端出了问题。
答:出现这个问题,只能证明你的后端在返回版本信息的时候并没有返回最新版本文件的MD5值,或者返回了你没有设置。如果你设置了MD5值,那么就是你设置的MD5值和文件计算出来的MD5值不匹配,这种情况下,你的APK文件极有可能被篡改了(当然在这种情况下,你也不能正常安装),或者是你们前后端的MD5值计算算法不一致(一般不存在这种情况)。
安装
按钮后一直提示更新失败呢?答:出现这种问题的情况有很多种。
OnInstallListener
接口,实现能够正确安装APK的方法了。答:最好的解决方法当然是打断点逐个进行排查啦!当然在打断点前,我们需要调用XUpdate.get().debug(true)
开启debug模式,打印相关日志,明确出错的位置,这样才能更快地解决问题啦!
System.err: at com.xuexiang.xupdate.widget.BaseDialog.init(BaseDialog.java:72)
错误?答:最好的解决方法就是传入的context使用的是AppCompatActivity
, 而不是Activity
或者FragmentActivity
!如果你一定要使用Activity
或者FragmentActivity
,那么请设置其主题为Theme.AppCompat
类型的主题。
经常有使用者反馈不知道该如何自定义接口(面对一堆接口,不知道该如何下手),进行个性化的定制,以满足版本更新实现的需求,下面我将一一列举问题和解决的方法。
IUpdateHttpService
那套通用请求方式来查询最新版本,我该怎么办?答:可以自定义版本更新检查器IUpdateChecker
,它主要负责的是查询是否存在最新版本。可参考框架默认提供的版本更新检查器来自定义。
答:可以自定义版本更新解析器IUpdateParser
,它主要负责的是解析服务端返回的数据结果,并构建更新信息实体UpdateEntity
。具体可参考自定义版本更新解析器, 也可参考框架默认提供的版本更新解析器来自定义。
答:可以自定义版本更新提示器IUpdatePrompter
,它主要负责的是展示最新的版本信息。具体可参考自定义版本更新提示器, 也可参考框架默认提供的版本更新提示器来自定义。
答:可以自定义版本更新下载器IUpdateDownloader
,它主要负责的是下载最新的版本APK安装包。可参考框架默认提供的版本更新下载器来自定义。
答:如果你的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开源之旅 微信公众号,前往查看
如有侵权,请联系 cloudcommunity@tencent.com 删除。
本文参与 腾讯云自媒体同步曝光计划 ,欢迎热爱写作的你一起参与!