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; // 用户取消升级