全部产品
云市场

API参考

更新时间:2018-09-14 17:18:18

1. 系统升级与应用升级的通用接口

  • 在使用ota升级的sdk之前,通过如下接口进行一些初始值的设置。
  • 这些是(系统升级和应用升级)通用的接口,用户接入时,只需做一次即可。
  • 建议在Application的OnCreate里面进行以下接口的调用。

包名:com.aliyun.aicc.fota.sdk

类名:FotaContext

1. 初始化API

FotaContext.getInstance()

2. 设置系统版本号

  • 接口名称:

    public void setFirmwareVersion(Context context, String firmwareVersion)

  • 参数说明:
入参 类型 是否必填 说明
context Context 必填 上下文
firmwareVersion String 必填 字符串,系统版本号遵循如下规则:1. 大版本可以支持4位数字,全部是个位数,比如1.0.0.1,2. 后面必须紧跟一个字母:E、R、F,或者其它 3. 再后面是年、月、日、时、分 4. 示例:1.0.0.1-R-20170606.1125
  • 返回值: 无
  • 说明: 该接口必须被调用,用于设置系统版本号,否则无法进行升级。

3. 设置机型

  • 接口名称:

    public void setDeviceModel(Context context, String deviceModel)

  • 参数说明:
入参 类型 是否必填 说明
context Context 必填 上下文
deviceModel String 必填 字符串,例如”MB202”
  • 返回值: 无
  • 说明: 可以不调用该接口。 如果不调用该接口,机型信息将从系统属性:ro.product.model 中读取。

4. 设置设备类型

  • 接口名称: public void setDeviceType(Context context, String deviceType)
  • 参数说明:
入参 类型 是否必填 说明
context Context 必填 上下文
deviceType String 必填 字符串,例如”phone”,”tv”
  • 返回值: 无
  • 说明:
    • 可以不调用该接口。
    • 如果不调用该接口,设备类型将默认为”phone”。

5. 设置安全图片auth code

  • 接口名称: public void setSafeguardAuth(Context context, String authCode)
  • 参数说明:
入参 类型 是否必填 说明
context Context 必填 上下文
authCode String 必填 字符串,例如”0b28”,用于指定安全图片文件的后缀
  • 返回值: 无
  • 说明:
    • 可以不调用该接口。
    • 如果不调用该接口,将使用默认的安全图片名称:yw_1222.zip

6. 设置设备序列号

  • 接口名称: public void setSerialNumber(Context context, String serialno)
  • 参数说明:
入参 类型 是否必填 说明
context Context 必填 上下文
serialno String 必填 字符串,设备唯一id,例如:”1234567890BB”
  • 返回值: 无
  • 说明: 用于生成device token

7. 设置硬件唯一id

  • 接口名称: public void setHardwareId(Context context, String id)
  • 参数说明:
入参 类型 是否必填 说明
context Context 必填 上下文
id String 必填 字符串,硬件唯一id,可以是device model + Wi-Fi mac地址 + sn串号,sn 串号可以没有。
  • 返回值: 无
  • 说明: 用于生成device token

8. 设置appkey和appsecret

  • 接口名称: public void setAppKeyAndSecrets(Context context, String appkey, String secret)
  • 参数说明:
入参 类型 是否必填 说明
context Context 必填 上下文
appkey String 必填 字符串,例如”adbcdef”
secret String 必填 字符串,例如”adbcdefgh”
  • 返回值: 无
  • 说明: 建议使用安全图片保存appkey与secret,不建议在代码中显示指定appkey和secret。

9. 设置客户端自定义查询条件

  • 接口名称: public void setCustomizedFilterFields(Context context, String jsonString)
  • 参数说明:
入参 类型 是否必填 说明
context Context 必填 上下文
jsonString String 必填 符合json数组格式的字符串
  • 返回值: 无
  • 说明:
    • 参数 jsonString的详细说明
    • -该参数的格式,是符合json数组格式的字符串,格式如下:
  1. [{"name": "field1","value": "value1"},{"name": "field2","value": "value2"},{"name": "field3","value": "value3"}]
      • 通过该字符串,能转换为json数组对象如下:
        1. [
        2. {
        3. "name": "field1",
        4. "value": "value1"
        5. },
        6. {
        7. "name": "field2",
        8. "value": "value2"
        9. },
        10. {
        11. "name": "field3",
        12. "value": "value3"
        13. }
        14. ]

10. 设置服务端的环境

  • 接口名称: public void setEnvironment(String env)
  • 参数说明:
