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

项目简介

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

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

设计起因

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

设计思路

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

解决痛点

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

项目地址

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

Android基础库: github.com/xuexiangjys…
版本更新后台服务: github.com/xuexiangjys…
版本更新管理系统: github.com/xuexiangjys…
Flutter插件: github.com/xuexiangjys…
React-Native插件: github.com/xuexiangjys…

项目演示

客户端效果

默认版本更新

后台更新

强制版本更新

可忽略版本更新

自定义提示弹窗主题

使用系统弹窗提示

后台管理界面

登陆页面

后台管理主页

应用版本添加

应用版本修改

集成指南

添加Gradle依赖

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

allprojects {
     repositories {
        ...
        maven { url "https://jitpack.io" }
    }
}
复制代码

2.而后在dependencies添加:算法

如下是版本说明，选择一个便可。json

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中的实现react-native

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": "一、优化api接口。\r\n二、添加使用demo演示。\r\n三、新增自定义更新服务API接口。\r\n四、优化更新提示界面。",
  "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基础库: github.com/xuexiangjys…
版本更新后台服务: github.com/xuexiangjys…
版本更新管理系统: github.com/xuexiangjys…
Flutter插件: github.com/xuexiangjys…
React-Native插件: github.com/xuexiangjys…

微信公众号

更多资讯内容，欢迎扫描关注个人我的微信公众号:【个人Android开源之旅】