SDK稳健接入

1.1 Android SDK及工具下载

阿里云Sophix 3.0版本现已上线！

Sophix提供了一套更加完美的客户端服务端一体的热更新方案，做到了图形界面一键打包、加密传输、签名校验和服务端控制发布与灰度功能，让你用最少的时间实现最强大可靠的全方位热更新。

• 一张表格来说明一下各个版本热修复的差别：

说明：

• [0] 部分情况指的是构造方法、参数数目大于8或者参数包括long,double,float基本类型的方法。
• [1] 冷启动方式，指的是需要重启app在下次启动时才能生效。
• [2] 对于Andfix及Hotfix 1.X能够支持的代码变动情况，都能做到即时生效。而对于其他代码变动较大的情况，会走冷启动方式，此时就无法做到即时生效。
• [3] Hotfix 1.X已经支持绝大部分主流手机，只是在X86设备以及修改了虚拟机底层结构的ROM上不支持。
• [4] 由于支持了资源和库，如果有这些方面的更新，就会导致的补丁变大一些，这个是很正常的。并且由于只包含差异的部分，所以补丁已经是最大程度的小了。
• [5] 提供服务端的补丁发布和停发、版本控制和灰度功能，存储开发者上传的补丁包。

1.2 集成准备

1.2.1 android studio集成方式

gradle远程仓库依赖, 打开项目找到app的build.gradle文件，添加如下配置：

添加maven仓库地址：

repositories {
   maven {
       url "http://maven.aliyun.com/nexus/content/repositories/releases"
   }
}

添加gradle坐标版本依赖：

compile 'com.aliyun.ams:alicloud-android-hotfix:3.2.7'

注意，若SDK集成过程中出现UTDID冲突，请参考：阿里云-移动云产品SDK UTDID冲突解决方案。

如若仓库访问失败, 那么用本地依赖的方式进行依赖, SDK下载见“1.5 客户端本地SDK及DEMO下载”节。

注意：使用android studio打包生成apk时，要关闭instant run。

1.2.2 eclipse集成方式

• 下载OneSDk.zip，解压出hotfix_core-release.aar文件后再解压这个aar文件
• 复制解压文件jni目录下的libsophix.so到自己的jni目录下, eclipse jni目录一般指的就是项目libs目录
• 复制utdid4all-1.1.5.3_proguard.jar和alicloud-android-utils-1.0.3.jar文件到项目libs目录下
• 重命名classes.jar为sophix.jar并复制到项目libs目录下
• 合并AndroidManifest.xml文件中的内容到本项目AndroidManifest.xml文件

编译期间报utdid类重复异常, 那么步骤2中添加的utdid4all-1.1.5.3_proguard.jar从项目libs目录移除即可

1.2.3 权限说明

Sophix SDK使用到以下权限

<! -- 网络权限 -->
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<! -- 外部存储读权限，调试工具加载本地补丁需要 -->
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"/>

READ_EXTERNAL_STORAGE权限属于Dangerous Permissions，仅调试工具获取外部补丁需要，不影响线上发布的补丁加载，调试时请自行做好android6.0以上的运行时权限获取。

1.2.4 配置AndroidManifest文件

在AndroidManifest.xml中间的application节点下添加如下配置：

<meta-data
android:name="com.taobao.android.hotfix.IDSECRET"
android:value="App ID" />
<meta-data
android:name="com.taobao.android.hotfix.APPSECRET"
android:value="App Secret" />
<meta-data
android:name="com.taobao.android.hotfix.RSASECRET"
android:value="RSA密钥" />

将上述value中的值分别改为通过平台HotFix服务申请得到的App Secret和RSA密钥，出于安全考虑，建议使用setSecretMetaData这个方法进行设置，详见1.3.2.2的方法说明。

注：App ID/App Secret将被用于计量计费，请妥善保管注意安全。

1.2.5 混淆配置

#基线包使用，生成mapping.txt
-printmapping mapping.txt
#生成的mapping.txt在app/build/outputs/mapping/release路径下，移动到/app路径下
#修复后的项目使用，保证混淆结果一致
#-applymapping mapping.txt
#hotfix
-keep class com.taobao.sophix.**{*;}
-keep class com.ta.utdid2.device.**{*;}
-dontwarn com.alibaba.sdk.android.utils.**
#防止inline
-dontoptimize

1.3 SDK接口使用说明

1.3.1 接入范例

