史上最好用的Android全量版本更新库XUpdate使用指南

在这里插入图片描述

项目简介

XUpdate是一个轻量级、高可用性的Android全量版本更新框架。

XUpdate是为了解决在不同项目组、不同平台之间进行统一的Android全量版本更新的库。它具有轻量、灵活、低耦合、高可用等特点，可以很方便地定制属于自己的版本更新。

设计原由

在没有XUpdate之前的版本更新，Android版本更新基本都是靠写各种版本更新工具类来实现版本更新，更可怕的是有时在不同项目组或者平台之间，它们的版本更新完全是不一样的，这样的结果就是会写无数的版本更新工具类，并且每次更换一个项目组或者平台就需要从头重写再写一遍，非常得麻烦。当时我就在想，版本更新作为一个Android应用基本都有，且内容相对稳定的功能，有没有可能设计出一个通用的、不为业务或者平台所影响的基础库呢？

设计思路

在着手写XUpdate之前，我特地去Github上搜了一圈有关Android版本更新的内容，发现AppUpdate这个项目star数量最多。但是当我翻阅它的源码之后发现，它设计得并不优美，内部耦合非常严重，不过优点就是Android版本更新的功能基本都涵盖了。于是我就照着它所拥有的功能，结合了我对版本更新的理解进行了重新设计，感兴趣的可点击查看框架UML设计图。

解决痛点

• 使用简单，只需一行代码即可完成版本更新功能。
• 功能强大，兼容Android6.0、7.0、8.0、9.0和10.0，支持静默更新和自动更新，支持国际化。
• 扩展性强，可自定义请求API接口、提示弹窗、下载服务、文件加密器等。
• 搭建简单，只需提供json内容即可支持版本更新。
• 配套齐全，默认提供了后台服务、管理界面以及各类插件。

项目地址

为了方便大家使用, XUpdate提供了一整套的全量版本更新解决方案.

• Android基础库: https://github.com/xuexiangjys/XUpdate
• 版本更新后台服务: https://github.com/xuexiangjys/XUpdateService
• 版本更新管理系统: https://github.com/xuexiangjys/xupdate-management
• Flutter插件: https://github.com/xuexiangjys/flutter_xupdate
• React-Native插件: https://github.com/xuexiangjys/react-native-xupdate

---

项目演示

客户端效果

• 默认版本更新

image

• 后台更新

xupdate_background.png

• 强制版本更新

xupdate_force.png

• 可忽略版本更新

xupdate_ignore.png

• 自定义提示弹窗主题

image

• 使用系统弹窗提示

xupdate_system.png

后台管理界面

• 登录页面

在这里插入图片描述

• 后台管理主页

xupdate_management_2.png

• 应用版本添加

xupdate_management_3.png

• 应用版本修改

image

---

集成指南

添加Gradle依赖

1.先在项目根目录的 build.gradle 的 repositories 添加:

allprojects {
     repositories {
        ...
        maven { url "https://jitpack.io" }
    }
}

2.然后在dependencies添加:

以下是版本说明，选择一个即可。

• androidx版本：2.0.0及以上

dependencies {
  ...
  // androidx版本
  implementation 'com.github.xuexiangjys:XUpdate:2.0.2'
}

• support版本：1.1.6及以下

dependencies {
  ...
  // support版本
  implementation 'com.github.xuexiangjys:XUpdate:1.1.6'
}

初始化SDK

在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();

自定义版本更新主题样式

通过设置更新顶部图片、主题色、按钮文字颜色、宽高比率等来实现自定义主题样式.

• promptThemeColor: 设置主题颜色
• promptButtonTextColor: 设置按钮的文字颜色
• promptTopResId: 设置顶部背景图片
• promptWidthRatio: 设置版本更新提示器宽度占屏幕的比例，默认是-1，不做约束
• promptHeightRatio: 设置版本更新提示器高度占屏幕的比例，默认是-1，不做约束

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();

强制版本更新

就是用户不更新的话，程序将无法正常使用。

• 如果你使用的是默认版本更新返回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.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。

• 版本更新apk安装的监听器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的下载器功能进行apk的下载

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的APK安装的功能

_XUpdate.startInstallApk(getContext(), FileUtils.getFileByPath(PathUtils.getFilePathByUri(getContext(), data.getData()))); //填写文件所在的路径

如果你的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。具体可参考自定义版本更新解析器, 也可参考框架默认提供的版本更新解析器来自定义。

3.问：我觉得框架提供的一套默认的版本更新提示界面不符合我们公司的UI风格，我能自定义一套自己的版本更新提示界面吗？

答：可以自定义版本更新提示器IUpdatePrompter，它主要负责的是展示最新的版本信息。具体可参考自定义版本更新提示器, 也可参考框架默认提供的版本更新提示器来自定义。

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
• 版本更新后台服务: https://github.com/xuexiangjys/XUpdateService
• 版本更新管理系统: https://github.com/xuexiangjys/xupdate-management
• Flutter插件: https://github.com/xuexiangjys/flutter_xupdate
• React-Native插件: https://github.com/xuexiangjys/react-native-xupdate