省流更新SDK使用说明 - GrouthDownload/TDownloadSDK GitHub Wiki

应用宝省流量更新SDK提供应用更新升级服务：应用的新版本在应用宝开发平台上架之后，便可通过SDK获取到应用的升级信息。应用升级信息通常分为以下两类：

普通更新： 下载新版本应用的全量Apk文件，完成升级；
增量更新： 下载新版本应用与旧版本应用的差分文件，下载完成之后利用本地已安装的旧版Apk文件和所下载的差分文件合成新版本Apk。
普通更新逻辑简单，适合apk包文件体积小的应用；增量更新只下载新旧版本Apk文件的差异文件（差异文件的大小因新旧版本Apk而异，新版本与旧版本差异小的情况下，差异文件的文件大小会非常小），节省用户流量，提高升级效率。由于增量更新涉及比较复杂的合成逻辑，所以此类升级方式只能依赖应用宝App才能完成；普通更新仅需要下载Apk文件，可以在SDK内独立完成，不需要应用宝App介入。

0 省流量更新SDK接入

添加maven仓库

maven {
   url "http://maven.oa.com/nexus/content/repositories/thirdparty"
}

在模块中添加依赖

   implementation "com.tencent.basicservices:patch_update:1.0.2-release102-WithJce-HideHalley-4001"

1 省流量更新SDK初始化

在调用省流量更新SDK提供的接口前，需要对SDK进行初始化。省流量更新SDK初始化涉及参数代码如下所示：

private String mAppKey    = "SuperDownTestDemo2";
private String mAppSecret = "dd40b776992873be708858471220d5b3";

private void initSelfUpdateSDK() {
    Map<String, String> initMap = new HashMap<>();

    initMap.put(InitParam.APP_KEY, mAppKey);
    initMap.put(InitParam.APP_SECRET, mAppSecret);
    initMap.put(UpdateConst.INIT_PARAM.YYB_APK_CHANNEL_ID, "990483");
    initMap.put(UpdateConst.INIT_PARAM.HOST_APP_CHANNEL_ID, "000116083735373738333534");
    initMap.put(UpdateConst.INIT_PARAM.VIA, "ANDROIDQQ.YYB.SELFUPDATE");
    SelfUpdateSDK.init(this, initMap);
}

初始化参数中： 1) appKey/appSecret属于公共参数，接入sdk时分配。 2) YYB_APK_CHANNEL_ID是指拉新应用宝时，下载的应用宝Apk的渠道号，由应用宝产品同学分配，接入时可联系产品同学提供。 3) HOST_APP_CHANNEL_ID是指App自身在应用宝数据源的渠道信息，对应于qms上的channleID字段信息，用于跳转应用宝时下载指定渠道的Apk，如若不需指定渠道，不填即可，切忌填写错误的渠道号。 4) VIA是指用于应用宝识别来源方的字段信息，由应用宝产品同学分配，接入时可联系产品同学提供。

2 应用更新检查

检查应用更新首先需注册接收检查更新结果的监听器，监听器定义具体代码如下：

private ISelfUpdateListener mSelfUpdateListener = new ISelfUpdateListener() {
    @Override
    public void onUpdateStateChanged(TMAppUpdateInfo tmAppUpdateInfo) {
        Log.i(TAG, ">onUpdateStateChanged " + tmAppUpdateInfo);
        //执行更新时，下载任务状态回调
    }

    @Override
    public void onUpdateProgressChanged(TMAppUpdateInfo tmAppUpdateInfo) {
        Log.i(TAG, ">onUpdateProgressChanged " + tmAppUpdateInfo);
        //执行更新时，下载任务进度回调
    }

    @Override
    public void onCheckUpdateSucc(TMAppUpdateInfo tmAppUpdateInfo) {
        Log.i(TAG, ">onCheckUpdateSucc " + tmAppUpdateInfo);
        //检查更新协议成功，接收到更新数据
    }

    @Override
    public void onCheckUpdateFailed(int errorCode) {
        //检查更新协议请求失败
    }
};

