Godot 应用更新 SDK（版本 1.0.0）

概述

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

用户场景示例

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

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

连接到项目

请执行以下步骤进行连接。

从 GitFlic 上的 RuStore 官方仓库复制插件项目。
在您的 IDE 中打开 godot_plugin_libraries 文件夹中的 Android 项目。
将 godot-lib.xxx.yyy.template_release.aar 包放入 godot_plugin_libraries/libs 文件夹中，其中 xxx.yyy 是您所使用的 Godot Engine 版本的版本号。

提示

适用于您的 Godot Engine 版本的 godot-lib.xxx.yyy.template_release.aar 包可在 Sourceforge.net 上的开发者页面中找到。

使用 gradle assemble 命令执行项目构建。

构建成功后，godot_example/android/plugins 文件夹中将创建以下文件：

RuStoreGodotAppUpdate.gdap;
RuStoreGodotAppUpdate.aar;
RuStoreGodotCore.gdap；
RuStoreGodotCore.aar。

警告

请特别注意，插件库必须针对您的 Godot Engine 版本进行构建。

将 godot_example/android/plugins 文件夹的内容复制到 your_project/android/plugins 文件夹中。
在 Android 构建预设的插件列表中，勾选 Ru Store Godot App Update 和 Ru Store Godot Core 选项。

创建更新管理器

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

创建 RuStoreGodotAppUpdateManager 单例
var _appUpdate_client: RuStoreGodotAppUpdateManager = null

func _ready():
    _appUpdate_client = RuStoreGodotAppUpdateManager.get_instance();

检查更新可用性

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

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

在使用该方法之前，必须执行一次事件订阅：

on_get_app_update_info_success；
on_get_app_update_info_failure。

订阅事件
func _ready():
    # Инициализация _appUpdate_client
	
    _appUpdate_client.on_get_app_update_info_success.connect(_on_get_app_update_info_success)
    _appUpdate_client.on_get_app_update_info_failure.connect(_on_get_app_update_info_failure)
 
func _on_get_app_update_info_success(response: RuStoreAppUpdateInfo):
    pass
 
func _on_get_app_update_info_failure(error: RuStoreError):
    pass

调用 get_app_update_info 方法
_appUpdate_client.get_app_update_info()

回调函数 (callback) on_get_app_update_info_success 返回包含更新必要性信息的对象。请提前请求信息，以便在用户方便的时间点无延迟地启动更新下载。

RuStoreAppUpdateInfo 类
class_name RuStoreAppUpdateInfo extends Object

    var updateAvailability: ERuStoreUpdateAvailability.Item
    var installStatus: ERuStoreInstallStatus.Item
    var availableVersionCode: int

    func _init(json: String = ""):
        if json == "":
            updateAvailability = ERuStoreUpdateAvailability.Item.UNKNOWN
            installStatus = ERuStoreInstallStatus.Item.UNKNOWN
            availableVersionCode = 0
        else:
            var obj = JSON.parse_string(json)
            updateAvailability = int(obj["updateAvailability"])
            installStatus = int(obj["installStatus"])
            availableVersionCode = int(obj["availableVersionCode"])

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 值时，才能启动更新下载。

回调函数 (callback) on_get_app_update_info_failure 返回包含错误信息的对象。错误结构请参阅错误处理章节。

下载并安装更新

使用监听器

在确认更新可用 (RuStoreAppUpdateInfo) 后，您可以获取更新的下载状态。为此，需要订阅 on_state_updated 事件，并调用 register_listener 方法来启动下载状态监听器。

检查更新下载状态

对 on_state_updated 事件的订阅仅执行一次。通过 register_listener 方法激活对下载过程的监听。

启动监听器
func _ready():
    # Инициализация _appUpdate_client

    _appUpdate_client.on_state_updated.connect(_on_state_updated)
    _appUpdate_client.register_listener()
	
func _on_state_updated(installState: RuStoreInstallState):
    pass

回调函数 (callback) on_state_updated 返回一个 RuStoreInstallState 对象，其中包含更新过程进度的信息。