initialize的调用应该尽可能的早，必须在Application.attachBaseContext()的最开始（在super.attachBaseContext之后，如果有Multidex，也需要在Multidex.install之后）进行SDK初始化操作，初始化之前不能用到其他自定义类，否则极有可能导致崩溃。而查询服务器是否有可用补丁的操作可以在后面的任意地方。不建议在Application.onCreate()中初始化，因为如果带有ContentProvider，就会使得Sophix初始化时机太迟从而引发问题。

SDK稳健接入

Sophix最新版本引入了新的初始化方式。

原来的初始化方式仍然可以使用。只是新方式可以提供更全面的功能修复支持，将会带来以下优点：初始化与应用原先业务代码完全隔离，使得原先真正的Application可以修复，并且减少了补丁预加载时间等等。另外，新方式能够更完美地兼容Android 8.0以后版本。

具体而言，是需要用户自行加入以下这个类：

package com.my.pkg;
import android.app.Application;
import android.content.Context;
import android.support.annotation.Keep;
import android.util.Log;
import com.taobao.sophix.PatchStatus;
import com.taobao.sophix.SophixApplication;
import com.taobao.sophix.SophixEntry;
import com.taobao.sophix.SophixManager;
import com.taobao.sophix.listener.PatchLoadStatusListener;
import com.my.pkg.MyRealApplication;
/**
 * Sophix入口类，专门用于初始化Sophix，不应包含任何业务逻辑。
 * 此类必须继承自SophixApplication，onCreate方法不需要实现。
 * 此类不应与项目中的其他类有任何互相调用的逻辑，必须完全做到隔离。
 * AndroidManifest中设置application为此类，而SophixEntry中设为原先Application类。
 * 注意原先Application里不需要再重复初始化Sophix，并且需要避免混淆原先Application类。
 * 如有其它自定义改造，请咨询官方后妥善处理。
 */
public class SophixStubApplication extends SophixApplication {
    private final String TAG = "SophixStubApplication";
    // 此处SophixEntry应指定真正的Application，并且保证RealApplicationStub类名不被混淆。
    @Keep
    @SophixEntry(MyRealApplication.class)
    static class RealApplicationStub {}
    @Override
    protected void attachBaseContext(Context base) {
        super.attachBaseContext(base);
//         如果需要使用MultiDex，需要在此处调用。
//         MultiDex.install(this);
        initSophix();
    }
    private void initSophix() {
        String appVersion = "0.0.0";
        try {
            appVersion = this.getPackageManager()
                             .getPackageInfo(this.getPackageName(), 0)
                             .versionName;
        } catch (Exception e) {
        }
        final SophixManager instance = SophixManager.getInstance();
        instance.setContext(this)
                .setAppVersion(appVersion)
                .setSecretMetaData(null, null, null)
                .setEnableDebug(true)
                .setEnableFullLog()
                .setPatchLoadStatusStub(new PatchLoadStatusListener() {
                    @Override
                    public void onLoad(final int mode, final int code, final String info, final int handlePatchVersion) {
                        if (code == PatchStatus.CODE_LOAD_SUCCESS) {
                            Log.i(TAG, "sophix load patch success!");
                        } else if (code == PatchStatus.CODE_LOAD_RELAUNCH) {
                            // 如果需要在后台重启，建议此处用SharePreference保存状态。
                            Log.i(TAG, "sophix preload patch success. restart app to make effect.");
                        }
                    }
                }).initialize();
    }
}

// queryAndLoadNewPatch不可放在attachBaseContext 中，否则无网络权限，建议放在后面任意时刻，如onCreate中
SophixManager.getInstance().queryAndLoadNewPatch();

这其中，关键一点是：

    @Keep
    @SophixEntry(MyRealApplication.class)
    static class RealApplicationStub {}

SophixEntry应指定项目中原先真正的Application（原项目里application的android::name指定的），这里用MyRealApplication指代。并且保证RealApplicationStub类名不被混淆。而SophixStubApplication的类名和包名可以自行取名。

这里的Keep是android.support包中的类，目的是为了防止这个内部静态类的类名被混淆，因为sophix内部会反射获取这个类的SophixEntry。如果项目中没有依赖android.support的话，就需要在progurad里面手动指定RealApplicationStub不被混淆，详见下文。

然后，在proguard文件里面需要加上下面内容：

-keepclassmembers class com.my.pkg.MyRealApplication {
    public <init>();
}
# 如果不使用android.support.annotation.Keep则需加上此行
# -keep class com.my.pkg.SophixStubApplication$RealApplicationStub

