跳到主要内容

SDK Kotlin/Java 应用更新 (版本 1.0.1)

概述​

RuStore In-app updates SDK 可确保用户设备上的应用保持最新版本。这有助于用户发现更新，体验性能提升并获得错误修复的结果。

用户场景示例​

请使用 RuStore In-app updates SDK 来实现不同的更新方式。 目前支持：延迟更新、静默更新（不使用 RuStore UI）和强制更新。

请参考示例应用程序，以了解如何正确集成更新 SDK。

img img img img

连接到项目​

连接仓库。

build.gradle
repositories {
    maven {
        url = uri("https://nexus-external.rustore.ru/repository/maven-rustore-exposed")
    }
}

要连接 SDK 依赖项，需要将以下代码片段添加到您的配置文件中。

build.gradle
dependencies {
    implementation("ru.rustore.sdk:appupdate:1.0.1")
}

创建更新管理器​

在调用库方法之前，需要创建更新管理器。

val updateManager = RuStoreAppUpdateManagerFactory.create(context)

检查更新可用性​

在请求更新之前，请检查您的应用程序是否有可用更新。 要检查更新可用性，请调用 getAppUpdateInfo() 方法。 调用此方法时将检查以下条件。

  • 用户设备上已安装最新版本的 RuStore。

  • 用户和应用在 RuStore 中均未被封禁。

  • 用户已在 RuStore 中登录。
该方法的响应将是一个 AppUpdateInfo 对象，其中包含关于更新必要性的信息。 请提前请求此对象并将其缓存，以便在用户方便的时间点无延迟地请求用户启动更新下载。 

ruStoreAppUpdateManager
    .getAppUpdateInfo()
    .addOnSuccessListener { appUpdateInfo ->
        if (appUpdateInfo.updateAvailability == UpdateAvailability.UPDATE_AVAILABLE) {
            // 更新可用（可在此处注册 listener 并开始下载）
        }
    }
    .addOnFailureListener { throwable ->
        Log.e(TAG, "getAppUpdateInfo error", throwable)
    }
AppUpdateInfo 对象包含用于确定更新可用性的一组必要参数。

  • updateAvailability — 更新可用性：

    • UNKNOWN (int == 0) — 默认值；
    • UPDATE_NOT_AVAILABLE (int == 1) — 无需更新；
    • UPDATE_AVAILABLE (int == 2) — 需要下载更新，或更新已下载到用户设备上；
    • DEVELOPER_TRIGGERED_UPDATE_IN_PROGRESS (int == 3) — 更新正在下载或安装已启动。

  • installStatus — 如果用户当前正在安装更新，则为更新的安装状态：

    • UNKNOWN (int == 0) — 默认值；
    • DOWNLOADED (int == 1) — 已下载；
    • DOWNLOADING (int == 2) — 正在下载；
    • FAILED (int == 3) — 错误；
    • PENDING (int == 5) — 等待中。
信息

仅在 updateAvailability 字段包含 UPDATE_AVAILABLE 值时，才能启动更新下载。

下载并安装更新​

使用监听器​

在确认更新可用 (AppUpdateInfo) 后，您可以请求更新的下载状态 —— 为此，请启动更新下载状态监听器。

检查更新下载状态​

请使用 registerListener() 方法。

ruStoreAppUpdateManager.registerListener { state ->
    when (state.installStatus) {
        InstallStatus.DOWNLOADED -> {
            // Обновление готово к установке
        }
        InstallStatus.DOWNLOADING -> {
            val totalBytes = state.totalBytesToDownload
            val bytesDownloaded = state.bytesDownloaded
            // Здесь можно отобразить прогресс скачивания
        }
        InstallStatus.FAILED -> {
            Log.e(TAG, "Downloading error")
        }
    }
}

state 对象描述了当前的下载状态。 该对象的内容如下所示。

  • installStatus — 如果用户当前正在安装更新，则为更新的安装状态：

    • UNKNOWN (int == 0) — 默认值；
    • DOWNLOADED (int == 1) — 已下载；
    • DOWNLOADING (int == 2) — 正在下载；
    • FAILED (int == 3) — 错误；
    • PENDING (int == 5) — 等待中;