RuStoreInstallState 类
class_name RuStoreInstallState extends Object

    var bytesDownloaded: int
    var totalBytesToDownload: int
    var percentDownloaded: float
    var installStatus: ERuStoreInstallStatus.Item
    var installErrorCode: ERuStoreInstallErrorCode.Item

    func _init(json: String = ""):
        if json == "":
            bytesDownloaded = 0
            totalBytesToDownload = 0
            percentDownloaded = 0
            installStatus = ERuStoreInstallStatus.Item.UNKNOWN
            installErrorCode = ERuStoreInstallErrorCode.Item.ERROR_UNKNOWN
        else:
            var obj = JSON.parse_string(json)
            bytesDownloaded = int(obj["bytesDownloaded"])
            totalBytesToDownload = int(obj["totalBytesToDownload"])
            installStatus = int(obj["installStatus"])
            installErrorCode = int(obj["installErrorCode"])
            if totalBytesToDownload > 0:
                percentDownloaded = float(bytesDownloaded) / totalBytesToDownload * 100
            else:
                percentDownloaded = 0
            if installStatus == ERuStoreInstallStatus.Item.DOWNLOADED:
                percentDownloaded = 100

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 — 需要下载的字节总数;
packageName — 更新的包名;
installErrorCode — 下载期间的错误代码。错误代码在错误处理章节中有所描述。

删除监听器

如果不再需要监听器，请使用 unregisterListener 方法删除该监听器。

调用 unregister_listener 方法
_appUpdate_client.unregister_listener()

启动更新下载

延迟更新

延迟更新场景描述

使用 RuStore UI 进行更新

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

启动更新流程

在使用启动更新流程的方法之前，必须先执行一次事件订阅：

on_start_update_flow_success;
on_start_update_flow_failure。

请使用 start_update_flow_delayed 方法来启动应用程序更新的下载。

信息

RuStoreAppUpdateInfo 对象在一次性使用后将失效。若要再次调用 start_update_flow_delayed 方法，请使用 get_app_update_info 方法重新请求 RuStoreAppUpdateInfo 对象。

请参阅检查更新部分。

订阅事件
func _ready():
    # Инициализация _appUpdate_client
    
    _appUpdate_client.on_start_update_flow_success.connect(_on_start_update_flow_success)
    _appUpdate_client.on_start_update_flow_failure.connect(_on_start_update_flow_failure)
    
func _on_start_update_flow_success(flowResult: ERuStoreUpdateFlowResult.Item):
    pass
    
func _on_start_update_flow_failure(error: RuStoreError):
    pass

调用 start_update_flow_delayed 方法
_appUpdate_client.start_update_flow_delayed()

回调函数 (callback) on_start_update_flow_success 返回一个 ERuStoreUpdateFlowResult.Item 枚举值，其中包含更新结果的信息：

RESULT_OK (int = -1) — 用户确认下载更新；
RESULT_CANCELED (int = 0) — 用户拒绝下载更新。

回调函数 (callback) on_start_update_flow_failure 返回一个包含错误信息的 RuStoreError 对象。 RuStoreError 错误结构在错误处理章节中有所描述。

在 RuStoreInstallState 对象的 installStatus 字段收到 ERuStoreUpdateFlowResult.Item.DOWNLOADED 状态后，必须调用更新安装方法。

强制更新

强制更新场景描述

使用 RuStore UI 进行更新

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

警告

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

启动更新流程

在从 get_appupdateinfo 收到成功响应后，可以使用 check_is_immediate_update_allowed 方法检查强制更新的可用性。

调用 check_is_immediate_update_allowed 方法
# Инициализация _appUpdate_client

var isAvailable: bool = _appUpdate_client.check_is_immediate_update_allowed()

true — 可用强制更新。
false — 不可用强制更新。

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

在使用启动更新流程的方法之前，必须先执行一次事件订阅：

on_start_update_flow_success;
on_start_update_flow_failure。

请使用 start_update_flow_immediate 方法来启动应用程序更新的下载。

信息

RuStoreAppUpdateInfo 对象在一次性使用后将失效。若要再次调用 start_update_flow_immediate 方法，请使用 get_app_update_info 方法重新请求 RuStoreAppUpdateInfo 对象。

订阅事件
func _ready():
    # Инициализация _appUpdate_client
    
    _appUpdate_client.on_start_update_flow_success.connect(_on_start_update_flow_success)
    _appUpdate_client.on_start_update_flow_failure.connect(_on_start_update_flow_failure)
    
