10.5.3

概述

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

已修复

在 AGP 9+ 上使用 android.builtInKotlin=true 构建的问题（有条件地使用 Kotlin Gradle 插件并迁移到 DSL kotlin.compilerOptions）

实现示例

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

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

用户场景

延迟更新
强制更新
静默更新

SDK 正确运行的前提条件

RuStore In-app updates SDK 的运行需要满足以下条件。

已在 RuStore 控制台的“推送通知 > 项目”部分加载应用程序数据。
应用程序已通过审核（无需发布应用程序）。

重要

您的应用程序不同构建类型（debug、release 等）的签名和 package name 可能各不相同。在这种情况下，您必须在 RuStore 控制台的“推送通知 > 项目”部分为每种构建类型创建一个项目。

Android 操作系统版本为 7.0 或更高。
用户设备上的 RuStore 版本为最新版本。
用户已在 RuStore 中登录。
RuStore 应用程序已获得安装应用程序的权限。

连接到项目

请执行以下命令将软件包连接到项目。

flutter pub add flutter_rustore_update

该命令将在 pubspec.yaml 文件中添加一行。

pubspec.yaml
dependencies:
  flutter_rustore_update: ^10.5.3

检查可用更新

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

用户设备上已安装最新版本的 RuStore。
用户和应用在 RuStore 中均未被封禁。
。
RuStore 应用程序已获准安装其他应用。
用户已在 RuStore 中登录。

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

RustoreUpdateClient.info().then((info) {
    print(info);
}).catchError((err) {
    print(err);
});

info 对象包含用于确定更新可用性的一组必要参数。

updateAvailability — 更新可用性：
- UPDATE_AVAILABILITY_UNKNOWN (int == 0) — 默认；
- UPDATE_AVAILABILITY_NOT_AVAILABLE (int == 1) — 无需更新；
- UPDATE_AVAILABILITY_AVAILABLE (int == 2) — 需要下载更新，或更新已下载到用户设备上；
- UPDATE_AVAILABILITY_IN_PROGRESS (int == 3) — 更新正在下载或安装已启动。
installStatus — 如果用户当前正在安装更新，则为更新的安装状态：
- INSTALL_STATUS_UNKNOWN (int == 0) — 默认值；
- INSTALL_STATUS_DOWNLOADED (int == 1) — 已下载；
- INSTALL_STATUS_DOWNLOADING (int == 2) — 正在下载；
- INSTALL_STATUS_FAILED (int == 3) — 错误；
- INSTALL_STATUS_INSTALLING (int == 4) — 正在安装；
- INSTALL_STATUS_PENDING (int == 5) — 等待中。

该软件包还为这些值提供了类型安全 (type-safe) 的表示形式：

info.updateAvailabilityValue — UpdateAvailability 类型的值；
info.installStatusValue — InstallStatus 类型的值。

示例：

RustoreUpdateClient.info().then((info) {
  if (info.updateAvailabilityValue == UpdateAvailability.available) {
    print('Обновление доступно');
  }
});

提示

只有在 updateAvailability 字段包含 UPDATE_AVAILABILITY_AVAILABLE 值时，才能启动更新下载。

注意

为了向后兼容，软件包中保留了旧版的 UPDATE_AILABILITY_* 常量。对于新的集成，建议使用 UPDATE_AVAILABILITY_*。

下载和安装更新

跟踪更新状态

在确认更新可用 (AppUpdateInfo) 后，您可以请求更新的下载状态。为此，请订阅更新状态流。

检查更新下载状态

提示

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

请使用 RustoreUpdateClient.stateStream。

import 'dart:async';

late final StreamSubscription<RequestResponse> updateSubscription;

@override
void initState() {
  super.initState();

  updateSubscription = RustoreUpdateClient.stateStream.listen((state) {
    switch (state.installStatusValue) {
      case InstallStatus.downloaded:
        // Обновление готово к установке
        break;
      case InstallStatus.downloading:
        // Здесь можно отобразить прогресс скачивания
        print('progress: ${state.downloadProgress}');
        break;
      case InstallStatus.failed:
        print('err ${state.installError.description}');
        break;
      default:
        break;
    }
  });
}

@override
void dispose() {
  updateSubscription.cancel();
  super.dispose();
}

stateStream 返回一个 broadcast Stream<RequestResponse>，适用于安全地处理屏幕或服务的生命周期。在通过 cancel() 取消订阅后，事件流将停止发送到应用程序。

为了向后兼容，listener(callback) 方法仍然保留，但对于新的集成，建议使用 stateStream。

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

installStatus — 如果用户当前正在安装更新，则为更新的安装状态：
- INSTALL_STATUS_UNKNOWN (int == 0) — 默认值；
- INSTALL_STATUS_DOWNLOADED (int == 1) — 已下载；
- INSTALL_STATUS_DOWNLOADING (int == 2) — 正在下载；
- INSTALL_STATUS_FAILED (int == 3) — 错误；
- INSTALL_STATUS_INSTALLING (int == 4) — 正在安装；
- INSTALL_STATUS_PENDING (int == 5) — 等待中。
bytesDownloaded — 已下载的字节数;
totalBytesToDownload — 需要下载的字节总数;
installErrorCode — 下载期间的错误代码。错误代码在错误处理章节中有所描述。

该包还提供了额外的属性：

state.installStatusValue — InstallStatus 类型的值；
state.installError — RustoreUpdateError 类型的值；
state.downloadProgress — 如果已知总下载大小，则为 0.0 到 1.0 范围内的下载进度。

下载进度显示示例：