请注意

在更新 SDK 中，没有针对用户取消下载更新这种情况的特定状态。 如果用户在下载阶段中断了更新，installStatus 将返回初始状态 UNKNOWN (0) 并显示下载按钮。

如果用户已经下载了更新但取消了安装，则 installStatus 将返回 DOWNLOADED (1) 值。

请参考以下几种情况。

  • 用户开始下载更新但取消了下载 —— 在这种情况下：
    • updateAvailability 为 UPDATE_AVAILABLE (2)；
    • installStatus 为 UNKNOWN (0)。
  • 用户下载了更新文件但没有安装 —— 在这种情况下：
    • updateAvailability 为 UPDATE_AVAILABLE (2)；
    • installStatus 为 DOWNLOADED (1)。
  • bytesDownloaded — 已下载的字节数;
  • totalBytesToDownload — 需要下载的字节总数;
  • installErrorCode — 下载期间的错误代码。 错误代码在 错误处理 章节中有所描述。

删除监听器​

如果不再需要监听器，请使用 unregisterListener() 方法删除监听器，并将之前注册的监听器传递给该方法。

ruStoreAppUpdateManager.unregisterListener(listener)

启动更新下载​

延迟更新​

延迟更新场景描述

使用 RuStore UI 进行更新

img
  1. 将向用户显示 RuStore UI 对话框以确认更新。
  2. 点击更新按钮后，将显示确认安装更新的对话框。
  3. 安装完成后，应用程序将关闭。

启动更新流程

要启动应用程序更新的下载，请调用 startUpdateFlow() 方法。

信息

AppUpdateInfo 对象在一次使用后将失效。 若要再次调用 startUpdateFlow() 方法，请再次使用 getAppUpdateInfo() 方法请求 AppUpdateInfo。

ruStoreAppUpdateManager
    .startUpdateFlow(appUpdateInfo, AppUpdateOptions.Builder().build())
    .addOnSuccessListener { resultCode ->
        if (resultCode == Activity.RESULT_CANCELED) {
            // 用户拒绝下载
        }
    }
    .addOnFailureListener { throwable ->
        Log.e(TAG, "startUpdateFlow error", throwable)
    }

如果用户确认下载更新，则 resultCode = Activity.RESULT_OK；如果用户拒绝，则 resultCode = Activity.RESULT_CANCEL。

在收到 DOWNLOADED 状态后，您可以调用 completeUpdate() 方法来安装更新。

建议通知用户更新已准备好安装。

该方法可能会返回错误。

信息

可能的错误列表

强制更新​

强制更新场景描述

使用 RuStore UI 进行更新

img
  1. 用户将看到一个带有 RuStore UI 的全屏对话框，用于确认更新。 在安装更新之前，应用程序的使用将被锁定。
  2. 点击更新按钮后，将显示一个用于确认安装更新的对话框。
  3. 随后，点击安装按钮后，将出现一个关于安装新版本应用程序的全屏对话框。
  4. 安装完成后，应用程序将自动重启。
警告

如果 RuStore 版本大于或等于 1.37，应用程序将重启。 如果 RuStore 版本较低，应用程序将关闭以安装更新，且在更新结束后不会重新打开。

启动更新流程

在获取 AppUpdateInfo 后，您可以检查强制更新是否可用。

if (appUpdateInfo.isUpdateTypeAllowed(IMMEDIATE)) {
    // 强制更新可用
}

建议使用 isUpdateTypeAllowed 函数的结果来决定是否启动强制更新，但该结果不会影响启动流程的可能性。 启动更新场景的必要性可以根据您的内部逻辑来决定。

请使用 startUpdateFlow() 方法来启动更新流程。

ruStoreAppUpdateManager
    .startUpdateFlow(appUpdateInfo, AppUpdateOptions.Builder().appUpdateType(IMMEDIATE).build())
    .addOnSuccessListener { resultCode ->
 
    }
    .addOnFailureListener { throwable ->
 
    }