func _on_start_update_flow_success(flowResult: ERuStoreUpdateFlowResult.Item):
    pass
    
func _on_start_update_flow_failure(error: RuStoreError):
    pass

调用 start_update_flow_immediate 方法
_appUpdate_client.start_update_flow_immediate()

回调函数 (callback) on_start_update_flow_success 返回一个 ERuStoreUpdateFlowResult.Item 枚举值，其中包含更新结果的信息：

RESULT_OK (int = -1) — 更新已完成。由于应用程序在更新时会终止；
RESULT_CANCELED (int = 0) — 用户中断了流程或发生了错误。收到此代码时，建议关闭应用程序。
ACTIVITY_NOT_FOUND (int = 2) — 未安装 RuStore，或者安装的版本不支持强制更新 (RuStore versionCode < 191)。

回调函数 (callback) on_start_update_flow_failure 返回一个包含错误信息的 RuStoreError 对象。 RuStoreError 错误结构在错误处理章节中有所描述。

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

静默更新

静默更新场景描述

RuStore 无 UI 更新

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

启动更新流程

在使用启动更新流程的方法之前，必须先执行一次事件订阅：

on_start_update_flow_success;
on_start_update_flow_failure。

请使用 start_update_flow_silent 方法来启动应用程序更新的下载。

信息

RuStoreAppUpdateInfo 对象在一次性使用后将失效。如需再次调用 start_update_flow_silent 方法，请使用 get_app_update_info 方法重新请求 RuStoreAppUpdateInfo 对象。

请参阅检查更新部分。

订阅事件
func _ready():
    # Инициализация _appUpdate_client
    
    _appUpdate_client.on_start_update_flow_success.connect(_on_start_update_flow_success)
    _appUpdate_client.on_start_update_flow_failure.connect(_on_start_update_flow_failure)
    
func _on_start_update_flow_success(flowResult: ERuStoreUpdateFlowResult.Item):
    pass
    
func _on_start_update_flow_failure(error: RuStoreError):
    pass

调用 start_update_flow_silent 方法
_appUpdate_client.start_update_flow_silent()

回调函数 (callback) on_start_update_flow_success 返回一个 ERuStoreUpdateFlowResult.Item 枚举值，其中包含更新结果的信息：

RESULT_OK (int = -1) — 更新下载任务已注册。

回调函数 (callback) on_start_update_flow_failure 返回一个包含错误信息的 RuStoreError 对象。 RuStoreError 错误结构在错误处理章节中有所描述。

在 RuStoreInstallState 对象的 installStatus 字段收到 ERuStoreUpdateFlowResult.Item.DOWNLOADED 状态后，请调用更新安装方法。

提示

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

安装更新

提示

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

在更新文件下载完成后，您可以启动更新安装。请使用 complete_update 方法来启动更新安装。在使用该方法之前，需要执行一次对以下事件的订阅。

on_complete_update_failure。

订阅事件
func _ready():
    # Инициализация _appUpdate_client
	
    _appUpdate_client.on_complete_update_failure.connect(_on_complete_update_failure)
	
func _on_complete_update_failure(error: RuStoreError):
    pass

调用 complete_update 方法
_appUpdate_client.complete_update()

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

回调函数 on_complete_update_failure 将返回一个 RuStoreError 对象，其 error 参数中包含错误信息。 RuStoreError 错误结构在错误处理章节中有所描述。

错误处理

提示

在收到任何 *_failure 事件时，不建议自行向用户显示错误。显示错误可能会对用户体验产生负面影响。

RuStoreError 类
class_name RuStoreError extends Object

    var description: String

    func _init(json: String = ""):
        if json == "":
            description = ""
        else:
            var obj = JSON.parse_string(json)
            description = obj["detailMessage"]

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

概述​

用户场景示例​

连接到项目​

创建更新管理器​

检查更新可用性​

下载并安装更新​

使用监听器​

检查更新下载状态​

删除监听器​

启动更新下载​

延迟更新​

强制更新​

静默更新​

安装更新​

错误处理​

可能的错误​

概述

用户场景示例

连接到项目

创建更新管理器

检查更新可用性

下载并安装更新

使用监听器

检查更新下载状态

删除监听器

启动更新下载

延迟更新

强制更新

静默更新

安装更新

错误处理

可能的错误