目的是防止真正Application的构造方法被proguard混淆。

最后，需要把AndroidManifest里面的application改为这个新增的SophixStubApplication类：

    <application
        android:name="com.my.pkg.SophixStubApplication"
        ... ...>
        ... ...

这样便完成了新方式的初始化接入改造。

总结一下，过程一共有四个步骤：

1. 把此SophixStubApplication入口类添加进项目中，所有Sophix相关初始化放在此类中。并且不应包含开发者的任何业务逻辑代码。 若使用了MultiDex，也应在SophixStubApplication的initSophix之前添加，并且需要记得在原来的Application里面去除MultiDex，避免重复调用导致问题。
2. 把RealApplicationStub的SophixEntry注解的内容改为自己原先真正的MyRealApplication类。
3. 混淆文件中确保某些内容不被混淆。
4. AndroidManifest里面的application改为新增的SophixStubApplication入口类。

1.3.2 接口说明

1.3.2.1 initialize方法

• initialize(): <必选>

  该方法主要做些必要的初始化工作以及如果本地有补丁的话会加载补丁, 但不会自动请求补丁。因此需要自行调用queryAndLoadNewPatch方法拉取补丁。这个方法调用需要尽可能的早, 必须在Application的attachBaseContext方法的最前面调用（在super.attachBaseContext之后，如果有Multidex，也需要在Multidex.install之后）, initialize()方法调用之前你需要先调用如下几个方法进行一些必要的参数设置, 方法调用说明如下:

• setContext(application): <必选> 传入入口Application即可

• setAppVersion(appVersion): <必选> 应用的版本号

• setSecretMetaData(idSecret, appSecret, rsaSecret): <可选，推荐使用> 三个Secret分别对应AndroidManifest里面的三个，可以不在AndroidManifest设置而是用此函数来设置Secret。放到代码里面进行设置可以自定义混淆代码，更加安全，此函数的设置会覆盖AndroidManifest里面的设置，如果对应的值设为null，默认会在使用AndroidManifest里面的。

• setEnableDebug(isEnabled): <可选> isEnabled默认为false, 是否调试模式, 调试模式下会输出日志以及不进行补丁签名校验. 线下调试此参数可以设置为true, 查看日志过滤TAG:Sophix, 同时强制不对补丁进行签名校验, 所有就算补丁未签名或者签名失败也发现可以加载成功. 但是正式发布该参数必须为false, false会对补丁做签名校验, 否则就可能存在安全漏洞风险

• setAesKey(aesKey): <可选> 用户自定义aes秘钥, 会对补丁包采用对称加密。这个参数值必须是16位数字或字母的组合，是和补丁工具设置里面AES Key保持完全一致, 补丁才能正确被解密进而加载。此时平台无感知这个秘钥, 所以不用担心阿里云移动平台会利用你们的补丁做一些非法的事情。

• setPatchLoadStatusStub(new PatchLoadStatusListener()): <可选> 设置patch加载状态监听器, 该方法参数需要实现PatchLoadStatusListener接口, 接口说明见1.3.2.说明

• setUnsupportedModel(modelName, sdkVersionInt):<可选> 把不支持的设备加入黑名单，加入后不会进行热修复。modelName为该机型上Build.MODEL的值，这个值也可以通过adb shell getprop | grep ro.product.model取得。sdkVersionInt就是该机型的Android版本，也就是Build.VERSION.SDK_INT，若设为0，则对应该机型所有安卓版本。目前控制台也可以直接设置机型黑名单，更加灵活。

1.3.2.2 queryAndLoadNewPatch方法

该方法主要用于查询服务器是否有新的可用补丁. SDK内部限制连续两次queryAndLoadNewPatch()方法调用不能短于3s, 否则的话就会报code:19的错误码. 如果查询到可用的话, 首先下载补丁到本地, 然后

• 应用原本没有补丁, 那么如果当前应用的补丁是热补丁, 那么会立刻加载(不管是冷补丁还是热补丁). 如果当前应用的补丁是冷补丁, 那么需要重启生效.

• 应用已经存在一个补丁, 请求发现有新补丁后，本次不受影响。并且在下次启动时补丁文件删除, 下载并预加载新补丁。在下下次启动时应用新补丁。

  补丁在后台发布之后, 并不会主动下行推送到客户端, 需要手动调用queryAndLoadNewPatch方法查询后台补丁是否可用.

