SDK接口说明
更新时间：2019-06-14
SDK初始化
-
方式一：
// 自定义一个Application类，继承自OtaApplication类，然后实现initService方法，示例： public class MyApplication extends Application { @Override protected void initService(IOtaSdkHelper helper) { // 通过helper对象，可以调用一系列SDK开放的API，详见下面的IOtaSdkHelper接口类使用说明 } } -
方式二：
// 在自定义的Application类中，调用SDK的初始化接口，示例： public class MyApplication extends Application { @Override protected void attachBaseContext(Context base) { super.attachBaseContext(base); OtaApplicationInit.attachBaseContext(base, new MyOtaListener()); } @Override public void onCreate() { super.onCreate(); OtaApplicationInit.onCreate(); } private class MyOtaListener implements OtaApplicationInit.IOtaListener { @Override public void initService(IOtaSdkHelper helper) { // 与方式1中initService的实现保持一致 } } }
IOtaSdkHelper接口类
public interface IOtaSdkHelper {
/**
* 获取ota实例
*
* @param vehicleId 车辆ID
* @param otaId 从平台获取的otaId
* @param otaSecret 从平台获取的otaSecret
* @param info 系统信息接口，用户自行实现
* @return ota接口对象，可以通过它调用升级相关API
*/
IOtaAgent getInst(String vehicleId, String otaId, String otaSecret, ISystemInfo info);
/**
* 获取ota实例
*
* @param vehicleId 车辆ID
* @param otaId 从平台获取的otaId
* @param otaSecret 从平台获取的otaSecret
* @param info 系统信息接口，用户自行实现
* @param upgradeInterface 自定义升级接口，用户自行实现，可参考DefaultUpgradeImpl的实现方式
* @return ota接口对象，可以通过它调用升级相关API
*/
IOtaAgent getInst(String vehicleId, String otaId, String otaSecret, ISystemInfo info, IUpgradeInterface upgradeInterface);
/**
* 设置升级路径，ota文件下载存储路径(仅作用于系统升级、APP下载路径已内置)
* 由于不同厂商定制ROM时，recovery模式可访问的分区权限、空间容量有差异，请根据当前设备环境进行设置
* 建议通过系统API获取，若不设置，默认为/cache分区路径（Android8.1以后为/data/cache）
*
* @param path 存储路径，请使用API获取
*/
void setUpgradePath(String path);
/**
* 设置日志生成路径
* 默认为/data/xxx/包名/files/ota_log.txt，建议使用默认路径
*
* @param path 日志路径，请使用API获取
*/
void setLogPath(String path);
/**
* 设置日志显示级别（2~6即Verbose~Error）
*
* @param level 级别，默认为2（全部写入到日志文件）
*/
void setLogLevel(int level);
/**
* 设置自动检查更新通知
* 默认开启，开启时，SDK会定时发送检查更新请求（30min），
* 若检查到更新，SDK会发送一个action为otasdk.ota.Constants.BROADCAST_NEWVERSION的本地广播，
* 开发者可以根据广播信息来定制符合当前设备接入场景的更新通知，例如UI提示、语言提示等。
* <p>
* BroadcastReceiver::onReceive中返回的更新信息包含：
* - otaId： key为otasdk.ota.Constants.BROADCAST_KEY_PID
* - 更新内容：key为otasdk.ota.Constants.BROADCAST_KEY_INFOS，值为json字符串，示例：
* [{
* "package":"com.android.system", // 包名
* "version":"8.1.0.0", // 版本号
* "info":"zipfiletest", // 更新信息
* "updtype":1, // 类型（0:安装，1:更新，2:删除）
* "detail":{"key":"val",...} // 用户配置自定义字段
* },
* {
* "package":"com.baidu.demo",
* "version":"3.0.0.760",
* "info":"existtest",
* "updtype":0,
* "detail":{"key":"val",...}
* },
* {
* "package":"com.baidu.test",
* "version":"",
* "info":"del test",
* "updtype":2,
* "detail":{"key":"val",...}
* }]
*
* @param autoCheck 是否自动检查
*/
void setAutoCheck(boolean autoCheck);
/**
* 设置静默升级时间段，用户定制，后台配置了静默升级才生效
* 时间格式（时:分钟，如09:50）
*
* @param timeBegin 开始时间（如23:30）
* @param timeEnd 结束时间（如02:20）
*/
void setSilentUpgradeTime(String timeBegin, String timeEnd);
/**
* 设置扩展选项
* key=1：下载进度反馈时间间隔，value为毫秒，默认300ms
* key=2：下载连接超时时间，value为毫秒，默认20000ms
* key=3：下载读流超时时间，value为毫秒，默认60000ms
* key=4：下载失败重试次数，value为次数，默认3次
* key=5：网络异常导致的下载失败，网络恢复后是否自动续传下载，默认不启用，value为1时启用，为0时不启用
* key=9：下载文件前是否对URL进行Encode，value为0或1，0为开启，1为关闭，默认开启
*
* @param key 选项
* @param value 选项值
*/
void setExtOption(int key, String value);
/**
* 预置app包名（针对需要更新设备已安装的应用，确保不会请求到低版本的任务）
* @param appNames app包名列表
*/
void presetAppNames(List<String> appNames);
}ISystemInfo接口类
public interface ISystemInfo {
/**
* 返回系统当前的版本号，系统检查升级的关键参数。
* 格式要求：4段式（例1.23.45.678），不足4段SDK会自动使用0填充（例1.6 -> 1.6.0.0）
* 约束：4段式的版本号每段字符串值的整数值范围为0～2^63-1
* 系统版本号位于系统文件build.prop中，可通过系统API SystemProperties获取，若格式不满足要求，请格式化为4段数字格式
* 系统更新采用版本号比较的方式，版本号格式错误将无法检测到更新
*
* @return 系统当前版本，不能为空
*/
String getVersion();
/**
* 返回系统型号
*
* @return 系统型号，不能为空
*/
String getModel();
/**
* 返回CPU类型
*
* @return CPU类型，不能为空
*/
String getCPU();
}IUpgradeInterface接口类
public interface IUpgradeInterface {
/**
* 安装升级包(系统或app)
* 调用了IOtaAgent::upgrade时会调用到此接口
*
* @param pkgName app包名
* @param file 升级包文件（系统ota包或apk文件）
* @param silence 静默安装
* @return 成功返回""，失败返回错误原因
*/
String installPackage(String pkgName, String file, boolean silence);
/**
* 卸载程序（仅app）
*
* @param pkgName app包名
* @param silence 静默卸载
* @return 成功返回""，失败返回错误原因
*/
String unInstallPackage(String pkgName, boolean silence);
/**
* 设置升级监听
*
* @param listener 监听器
*/
void setListener(IUpgradeListener listener);
}DefaultUpgradeImpl默认升级实现类
（可在此类基础上自定义升级包的安装、卸载）
public class DefaultUpgradeImpl implements IUpgradeInterface {
private final String productId;
protected final WeakReference<Context> context;
private BlockingQueue<IUpgradeListener> listeners = new LinkedBlockingQueue(1);
private Map<String, IUpgradeListener> listenerMap = new ConcurrentHashMap();
public DefaultUpgradeImpl(Context context, String productId) {
this.context = new WeakReference(context);
this.productId = productId;
}
/**
* 安装升级包
* @param pkgName app包名
* @param fileName 升级包文件（系统ota包或apk文件）
* @param silence 静默安装
* @return 成功返回""，失败返回错误原因
*/
@Override
public String installPackage(String pkgName, String fileName, boolean silence) {
IUpgradeListener listener = null;
try {
listener = (IUpgradeListener)this.listeners.take();
} catch (InterruptedException var7) {
var7.printStackTrace();
}
this.listenerMap.put(pkgName, listener);
File file = new File(fileName);
if (!file.exists()) {
return "package file is not exist";
} else {
String result = this.install(pkgName, file, silence);
if (TextUtils.isEmpty(result)) {
return "";
} else {
if (this.failDelPackage() && !TextUtils.isEmpty(result) && !"upgrade_pending".equals(result)) {
file.delete();
}
return result;
}
}
}
private String install(String pkgName, File file, boolean slience) {
if ("com.android.system".compareToIgnoreCase(pkgName) == 0) {
return this.installSystem(file, slience);
} else {
this.installApp(pkgName, file, slience);
return "upgrade_pending";
}
}
/**
* 卸载包
* @param pkgName app包名
* @param silence 静默卸载
* @return 成功返回""，失败返回错误原因
*/
@Override
public String unInstallPackage(String pkgName, boolean silence) {
IUpgradeListener listener = null;
try {
listener = (IUpgradeListener)this.listeners.take();
} catch (InterruptedException var5) {
var5.printStackTrace();
}
this.listenerMap.put(pkgName, listener);
this.uninstallApp(pkgName, silence);
return "upgrade_pending";
}
/**
* 安装系统：自定义安装系统，请重载此方法
* @param file ota文件
* @param silence 静默安装
* @return 成功返回""，失败返回错误原因。如果是异步升级，则返回Constants.UPGRADE_PENDING，表示安装成功后，等待设备重启
*/
protected String installSystem(File file, boolean silence) {
try {
RecoverySystem.installPackage((Context)this.context.get(), file);
return "";
} catch (IOException var5) {
var5.printStackTrace();
return "installPackage fail:" + var5.toString();
}
}
/**
* 安装app：自定义安装app，请重载此方法
* @param pkg 包名
* @param apkFile apk文件
* @param silence 静默安装
* @return 成功返回""，失败返回错误原因
*/
protected String installApp(String pkg, File apkFile, boolean silence) {
return ""; // 略
}
/**
* 卸载app：自定义卸载app，请重载此方法
* @param pkgName 包名
* @param silence 是否静默
*/
protected void uninstallApp(String pkgName, boolean silence) {
// 略
}
/**
* 获取安装监听对象
* @param pkg 包名
* @return 监听器
*/
protected IUpgradeListener getListener(String pkg) {
return (IUpgradeListener)this.listenerMap.get(pkg);
}
@Override
public void setListener(IUpgradeListener listener) {
try {
this.listeners.put(listener);
} catch (InterruptedException var3) {
var3.printStackTrace();
}
}
/**
* 升级失败是否删除ota包
* @return
*/
protected boolean failDelPackage() {
return true;
}
}IOtaAgent接口类
public interface IOtaAgent {
/**
* 获取sdk信息
*
* @return json格式字符串
* 例如：
* {
* "vendor_version":"6.0.1", // rom版本
* "sdk_version":"1.0.18" // sdk版本
* }
*/
String getSdkInfo();
/**
* 获取产品id，即otaId
*
* @return otaId
*/
String getProductId();
/**
* 检查更新
*
* @param force 是否强制：
* 1. Recovery升级时，传true和false均可；
* 2. A/B系统升级时，自定义升级过程
* 如果回调了升级接口中的IUpgradeListener::onWriteDone，表示新系统已写入磁盘等待设备重启，设备在重启之前均无法请求到系统更新，
* 如果这里传入true，表示强制请求更新
* @param listener 监听器
*/
void checkUpdate(boolean force, ICheckUpdateListener listener);
/**
* 检查更新的扩展方法
*
* @param pkgName 包名（系统包则填空）
* @param listener 监听器
* @param checkExist 检查更新，并检测最新版本ota包是否已下载，如果值为false，则仅检查更新，不判断是否下载
*/
void checkUpdate(String pkgName, ICheckUpdateListenerEx listener, boolean checkExist);
/**
* 指定包名下载
*
* @param pkgName 包名
* @param listener 监听器
*/
void downLoad(String pkgName, IDownloadListener listener);
/**
* 指定包名限速下载
*
* @param pkgName 包名
* @param listener 监听器
* @param limitSpeed 速度上限值（单位KB）
* 网速根据当前网络情况，大约可以在30～60s内收敛
*/
void downLoad(String pkgName, IDownloadListener listener, int limitSpeed);
/**
* 下载全部更新
*
* @param listener 监听器
*/
void downLoadAll(IDownloadListener listener);
/**
* 限速下载全部更新
*
* @param listener 监听器
* @param limitSpeed 限速KB
*/
void downLoadAll(IDownloadListener listener, int limitSpeed);
/**
* 取消指定包名的下载任务
* 下一次调用downLoad会续传下载，不会丢失上一次下载的数据
*
* @param pkgName 包名
*/
void downLoadAbort(String pkgName);
/**
* 取消当前全部下载任务
*/
void downLoadAbortAll();
/**
* 指定包名升级
*
* @param pkgName 包名
* @param listener 监听器
*/
void upgrade(String pkgName, IUpgradeListener listener);
/**
* 本地zip系统包升级（仅系统）
*
* @param localZip 本地update.zip文件
* @param listener 监听器
*/
void upgradeLocal(String localZip, IUpgradeListener listener);
/**
* 安装全部更新
*
* @param listener 监听器
*/
void upgradeAll(IUpgradeListener listener);
/**
* 设置自定义的升级接口实现类，除了通过IOtaSdkHelper初始化IOtaAgent时设置自定义的升级逻辑外，可以通过该方法重新设置
* 建议使用SDK开放的DefaultUpgradeImpl进行扩展
*
* @param customUpgrade 自定义升级接口实现类
*/
void setCustomUpgrade(IUpgradeInterface customUpgrade);
/**
* 添加自定义请求字段（需要配合OTA平台中任务的下发策略配置，若后台任务选择渠道号下发时，key填Constants.CHANNEL）
*
* @param key key
* @param value value
* @return
*/
boolean addReqMetaField(String key, String value);
/**
* 添加扩展节点（特殊场景下的需求）
*
* @param metaName 名称
* @param jsonString json字符串
* @return
*/
boolean addExtMetaData(String metaName, String jsonString);
}监听器ICheckUpdateListener接口类
public interface ICheckUpdateListener {
/**
* 检查到更新，检查成功时调用
*
* @param jsonList 更新列表，json格式，key有package(包名)、version(版本号)、info(更新信息)、updtype(安装类型)，
* 接着可调用IOtaAgent::download下载升级包
* jsonList示例：
* [{
* "package":"com.android.system", // 包名
* "version":"8.1.0.0", // 版本号
* "info":"zipfiletest", // 更新信息
* "updtype":1, // 类型(0:安装，1:更新，2:删除)
* "detail":{"key":"val",...} // 自定义字段
* },
* {
* "package":"com.android.system",
* "version":"8.1.0.0",
* "info":"zipfiletest",
* "updtype":1,
* "detail":{"key":"val",...}
* },
* {
* "package":"com.android.system",
* "version":"8.1.0.0",
* "info":"zipfiletest",
* "updtype":1,
* "detail":{"key":"val",...}
* }]
*/
void onSuccess(String jsonList);
/**
* 检查失败时调用
*
* @param errCode 错误码(见蚊末错误码对照表)
* @param reason 失败原因
*/
void onFail(int errCode, String reason);
// 回调线程为UI主线程，可在回调函数中更新UI
}监听器ICheckUpdateListenerEx扩展接口类
public interface ICheckUpdateListenerEx {
/**
* 检查到更新，检查成功时调用
*
* @param pkgName 包名
* @param updateInfo 更新内容(json格式)，字段信息见ICheckUpdateListener::onSuccess的参数
* @param exist 表示监测到的新版本的ota文件是否已下载，若下载，接着可调用IOtaAgent::upgrade安装升级
*/
void onSuccess(String pkgName, String updateInfo, boolean exist);
/**
* 检查失败时调用
*
* @param pkgName 包名
* @param errCode 错误码(见文末错误码对照表)
* @param reason 失败原因
*/
void onFail(String pkgName, int errCode, String reason);
// 回调线程为UI主线程，可在回调函数中更新UI
}监听器IDownloadListener接口类
public interface IDownloadListener {
/**
* pkgName的任务在等待下载
*
* @param pkgName 包名
*/
void onPending(String pkgName);
/**
* pkgName的下载任务已开始
*
* @param pkgName 包名
*/
void onPrepare(String pkgName);
/**
* pkgName的下载任务进度更新
*
* @param pkgName 包名
* @param sofarBytes 当前下载长度
* @param totalBytes 总长度
*/
void onProgress(String pkgName, int sofarBytes, int totalBytes);
/**
* pkgName的下载任务被中断
*
* @param pkgName 包名
*/
void onPaused(String pkgName);
/**
* pkgName的下载任务出现异常而终止
* @param pkgName 包名
* @param errCode 错误码(见文末错误码对照表)
* @param reason 失败原因
*/
void onFailed(String pkgName, int errCode, String reason);
/**
* pkgName的任务下载成功，此时可调用接口IOtaAgent::upgrade安装升级包
*
* @param pkgName 包名
*/
void onFinished(String pkgName);
// 回调线程为UI主线程，可在回调函数中更新UI
}监听器IUpgradeListener接口类
public interface IUpgradeListener {
/**
* 升级进度更新
*
* @param pkgName 包名
* @param stage 升级阶段(decodepackage、verifypackage、installpackage)
* @param percent 进度(1～100)
*/
void onProgress(String pkgName, String stage, int percent);
/**
* 升级失败
*
* @param pkgName 包名
* @param errCode 错误码(见文末错误码对照表)
* @param reason 失败原因
*/
void onFailed(String pkgName, int errCode, String reason);
/**
* 升级成功
* (使用Recovery的系统更新，此方法不调用，因为设备已经重启进入Recovery了，系统重启后会通过广播发出系统升级结果，
* 请注册action为constants.BROADCAST_UPGRADE的广播接收器来获取升级结果信息，
* key为constants.BROADCAST_UPGRADE.BROADCAST_UPGRADE_DATA，值为json字符串，json各字段分别为：
* "result":true/false
* "package":"包名"
* "curver":"当前系统版本"
* "oldver":"升级前版本")
* @param pkgName 包名
*/
void onSuccess(String pkgName);
/**
* (自定义升级时可能需要，非必调接口)：不立即重启、但需要重启才生效的安装过程(A/B系统升级)，
* 调用此方法产生数据上报，可避免重复请求到更新任务，关联接口checkUpdate(boolean force,...)
* @param pkgName 包名
*/
void onWriteDone(String pkgName);
// 回调线程为UI主线程，可在回调函数中更新UI
}监听器IUpgradeListenerEx扩展接口类
public interface IUpgradeListenerEx extends IUpgradeListener {
/**
* 升级确认
*
* @param taskState 任务状态 0:正常；1:任务被取消；2:任务被暂停
* @return true:确认升级，false:取消升级
*/
boolean upgradeConfirm(int taskState);
// 回调线程为子线程
}接口回调错误码对照表
所属包名：com.baidu.commonlib.interfaces.ErrorCode
checkUpdate回调错误码：
public static final int CHECK_PARAM_ERROR = 1; // 参数错误
public static final int CHECK_NET_ERROR = 2; // 网络错误
public static final int CHECK_NO_UPDATE = 3; // 无更新download回调错误码：
public static final int DOWNLOAD_PARAM_ERROR = 11; // 参数错误
public static final int DOWNLOAD_NET_ERROR = 12; // 网络错误
public static final int DOWNLOAD_NO_SPACE = 13; // 空间不足
public static final int DOWNLOAD_APP_INSTALLED_ERROR = 14; // 安装app，app已安装错误
public static final int DOWNLOAD_APP_NOT_INSTALL_ERROR = 15; // 更新app，app未安装错误
public static final int DOWNLOAD_LOW_VERSION_ERROR = 16; // 更新app，版本过低错误upgrade错误码：
public static final int UPGRADE_PARAM_ERROR = 21; // 参数错误
public static final int UPGRADE_SHA1_VERIFY_ERROR = 22; // sha1校验失败
public static final int UPGRADE_SIGN_VERIFY_ERROR = 23; // 签名校验失败
public static final int UPGRADE_FILE_NOT_EXIST_ERROR = 24; // 文件不存在
public static final int UPGRADE_NOT_INSTALLED_ERROR = 25; // 卸载app，app未安装
public static final int UPGRADE_INSTALL_ERROR = 26; // app安装错误
public static final int UPGRADE_UNINSTALL_ERROR = 27; // app卸载错误
public static final int UPGRADE_CUSTOM_ERROR = 28; // 安装自定义错误
public static final int UPGRADE_USER_NOT_CONFIRM = 29; // 用户取消升级