监听器中包括两部分：下载任务相关的回调、检查更新相关的回调。检查更新时只涉及检查更新相关的回调。注册监听器，并触发检查更新动作：

SelfUpdateSDK.get().addSelfUpdateListener(mSelfUpdateListener);
SelfUpdateSDK.get().checkSelfUpdate();

当SDK接收到后台返回的更新数据后，通过已注册的监听器告知调用方。

3 使用SDK进行自升级

调用检查更新接口成功接收到更新信息（TMAppUpdateInfo 结构体）后，可通过updateMethod字段判断更新类型，具体类型描述如下代码所述：

private TMAppUpdateInfo mAppUpdateInfo;
private void checkUpdateType() {
    if (mAppUpdateInfo.updateMethod == UpdateConst.TYPE.NO_UPDATE) {
        //无更新
    } else if (mAppUpdateInfo.updateMethod == UpdateConst.TYPE.NORMAL_UPDATE) {
        //普通更新
    } else if (mAppUpdateInfo.updateMethod == UpdateConst.TYPE.PATCH_UPDATE) {
        //增量更新
    }
}

当更新类型为普通更新（后台未返回增量更新数据，无法进行增量更新）时，建议使用SDK进行自升级。第2节已注册更新过程的回调监听器，只需调用SDK更新接口即可开始执行更新流程：

SelfUpdateSDK.get().startSelfUpdateBySDK(mAppUpdateInfo);

任务的下载进度和状态变化会通过监听器回调给调用方。暂停下载任务的接口如下：

SelfUpdateSDK.get().pauseSelfUpdateBySDK(mAppUpdateInfo);

自升级任务的状态用TMAppUpdateInfo 结构体的updateState字段区分，updateState字段的值对应的含义如下代码所示：

private String getShowText(int updateState) {
    String text = "";
    switch (updateState) {
        case UpdateConst.UPDATE_STATE.WATING:
            text = "等待开始下载...";
            break;
        case UpdateConst.UPDATE_STATE.DOWNLOADING:
            text = "下载中";
            break;
        case UpdateConst.UPDATE_STATE.DOWNLOAD_PAUSED:
            text = "已暂停";
            break;
        case UpdateConst.UPDATE_STATE.DOWNLOAD_FAILED:
            text = "下载失败";
            break;
        case UpdateConst.UPDATE_STATE.DOWNLOAD_DELETED:
            text = "下载删除";
            break;
        case UpdateConst.UPDATE_STATE.DOWNLOAD_SUCC:
            text = "自更新任务下载成功";
            break;
        case UpdateConst.UPDATE_STATE.SELF_UPDATE_FAILED:
            text = "自更新任务失败";
            break;
        case UpdateConst.UPDATE_STATE.INSTALL_SUCC:
            text = "自更新任务安装成功";
            break;
        default:
            text = "UNKNOWN";
            break;
    }
    return text;
}

4 使用YYB进行自升级

类似于SDK升级流程，当检查更新的结果为增量更新时，建议使用YYB进行自更新（否则使用SDK升级即普通更新效果）。开始自更新和暂停自更新接口调用如下：

SelfUpdateSDK.get().startSelfUpdateByYYB(mAppUpdateInfo);
SelfUpdateSDK.get().pauseSelfUpdateByYYB(mAppUpdateInfo);

使用YYB进行自更新时，前提条件是需要用户已安装应用宝App。腾讯下载SDK提供判断应用宝是否安装的接口。另外，也提供下载应用宝Apk相关服务的接口。

监听下载应用宝APK任务的状态

初始化监听器：

