跳到主要内容

Unity 应用更新 SDK (版本 0.2.0)

概述​

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

用户场景示例​

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

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

img img img img

连接到项目​

如需连接，请下载 RuStore AppUpdate SDK 并将其导入到项目中 (Assets > Import Package > Custom Package)。 依赖项将通过 External Dependency Manager（已包含在 SDK 中）自动连接。

Minimum API level 的设置不能低于 24。 目前不支持应用程序代码混淆 (ProGuard/R8)，必须在项目设置中将其禁用 (File > Build Settings > Player Settings > Publishing Settings > Minify)。

创建更新管理器​

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

RuStoreAppUpdateManager.Instance.Init();

检查更新可用性​

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

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

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

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

RuStoreAppUpdateManager.Instance.GetAppUpdateInfo(
    onFailure: (error) => {
        // Handling error
    },
    onSuccess: (info) => {
        // Process update info
    }
);
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) — 等待中。

  • availableVersionCode — 更新版本的代码。

信息

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

下载并安装更新​

使用监听器​

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

检查更新下载状态​

请使用 RegisterListener() 方法。

RuStoreAppUpdateManager.Instance.RegisterListener(listener);

listener — 实现 IInstallStateUpdateListener 接口的类对象：

public interface InstallStateUpdateListener {
    public void OnStateUpdated(InstallState state);
}

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

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

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

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

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

请参考以下几种情况。

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

删除监听器​

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

RuStoreAppUpdateManager.Instance.UnregisterListener(listener);

启动更新下载​

延迟更新​

延迟更新场景描述

使用 RuStore UI 进行更新

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

启动更新流程

如需启动应用更新下载，请调用 StartUpdateFlow() 方法。

信息

AppUpdateInfo 对象在一次使用后将失效。 如需再次调用 StartUpdateFlow() 方法，请再次使用 GetAppUpdateInfo() 方法请求 AppUpdateInfo。

RuStoreAppUpdateManager.Instance.StartUpdateFlow(
    onFailure: (error) => {
        // Handling error
    },
    onSuccess: (resultCode) => {
        // Handle flow result
    }
);

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

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

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

该方法可能会返回错误。

信息

可能的错误列表

安装更新​

在完成更新 APK 文件的下载后，您可以启动更新安装。 请调用 CompleteUpdate() 方法来启动更新安装。

RuStoreAppUpdateManager.Instance.CompleteUpdate(
    onFailure: (error) => {
        // Handling error
    }
);

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

错误处理​

提示

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

以下是错误结构。

public class RuStoreError {
    public string name;
    public string description;
}

可能的错误​

  • 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.