入参 类型 是否必填 说明
env String 必填 服务端的环境,取值如下:FotaContext.CLOUD_ENV_TEST(测试环境)FotaContext.CLOUD_ENV_PRE(预发环境)FotaContext.CLOUD_ENV_ONLINE(线上环境)
  • 返回值: 无
  • 说明:
    • 设置fota运行时,所使用的云端环境
    • 不做任何设置,或者设置的入参有错误时,默认使用测试环境。

11. 代码示例

  1. // 在应用的application的onCreate()方法中,做如下接口的调用
  2. import com.aliyun.aicc.fota.sdk.FotaContext;
  3. FotaContext.getInstance().initContext(this);
  4. FotaContext.getInstance().setFirmwareVersion(getApplicationContext(), "1.0.0.1-R-20170606.1125");
  5. FotaContext.getInstance().setDeviceModel(getApplicationContext(), "MB202");
  6. FotaContext.getInstance().setDeviceType(getApplicationContext(), "tablet");
  7. FotaContext.getInstance().setSafeguardAuth(getApplicationContext(), "0b28");
  8. FotaContext.getInstance()).setSerialNumber(getApplicationContext(), "1234567890BB")
  9. FotaContext.getInstance()).setHardwareId(getApplicationContext(), "MB202B0:35:9F:BE:29:04")
  10. FotaContext.getInstance().setAppKeyAndSecrets(getApplicationContext(), "24657550", "a3e5394705f9a6fbe7b0cc3bc40aede2");
  11. FotaContext.getInstance().setCustomizedFilterFields(this, jsonString);
  12. // 设置所使用的服务端的环境
  13. FotaContext.getInstance().setEnvironment(FotaContext.CLOUD_ENV_TEST);

2. 应用升级接口

2.1 应用升级的设置

  • 包名:com.aliyun.aicc.fota.sdk
  • 类名:FotaAppConfig

2.1.1 构造函数

public static FotaAppConfig getInstance

2.1.2设置自动查询的间隔和包列表

  • 接口名称:public void setAutoCheckPackagesList(Context context,
    1. int autoCheckIntervalInMs,
    2. String[] autoCheckPackagesList)
  • 参数说明
入参 类型 是否必填 说明
context Context 必填 上下文
autoCheckIntervalInMs int 必填 自动查询的间隔
autoCheckPackagesList String[] 必填 需要自动查询的包列表

2.2 升级包的查询、下载、安装、通知

  • 包名:com.aliyun.aicc.fota.sdk
  • 类名:FotaAppUpdateClient

2.2.1 构造函数

public static FotaAppUpdateClient getInstance()

2.2.2 触发自动轮询

public void startAutoCheck(Context context, final int delayedInMs)

  • 参数说明
入参 类型 是否必填 说明
context Context 必填 调用接口的上下文
delayedInMs int 必填 自动查询的间隔

2.2.3 添加AppUpdateListener

public void addAppUpdateListener (Context context, final IAppUpdateListener listener)

  • 参数说明
入参 类型 是否必填 说明
context Context 必填 调用接口的上下文
listener IAppUpdateListener 必填 用于监听AppUpdate的Listener
  • 上述回调函数
    1. interface IAppUpdateListener
    2. {
    3. void onAppCheckUpdateSuccess(String sessionID, in SystemAppXmlInfo info);
    4. void onAppCheckUpdateError(String packageName, int versionCode, int status, int minorStatus, String errMsg);
    5. void onAppDownloadSuccess(String sessionID, in SystemAppXmlInfo info);
    6. void onAppDownloadError(String sessionID, String packageName, int status, int minorStatus, String errMsg);
    7. void onAppInstallSuccess(String sessionID, in SystemAppXmlInfo info);
    8. void onAppInstallError(String sessionID, String packageName, int status, int minorStatus, String errMsg);
    9. void onAppDownloadProgress(String sessionID, String packageName, int status, int progress, String msg);
    10. }

2.2.4 删除AppUpdateListener

public void removeAppUpdateListener (Context context, final IAppUpdateListener listener)

  • 参数说明
入参 类型 是否必填 说明
context Context 必填 调用接口的上下文
listener IAppUpdateListener 必填 用于监听AppUpdate的Listener

2.2.5 触发查询更新包

public void checkUpdate(Context context, final String packageName)

  • 参数说明
入参 类型 是否必填 说明
context Context 必填 调用接口的上下文
packageName String 必填 查询的应用包名

2.2.6 触发下载更新包

  1. public void download(Context context, final String packageName)
  • 参数说明
入参 类型 是否必填 说明
context Context 必填 调用接口的上下文
packageName String 必填 查询的应用包名

2.2.7 触发校验并安装更新包

public void verifyAndInstall(Context context, final String packageName)

  • 参数说明
入参 类型 是否必填 说明
context Context 必填 调用接口的上下文
packageName String 必填 查询的应用包名