• 只会下载补丁版本号比当前应用存在的补丁版本号高的补丁, 比如当前应用已经下载了补丁版本号为5的补丁, 那么只有后台发布的补丁版本号>5才会重新下载.

同时1.4.0以上版本服务后台上线了“一键清除”补丁的功能, 所以如果后台点击了“一键清除”那么这个方法将会返回code:18的状态码. 此时本地补丁将会被强制清除, 同时不清除本地补丁版本号

1.3.2.3 killProcessSafely方法

可以在PatchLoadStatusListener监听到CODE_LOAD_RELAUNCH后在合适的时机，调用此方法杀死进程。注意，不可以直接Process.killProcess(Process.myPid())来杀进程，这样会扰乱Sophix的内部状态。因此如果需要杀死进程，建议使用这个方法，它在内部做一些适当处理后才杀死本进程。

1.3.2.4 cleanPatches()方法

清空本地补丁，并且不再拉取被清空的版本的补丁。正常情况下不需要开发者自己调用，因为Sophix内部会判断对补丁引发崩溃的情况进行自动清空。

1.3.2.5 PatchLoadStatusListener接口

该接口需要自行实现并传入initialize方法中, 补丁加载状态会回调给该接口, 参数说明如下:

• mode: 无实际意义, 为了兼容老版本, 默认始终为0
• code: 补丁加载状态码, 详情查看PatchStatus类说明
• info: 补丁加载详细说明
• handlePatchVersion: 当前处理的补丁版本号, 0:无 -1:本地补丁 其它:后台补丁

常见状态码说明如下: 一个补丁的加载一般分为三个阶段: 查询/预加载/加载

    //兼容老版本的code说明
    int CODE_LOAD_SUCCESS = 1;//加载阶段, 成功
    int CODE_ERR_INBLACKLIST = 4;//加载阶段, 失败设备不支持
    int CODE_REQ_NOUPDATE = 6;//查询阶段, 没有发布新补丁
    int CODE_REQ_NOTNEWEST = 7;//查询阶段, 补丁不是最新的 
    int CODE_DOWNLOAD_SUCCESS = 9;//查询阶段, 补丁下载成功
    int CODE_DOWNLOAD_BROKEN = 10;//查询阶段, 补丁文件损坏下载失败
    int CODE_UNZIP_FAIL = 11;//查询阶段, 补丁解密失败
    int CODE_LOAD_RELAUNCH = 12;//预加载阶段, 需要重启
    int CODE_REQ_APPIDERR = 15;//查询阶段, appid异常
    int CODE_REQ_SIGNERR = 16;//查询阶段, 签名异常
    int CODE_REQ_UNAVAIABLE = 17;//查询阶段, 系统无效
    int CODE_REQ_SYSTEMERR = 22;//查询阶段, 系统异常
    int CODE_REQ_CLEARPATCH = 18;//查询阶段, 一键清除补丁
    int CODE_PATCH_INVAILD = 20;//加载阶段, 补丁格式非法
    //查询阶段的code说明
    int CODE_QUERY_UNDEFINED = 31;//未定义异常
    int CODE_QUERY_CONNECT = 32;//连接异常
    int CODE_QUERY_STREAM = 33;//流异常
    int CODE_QUERY_EMPTY = 34;//请求空异常
    int CODE_QUERY_BROKEN = 35;//请求完整性校验失败异常
    int CODE_QUERY_PARSE = 36;//请求解析异常
    int CODE_QUERY_LACK = 37;//请求缺少必要参数异常
    //预加载阶段的code说明
    int CODE_PRELOAD_SUCCESS = 100;//预加载成功
    int CODE_PRELOAD_UNDEFINED = 101;//未定义异常
    int CODE_PRELOAD_HANDLE_DEX = 102;//dex加载异常
    int CODE_PRELOAD_NOT_ZIP_FORMAT = 103;//基线dex非zip格式异常
    int CODE_PRELOAD_REMOVE_BASEDEX = 105;//基线dex处理异常
    //加载阶段的code说明 分三部分dex加载, resource加载, lib加载
    //dex加载
    int CODE_LOAD_UNDEFINED = 71;//未定义异常
    int CODE_LOAD_AES_DECRYPT = 72;//aes对称解密异常
    int CODE_LOAD_MFITEM = 73;//补丁SOPHIX.MF文件解析异常
    int CODE_LOAD_COPY_FILE = 74;//补丁拷贝异常
    int CODE_LOAD_SIGNATURE = 75;//补丁签名校验异常
    int CODE_LOAD_SOPHIX_VERSION = 76;//补丁和补丁工具版本不一致异常
    int CODE_LOAD_NOT_ZIP_FORMAT = 77;//补丁zip解析异常
    int CODE_LOAD_DELETE_OPT = 80;//删除无效odex文件异常
    int CODE_LOAD_HANDLE_DEX = 81;//加载dex异常
    // 反射调用异常
    int CODE_LOAD_FIND_CLASS = 82;
    int CODE_LOAD_FIND_CONSTRUCTOR = 83;
    int CODE_LOAD_FIND_METHOD = 84;
    int CODE_LOAD_FIND_FIELD = 85;
    int CODE_LOAD_ILLEGAL_ACCESS = 86;
    //resource加载
    public static final int CODE_LOAD_RES_ADDASSERTPATH = 123;//新增资源补丁包异常
    //lib加载
    int CODE_LOAD_LIB_UNDEFINED = 131;//未定义异常
    int CODE_LOAD_LIB_CPUABIS = 132;//获取primaryCpuAbis异常
    int CODE_LOAD_LIB_JSON = 133;//json格式异常
    int CODE_LOAD_LIB_LOST = 134;//lib库不完整异常
    int CODE_LOAD_LIB_UNZIP = 135;//解压异常
    int CODE_LOAD_LIB_INJECT = 136;//注入异常