resultCode (Int)：

  • Activity.RESULT_OK (-1) — 更新已完成，可能无法获取该代码，例如 k. 应用程序在更新时终止。
  • Activity.RESULT_CANCELED (0) — 用户中断了流程，或发生了错误。 在收到此代码时，应终止应用程序的运行。
  • ActivityResult.ACTIVITY_NOT_FOUND (2) — 未安装 RuStore，或安装的版本不支持强制更新 (RuStore versionCode < 191)。

throwable — 更新场景启动错误。

更新成功后无需进一步操作。

静默更新​

静默更新场景描述

RuStore 无 UI 更新

img
  1. 系统将向用户显示确认安装更新的对话框（更新将在后台下载）。
  2. 安装完成后，应用程序将关闭。

启动更新流程

要启动应用程序更新下载，必须调用 startUpdateFlow() 方法，并传入通过 getAppUpdateInfo() 方法获取的 AppUpdateInfo 参数，同时将 AppUpdateOptions 中的更新类型设置为 SILENT。

ruStoreAppUpdateManager
    .startUpdateFlow(appUpdateInfo, AppUpdateOptions.Builder().appUpdateType(SILENT).build())
    .addOnSuccessListener { resultCode ->
 
    }
    .addOnFailureListener { throwable ->
 
    }

当 onSuccessListener 被调用且 resultCode = Activity.RESULT_OK 时，将注册一个更新下载任务。

在此场景中，仅能调用 resultCode = Activity.RESULT_OK 的 onSuccessListener 或 onFailureListener。

调用该方法后，您可以在监听器中跟踪更新的下载状态。

在收到 DOWNLOADED 状态后，您可以调用 completeUpdate() 方法来安装更新。 建议通知用户更新已准备好安装。

提示

对于静默更新，建议实现自定义界面。

安装更新​

请调用 completeUpdate() 方法来启动更新安装。

ruStoreAppUpdateManager
    .completeUpdate()
    .addOnFailureListener { throwable ->
        Log.e(TAG, "update error", throwable)
    }

更新通过 Android 原生工具进行。 如果更新成功，应用程序将会关闭。

错误处理​

提示

如果您收到 onFailure 响应，不建议自行向用户显示错误。 显示错误可能会对用户体验产生负面影响。

可能的错误​

  • RuStoreNotInstalledException — 用户设备上未安装 RuStore；
  • RuStoreOutdatedException — 用户设备上安装的 RuStore 版本不支持此 SDK；
  • RuStoreUserUnauthorizedException — 用户未在 RuStore 中登录；
  • RuStoreException — RuStore 基础错误，其他错误均继承自此类;
  • RuStoreInstallException(public val code: Int) — 下载和安装错误.
    • ERROR_UNKNOWN(Int = 4001) — 未知错误。
    • ERROR_DOWNLOAD(Int = 4002) — 下载时出错。
    • ERROR_BLOCKED(Int = 4003) — 安装被系统拦截。
    • ERROR_INVALID_APK(Int = 4004) — 更新 APK 文件无效。
    • ERROR_CONFLICT(Int = 4005) — 与当前应用版本冲突。
    • ERROR_STORAGE(Int = 4006) — 设备存储空间不足。
    • ERROR_INCOMPATIBLE(Int = 4007) — 与设备不兼容。
    • ERROR_APP_NOT_OWNED(Int = 4008) — 未购买该应用。
    • ERROR_INTERNAL_ERROR(Int = 4009) — 内部错误。
    • ERROR_ABORTED(Int = 4010) — 用户取消了更新安装。
    • ERROR_APK_NOT_FOUND(Int = 4011) — 未找到用于启动安装的 APK 文件。
    • ERROR_EXTERNAL_SOURCE_DENIED(Int = 4012) — 禁止启动更新。 例如，在第一个方法中返回了更新不可用的响应，但用户调用了第二个方法。
    • ERROR_ACTIVITY_SEND_INTENT(Int = 9901) — 发送打开 Activity 的 Intent 时出错。
    • ERROR_ACTIVITY_UNKNOWN(Int = 9902) — 打开 Activity 时出现未知错误。