2.2.8 查询并下载更新包

  • 接口名称:

public void checkUpdateAndDownload(final Context context, final String packageName, final int currentVersionCode, final String currentVersionName, final Map paramsMap, final IAppUpdateCallback callback)

  • 参数说明:
入参 类型 是否必填 说明
context Context 必填 调用接口的上下文
packageName String 必填 待查询的应用包名
currentVersionCode int 必填 当前应用的version code
currentVersionName String 必填 当前应用的version name
paramsMap Map 必填 调用者自定义查询参数,是k-v键值对
callback IAppUpdateCallback 必填 回调函数
  • 返回值: 无
  • 说明: 该方法在查询到有更新的安装包之后,自动开始下载。

  • 上述回调函数:请实现如下接口:

  1. interface IAppUpdateCallback {
  2. void onAppGotResultSuccess(String sessionID, String packageName,
  3. int versionCode, String versionName,
  4. String appZipType, String path, String extrasJson);
  5. void onAppGotResultError(String packageName, int status,
  6. int minorStatus, String errMsg);
  7. void onProgress(String sessionID, String packageName,
  8. int status, int progress, String msg);
  9. }
  • onAppGotResultSuccess参数说明
出参 类型 是否为空 说明
sessionID String 不为空 调用接口的上下文
packageName String 不为空 待查询的应用包名
versionCode int 不为空 当前应用的version code
versionName String 不为空 当前应用的version name
appZipType String 不为空 1自动安装包类型,7自定义安装包类型
path String 不为空 下载文件路径,应用的data目录下
extrasJson String 可为空 应用包的自定义属性信息
  • 上面的回调函数IAppUpdateCallback中,onAppGotResultError 方法中,参数 status 和minorStatus 的定义:
宏定义 含义
STATUS_CHECKING_FAILED 103 status 查询更新失败了
STATUS_CHECKING_FAILED_NETWORK_NONETWORK 200 查询更新失败了,没有网络
STATUS_CHECKING_FAILED_HTTP_TIMEOUT 201 查询更新失败了,查询time out
STATUS_CHECKING_FAILED_CANNOT_GET_XML 202 查询更新失败了,没有获取到xml
STATUS_CHECKING_FAILED_OTHERS 203 查询更新失败了,其他问题,详情看errorMsg
STATUS_CHECKING_FAILED_GET_NULLXML 204 查询更新失败了,您的版本已是最新了
STATUS_CHECKING_FAILED_PARAM_ERROR 205 查询更新失败了,参数有错
STATUS_DOWNLOADERROR 106 下载更新失败了
STATUS_DOWNLOADERROR_STORAGE_LOWLEVEL 214 下载更新失败了,空间不够
STATUS_DOWNLOADERROR_POWSER_LOW 215 下载更新失败了,电量不够
STATUS_DOWNLOADERROR_NETWORK_MOBILE 216 下载更新失败了,移动网络下
STATUS_DOWNLOADERROR_NETWORK_NONETWORK 217 下载更新失败了,没有网络
STATUS_DOWNLOADERROR_CANCLED 218 下载更新失败了,取消了
STATUS_DOWNLOADERROR_NET_ERROR 219 下载更新失败了,网络有问题
STATUS_DOWNLOADERROR_OTHERS 220 下载更新失败了,其他,详情查看errorMsg
STATUS_DOWNLOADERROR_IO_ERRORS 221 下载更新失败了,IO出错
STATUS_DOWNLOADERROR_XML_ERRORS 223 下载更新失败了,xml出错
STATUS_DOWNLOADERROR_SIGNED_ERRORS 224 下载更新失败了,签名有错
STATUS_VERYFYFAIL_FILE_NOTFOUND 240 下载更新失败了,文件丢失
STATUS_VERYFYFAIL_MD5_CHECK_FAILED 241 下载更新失败了,md5校验失败

2.2.9 通知安装结果

  • 接口名称:public void notifyInstallResult(final Context context,
    1. final String sessionId,
    2. final String packageName,
    3. final int targetVersionCode,
    4. final String targetVersionName,
    5. final int result,
    6. final String errMsg)
  • 参数说明:
入参 类型 是否必填 说明
context Context 必填 调用接口的上下文
sessionId String 必填 上面2.1的接口调用之后,从回调函数返回的session id
packageName String 必填 待更新的应用包名
targetVersionCode int 必填 目标版本version code
targetVersionName String 必填 目标版本version name
result int 必填 安装结果
errMsg String 必填 安装失败的error message
  • 返回值: 无
  • 说明:
    • 由调用者,将应用的安装结果通知给fota sdk。
    • 上面的result定义:
宏定义 含义
STATUS_INSTALLSUCCESS 0 安装成功
STATUS_VERYFYFAIL 110 安装失败,更新包校验失败,详情查看errMsg
STATUS_INSTALLERROR 113 安装失败,安装应用失败,详情查看errMsg

3. 系统升级接口

  • 包名:com.aliyun.aicc.fota.sdk.aidl
  • 类名:IOsUpdateService

1. 初始化:

  1. // 系统升级是以service方式实现的,对外提供aidl的接口。
  2. // 通过如下方式,获取系统升级service的实例
  3. mService = IOsUpdateService.Stub.asInterface(arg1);

下面的接口,都是系统升级service的方法,需要通过mService的实例进行调用。

2. 查询相关的接口2.1 查询新版本

  • 接口名称: public synchronized void checkUpdateXml(int trrigerType)
  • 参数说明:
入参 类型 是否必填 说明
trrigerType int 必填 发起查询的类型
  • 返回值: 无
  • 说明:
    • 调用上面的查询接口,发起查询之后,通过所注册的listener的onGotXml()方法,取得新版本信息。
    • 入参发起查询的类型,取如下值:
      1. OsUpdateServiceManager类的如下类型:
      2. public enum OsCheckTriggerType {
      3. manual_button, manual_notification_bar, manual_pc_helper, auto_push, auto_network_connected, auto_alarm_timeout
      4. };

2.2 设置自动查询时间间隔

  • 接口名称: public boolean setAutoTimerCheckInterval(long intervalMilliSecond)
  • 参数说明:
入参 类型 是否必填 说明
intervalMilliSecond long 必填 自动轮询的时间间隔,单位是毫秒,默认值是24小时
  • 返回值: true:设置成功 false:设置失败
  • 说明:
    • 设置自动轮询的时间间隔,单位是毫秒,默认值是24小时
    • 做了这个设置之后,自动打开“自动轮询”的功能

2.3 关闭自动查询

  • 接口名称: public boolean disableAutoTimerCheck()
  • 参数说明: 无
  • 返回值: true:设置成功 false:设置失败
  • 说明:
    • 关闭自动轮询的功能
    • 默认为开启,默认自动轮询的时间间隔为24小时(距离上次查询成功的时间间隔)

3. 下载更新包

  • 接口名称: public synchronized void download(int mode)
  • 参数说明:
入参 类型 是否必填 说明
mode int 必填 下载模式
  • 返回值: 无
  • 说明: 查到版本之后,调用该接口进行下载。
  • 入参取如下值:
    • OsUpdateServiceManager.DOWNLOAD_LOCAL

4. 自动查询发现新版本后,是否自动开始下载

  • 自动查询包括:
    • 收到push后发起的查询
    • 自动定时查询
    • 网络断开再连接之后的查询
  • 上述情况下发起的自动查询,发现新版本后,将根据如下接口设置的开关状态,决定是否开始自动下载。
  • 注意:由用户在UI上手动发起的查询,发现新版本后,需要UI代码中,主动调用mService.download(OsUpdateServiceManager.DOWNLOAD_LOCAL),才开始下载。

  • 接口名称: public void setAutoDownloadUnderWiFi(boolean isAutoDownload)

  • 参数说明: true:自动下载;false:不自动下载
  • 返回值: 无

  • 接口名称: public void setAutoDownloadUnderMobile(boolean isAutoDownload)

  • 参数说明: true:自动下载;false:不自动下载
  • 返回值: 无

5. 升级

  • 接口名称: public synchronized void restartInstall()
  • 参数说明: 无
  • 返回值: 无
  • 说明: 重启系统,进入recovery模式做升级。

6. 代码示例

  • 首先需要绑定osupdate service,如何绑定,请参考接入指南。
  • 下面的mService,就是所绑定的osupdate service的实例。
  1. 查询:
  2. mService.checkUpdateXml(OsCheckTriggerType.manual_button.ordinal());
  3. 下载:
  4. mService.download(OsUpdateServiceManager.DOWNLOAD_LOCAL);
  5. // wifi和以太网络下,是否自动下载
  6. mService.setAutoDownloadUnderWiFi(true)
  7. // 移动网络下,是否自动下载
  8. mService.setAutoDownloadUnderMobile(true)
  9. // 上面两个方法,如果指定入参为true,不需要主动调用下载接口,当查询到有新版本之后,就自动开始下载。
  10. // 如果指定为false,当查询到有新版本之后,只是返回新版本信息,并不自动开始下载。
  11. // 默认为true
  12. 升级:
  13. //重启之前需要检查是否可以进行重启升级
  14. int ret = mService.checkPreInstallStatus();
  15. if (ret == FotaDownloadServiceManager.ENV_OK) {
  16. //重启系统并升级
  17. mService.restartInstall();
  18. }