1.3.2.6 setTags接口 [v3.2.7新增]

该参数设置端上拉取补丁包时的标签，可以支持条件更为丰富的灰度发布，以下为简单示例：

List<String> tags = new ArrayList<>();
tags.add("test");
//此处调用在initialize()方法前
SophixManager.getInstance().setTags(tags)；

List<String> tags = new ArrayList<>();
tags.add("production");
//此处调用在initialize()方法前
SophixManager.getInstance().setTags(tags)；

如上，设置不同的tags，同一版本号下，可以打两个或者多个基线包，线上发布时用production的基线包，测试环境用test的基线包，这样就可以测试同一版本号下的同一个补丁了，两个环境互不影响。tags可以add多个，结构为前后非空字符串即可。生成补丁时，用同样tags的基线包和修复包。

1.4 版本管理说明

说明一：patch是针对客户端具体某个版本的，patch和具体版本绑定

• eg. 应用当前版本号是1.1.0, 那么只能在后台查询到1.1.0版本对应发布的补丁, 而查询不到之前1.0.0旧版本发布的补丁.

说明二：针对某个具体版本发布的新补丁, 必须包含所有的bugfix, 而不能依赖补丁递增修复的方式, 因为应用仅可能加载一个补丁

• eg. 针对1.0.0版本在后台发布了一个补丁版本号为1的补丁修复了bug1, 然后发现此时针对这个版本补丁1修复的不完全, 代码还有bug2, 在后台重新发布一个补丁版本号为2的补丁, 那么此时补丁2就必须同时包含bug1和bug2的修复才行, 而不是只包含bug2的修复(bug1就没被修复了)

1.5 客户端本地SDK及DEMO下载

下载客户端SDK并集成(下载地址)，Demo程序(Github)

1.6 注意事项

发布前请严格按照：扫码内测 => 灰度发布 => 全量发布的流程进行，以保证补丁包能够正常在所有Android版本的机型上生效。为了保险起见，理论上应该对每个版本的android手机都测一遍是否生效会比较好。不过，其实只需测试通过以下具有代表性的Android版本就基本没什么大问题了：4.0、4.4、5.1、7.0

遇到问题先查看文档：https://help.aliyun.com/knowledge_list/51422.html

通过文档不能解决，可以联系：技术支持

1.7 补丁使用

生成的补丁需要上传到控制台。控制台地址

详情说明见：管理控制台使用

1.8 其他学习资料

• 《深入探索Android热修复技术原理》 —— 业界首部全方位系统介绍热修复原理书籍，从阿里Sophix方案开发过程入手权威解读！

• Sophix技术概览：https://yq.aliyun.com/articles/103527

• 即时生效的代码热修复：https://yq.aliyun.com/articles/74598

• 资源热更新技术详解：https://yq.aliyun.com/articles/96378

• Dalvik下冷启动修复的新探索：https://yq.aliyun.com/articles/107396

• （其他非官方资料？可以加钉钉群，把你的文章与我们分享，我们会挑选好文放在这里~）

其它问题，技术支持参见：地址