private TaskListener mYYBDownloadListener = new TaskListener() {
    @Override
    public void onTaskStart(DownloadInfo downloadInfo) {
    }

    @Override
    public void onTaskStateChanged(DownloadInfo downloadInfo) {
        Log.i(TAG, ">onTaskStateChanged " + downloadInfo);
    }

    @Override
    public void onTaskProgressChanged(DownloadInfo downloadInfo) {
        Log.i(TAG, ">onTaskProgressChanged " + downloadInfo);
    }

    @Override
    public void onInstallStart(DownloadInfo downloadInfo) {

    }

    @Override
    public void onInstalled(DownloadInfo downloadInfo) {
        Log.i(TAG, ">onInstalled " + downloadInfo);
    }
};

注册监听器：

SelfUpdateSDK.get().registerDownloadYYBApkListener(mYYBDownloadListener);

触发应用宝Apk下载任务的方式有两种： 1.静默预下载； 2.调用YYB自升级接口自动触发。两者的区别是：预下载不会主动拉起安装，而调用YYB自升级接口自动触发会主动拉起应用宝安装。

预下载应用宝调用：

int ret = SelfUpdateSDK.get().preDownloadYYB();
if (ret == DownloadConst.ALREADY_SUCC_ERROR) {
    Log.e(TAG, "应用宝已经预下载完成了");
}

5 TMAppUpdateInfo字段说明

TMAppUpdateInfo结构体贯穿整个自升级过程，它的主要字段及含义如下：

字段名称	含义
updateMethod	更新类型，值含义参考UpdateConst#TYPE
newApkSize	新版本apk全量包大小
patchSize	增量包大小，仅在增量更新类型时值才有效
newFeature	新版本特性文案
updateDownloadUrl	新版本下载链接
packageName	包名
versionName	版本名
versionCode	版本号
fileMd5	新版本文件MD5
apkId	新版本apkId
appId	新版本appId
updateState	任务所处状态
downloaderType	下载器类型标识，值含义参考UpdateConst#DownloaderType
apkPath	最终apk路径
receivedLength	已接收到的任务大小
totalLength	任务总大小
updateErrorCode	任务出错时的错误码
updateErrorMsg	任务出错时的错误信息
downloadErrorCode	下载过程的错误码，由下载模块定义
pauseOnMobile	任务是否需要在移动网络下自动暂停
hostChannelId	任务包名对应的APP在应用宝数据源的渠道信息
via	业务VIA，标识来源

6 省流量更新SDK交互补充

6.1 判断应用宝是否安装，显示不同界面

if(SelfUpdateSDK.get().isYYBInstalled()) {
    // TODO : 应用宝安装，只显示极速更新按钮
} else {
    // TODO : 应用宝未安装，显示极速更新以及普通更新两个按钮
    // 注册应用宝安装包下载情况监听器，注册监听器可挪至其它更早的位置，具体参考省流量更新文档
    SelfUpdateSDK.get().registerDownloadYYBApkListener(taskListener);
    // 基础服务SDK中base库提供网络环境查询
    // 当前连接WIFI
    if(NetworkUtil.isWifi()) {
        // Wifi状态下后台开始静默下载
        SelfUpdateSDK.get().preDownloadYYB();
    }
}

通过SelfUpdateSDK.get().isYYBInstalled()来判断应用宝是否安装。应用宝已安装返回true，此时只显示极速更新按钮。应用宝未安装返回false，此时显示两个按钮，分别为极速更新按钮以及普通更新按钮。应用宝未安装时，注册一个应用宝下载状况监听器（TaskListener），用来获取应用宝的下载状况信息。应用宝未安装时当前网络状态为Wifi连接时（这里在腾讯下载sdk的base组件中提供网络环境查询函数），后台对应用宝进行静默下载，静默下载调用SelfUpdateSDK.get().preDownloadYYB()。

6.2 点击极速更新按钮

/**
 * 极速更新点击时响应伪代码
 */