RustoreUpdateClient.stateStream.listen((state) {
  if (state.installStatusValue == InstallStatus.downloading) {
    print('Downloaded: ${state.bytesDownloaded}/${state.totalBytesToDownload}');
    print('Progress: ${state.downloadProgress}');
  }
});

请注意

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

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

请参考以下几种情况。

用户开始下载更新但取消了下载 —— 在这种情况下：
- updateAvailability — UPDATE_AVAILABILITY_AVAILABLE (2)；
- installStatus — �C0� (0)。
用户下载了更新文件但没有安装 —— 在这种情况下：
- updateAvailability — UPDATE_AVAILABILITY_AVAILABLE (2)；
- �C1� — INSTALL_STATUS_DOWNLOADED (1)。

注意

RustoreUpdateClient.listener(callback) 方法为了向后兼容而予以保留。对于新的集成，建议使用 RustoreUpdateClient.stateStream。

开始下载更新

延迟更新

启动更新流程

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

信息

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

RustoreUpdateClient.download().then((value) {
    print("download code ${value.code}");
    if (value.code == ACTIVITY_RESULT_CANCELED) {
        // Пользователь отказался от скачивания
    }
}).catchError((err) {
    print("download err ${err}");
   }
);

如果用户确认下载更新，则 resultCode = ACTIVITY_RESULT_OK；如果用户拒绝，则 resultCode = ACTIVITY_RESULT_CANCELED。

在收到 INSTALL_STATUS_DOWNLOADED 状态或 InstallStatus.downloaded 值后，您可以调用安装更新的方法。

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

该方法可能会返回错误。

信息

可能的错误列表

强制更新

启动更新流程

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

RustoreUpdateClient.immediate().then((value) {
    print("silent code ${value.code}");
}).catchError((err) {
    print("immediate err ${err}");
   }
);

resultCode (Int)：

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

throwable — 更新场景启动错误。

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

静默更新

启动更新流程

请调用 silent() 方法来启动应用程序的静默更新下载。

RustoreUpdateClient.silent().then((value) {
    print("silent code ${value.code}");
}).catchError((err) {
    print("silent err ${err}");
   }
);

当调用 code = ACTIVITY_RESULT_OK 的 then 时，将注册一个更新下载任务。

在此场景中，只能调用带有 ACTIVITY_RESULT_OK 的 then 或 catchError。

调用该方法后，您可以通过 RustoreUpdateClient.stateStream 跟踪更新的下载状态。

在收到 INSTALL_STATUS_DOWNLOADED 状态或 InstallStatus.downloaded 值后，您可以调用安装更新的方法。建议通知用户更新已准备好安装。

提示

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

安装更新

在更新文件下载完成后，您可以启动更新安装。更新通过 Android 原生工具进行。请使用以下方法启动更新安装：

completeUpdateFlexible() — 更新并重启应用程序；
completeUpdateSilent() — 更新并关闭应用程序。

提示

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

灵活更新完成

调用 completeUpdateFlexible 方法
RustoreUpdateClient.completeUpdateFlexible().catchError((err) {
    print("completeUpdateFlexible err ${err}");
});

来自 RuStore 的 UI 更新：

用户将看到更新完成的 UI 对话框。
更新成功后，应用程序将重新启动。

静默更新完成

调用 completeUpdateSilent 方法
RustoreUpdateClient.completeUpdateSilent().catchError((err) {
    print("completeUpdateSilent err ${err}");
});

来自 RuStore 的无 UI 更新：

系统不会显示更新完成的 UI 对话框。
如果更新成功，应用程序将会关闭。

错误处理

插件中的错误仍然可以通过 const.dart 文件中声明的常量访问。

此外，该包还提供了类型安全的错误表示：

RustoreUpdateError;
state.installError;
state.installError.description。

下载错误处理示例：

RustoreUpdateClient.stateStream.listen((state) {
  if (state.installStatusValue == InstallStatus.failed) {
    print(state.installError.description);
  }
});

注意

RustoreUpdateClient.listener(callback) 方法为了向后兼容而予以保留。对于新的集成，建议使用 RustoreUpdateClient.stateStream。

可能的错误列表

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 时出现未知错误。

应用更新的依赖项列表

ru.rustore.sdk:core:0.1.10 — GNU Lesser General Public License v3.0；
ru.rustore.sdk:analytics:0.1.5 — GNU Lesser General Public License v3.0；
org.jetbrains.kotlin:kotlin-stdlib-jdk8:1.7.20 — The Apache Software License, Version 2.0；
org.jetbrains.kotlinx:kotlinx-coroutines-android:1.6.4 — The Apache Software License, Version 2.0；
androidx.core:core-ktx:1.9.0 — Apache License, Version 2.0;
androidx.appcompat:appcompat:1.5.1 — Apache License, Version 2.0;
androidx.activity:activity:1.5.1 — Apache License, Version 2.0.

概述​

已修复​

实现示例​

用户场景​

SDK 正确运行的前提条件​

连接到项目​

检查可用更新​

下载和安装更新​

跟踪更新状态​

检查更新下载状态​

开始下载更新​

延迟更新​

强制更新​

静默更新​

安装更新​

灵活更新完成​

静默更新完成​

错误处理​

可能的错误列表​

应用更新的依赖项列表​

概述

已修复

实现示例

用户场景

SDK 正确运行的前提条件

连接到项目

检查可用更新

下载和安装更新

跟踪更新状态

检查更新下载状态

开始下载更新

延迟更新

强制更新

静默更新

安装更新

灵活更新完成

静默更新完成

错误处理

可能的错误列表

应用更新的依赖项列表