public void onClick_SpeedUpdate() {
    if(SelfUpdateSDK.get().isYYBInstalled()) {
        // 应用宝已安装, 拉起应用宝极速更新
        // tmAppUdateInfo为更新应用的信息，类型TMAppUpdateInfo
        // tmAppUdateInfo获取可通过检查更新回调获取，如何进行检查更新参考省流量更新文档
        SelfUpdateSDK.get().startSelfUpdateByYYB(tmAppUpdateInfo);
    } else {
        int ret = SelfUpdateSDK.get().preDownloadYYB();
        // 应用宝未安装但是静默下载完成
        if(ret == DownloadConst.ALREADY_SUCC_ERROR) {
            // 弹出应用宝安装界面,tmYYBUpdateInfo为应用宝应用的信息，类型TMAppUpdateInfo
            SelfUpdateSDK.get().startSelfUpdateByYYB(tmYYBUpdateInfo);
        } else {
            // TODO : 应用宝未安装并且下载未完成，极速更新变为应用宝安装包的下载进度
            // TODO : 下载进度的更新获取可通过应用宝安装包下载情况监听器获取，监听onTaskProgressChanged
        }
    }
}

当点击极速更新按钮，存在两种情况，一种是已安装应用宝（只存在极速更新按钮），另一种是未安装应用宝（同时存在极速更新和普通更新按钮）。 1) 已安装应用宝 点击极速更新按钮，拉起应用宝并进行更新应用，此时调用 SelfUpdateSDK.get().startSelfUpdateByYYB(tmAppUpdateInfo) tmAppUpdateInfo为更新应用的更新信息，具体类型为TMAppUpdateInfo。可通过检查更新回调监听器(ISelfUpdateListener)获取应用的TMAppUpdateInfo。 2) 未安装应用宝 点击极速更新按钮，如果应用宝静默下载完成，则直接拉起应用宝安装，拉起应用宝调用应用宝的自升级接口自动触发。此时调用 SelfUpdateSDK.get().startSelfUpdateByYYB(tmYYBUpdateInfo) tmYYBUpdateInfo为应用宝的更新信息，具体类型为TMAppUpdateInfo。如果应用宝静默下载未完成，则通过应用宝安装包下载安装监听器（TaskListener）中回调函数onTaskProgressChanged、onTaskStateChanged等获取进度变化以及状态变化。

6.3 点击普通更新按钮

/**
 * 普通更新点击时响应
 */
public void onClick_GeneralUpdate() {
    // 使用SDK自升级
    SelfUpdateSDK.get().startSelfUpdateBySDK(tmAppUpdateInfo);
    // TODO : 显示普通下载进度变化条
}

当点击普通更新按钮，直接通过SDK进行下载。此时调用 SelfUpdateSDK.get().startSelfUpdateBySDK(tmAppUpdateInfo) tmAppUpdateInfo为更新应用的更新信息，具体类型为TMAppUpdateInfo。SDK下载进度以及下载状态可通过设置SDK下载监听器（ISelfUpdateListener）获取到。

7 接入测试用例

用例名称	用例描述	前提条件	操作步骤	期待结果
未安装应用宝进行省流量更新	未安装应用宝时点击省流量更新按钮	检测到新版本且未安装应用宝	1.启动应用，显示省流量更新按钮和普通更新按钮。2.点击省流量更新按钮。	1.后台静默下载应用宝安装包。2.点击省流量更新后应用宝安装包下载完成则拉起安装，下载未完成则提示应用宝的下载进度。3.应用宝安装包拉起安装，但是用户拒绝安装，给出提示省流量更新失败。4.应用宝安装成功，跳转应用宝并省流量更新应用。
未安装应用宝进行普通更新	未安装应用宝时点击普通更新按钮	检测到新版本且未安装应用宝	1.启动应用，显示省流量更新按钮和普通更新按钮。2.点击普通更新按钮。	1.后台静默下载应用宝安装包。 2.开始下载应用最新安装包，完成后拉起安装。
安装应用宝进行省流量更新	已安装应用宝点击省流量更新按钮	检测到新版本且安装应用宝	1.启动应用，只显示省流量更新按钮。2.点击省流量更新按钮。	跳转到应用宝界面并省流量更新应用。