鸿蒙系统应用市场更新功能详解与开发适配指南

功能概述

应用市场更新功能是华为应用市场服务（AppGallery Kit）面向开发者提供的一项开放能力，主要服务于已在应用市场上架的应用。该功能允许开发者在应用内部集成版本检测与更新提醒逻辑，帮助用户及时将应用升级到最新版本。

通过该功能，开发者无需自行搭建版本管理服务器、维护版本信息、处理下载跳转等复杂逻辑，只需调用应用市场更新服务提供的接口，即可完成以下核心操作：

• 检测当前设备上安装的应用版本是否低于应用市场在架版本。
• 如果存在新版本，调用系统升级对话框提示用户进行升级。
• 获取升级对话框的显示结果，便于开发者进行后续业务处理。

该功能有效提升了应用内更新提醒的便捷性和一致性，减少了用户因版本过旧而遇到的功能缺失或兼容性问题，同时也帮助开发者提高新版本的分发效率。

适用场景

应用市场更新功能适用于以下两类主要场景：

应用启动自动检测

当应用启动完成后，开发者可以在应用初始化阶段调用检查更新接口，查询当前应用是否有可更新的版本。如果存在新版本，可进一步调用显示升级对话框接口，提醒用户更新。

这种场景常见于对版本及时性要求较高的应用，例如安全类、金融类、即时通讯类应用。在用户打开应用时自动检测更新，可以在第一时间引导用户升级，避免用户因版本过旧而无法使用关键功能或存在安全风险。

用户主动检查更新

开发者可以在应用的"设置"、"关于"或"帮助"页面提供"检查更新"入口。用户点击该入口后，应用调用检查更新接口，并根据返回结果决定是否弹出升级对话框。

这种场景给予了用户更多的自主权，适合不希望频繁打扰用户的工具类、内容类应用。用户在有需要时主动触发检查，体验更加友好。

无论是自动检测还是用户主动触发，核心流程一致：先检查，后提醒。开发者可以根据自身产品的交互设计，灵活选择触发时机。

业务流程

应用市场更新功能的整体业务流程可以概括为以下四个步骤：

1. 应用调用检查更新接口

   应用通过 checkAppUpdate 接口向升级服务发起请求，传入当前 UIAbility 的上下文信息。

2. 升级服务 API 返回是否有新版本

   升级服务根据应用包名、版本号、签名信息等条件进行判断，返回 CheckUpdateResult 结果对象。其中 updateAvailable 属性表示是否存在可更新版本。

3. 应用调用显示升级对话框接口

   如果检查结果表明存在新版本，应用可以调用 showUpdateDialog 接口，请求系统弹出升级对话框。

4. 升级服务 API 向应用返回显示结果

   系统根据当前状态展示升级对话框，并将显示结果以 ShowUpdateResultCode 形式返回给应用。开发者可据此判断对话框是否成功展示以及用户后续操作。

流程示意如下：

应用 -> checkAppUpdate -> 升级服务API
应用 <- 返回是否有新版本 <- 升级服务API
应用 -> showUpdateDialog -> 升级服务API
应用 <- 返回显示结果 <- 升级服务API

该流程清晰简洁，开发者只需关注接口调用和结果处理即可，无需深入理解升级服务内部实现。

约束与限制

在使用应用市场更新功能前，开发者需要充分了解以下约束与限制，以确保功能能够正常适配并稳定运行。

设备支持

设备类型	支持情况	备注
Phone	支持	从初始版本起支持
Tablet	支持	从初始版本起支持
PC / 2in1	支持	从初始版本起支持
TV	支持	从 5.1.1(19) 版本开始新增支持
Wearable	支持	从 6.0.0(20) 版本开始新增支持

开发者需要根据应用的目标设备类型确认所使用的 API 版本是否满足要求。对于 TV 和 Wearable 设备，需要确保运行环境版本不低于上述指定版本。如果应用需要同时覆盖多种设备类型，建议在代码中进行设备类型判断或版本判断，避免在不支持的设备上调用接口导致异常。

调试环境限制

应用市场更新功能 不支持模拟器。在模拟器中使用该服务时，系统会提示：

无法获取内容，请点击屏幕重试。

因此，开发者必须使用 真机 进行调试和验证。建议准备至少一台符合目标设备类型的真机，并确保真机系统版本满足要求。

应用上架要求

应用必须 已在应用市场上架，才能正常使用该功能。未上架的应用无法通过该服务获取版本更新信息。如果应用尚处于开发阶段或未完成上架流程，需要先完成上架，再进行更新功能的联调与验证。

版本检测条件

• 本地安装版本必须 低于 应用市场在架版本，才能检查到更新。如果本地版本等于或高于在架版本，则不会检测到更新。
• 本地安装版本必须与应用市场在架版本的 签名信息保持一致，否则无法正常检测。
• 暂不支持 邀请测试 和 公开测试 环境下的版本检测。

这些条件确保了更新检测的准确性和安全性，避免因签名不一致或测试环境干扰导致误判。

接口说明

应用市场更新服务提供两个主要接口，具体如下：

接口名	描述
checkAppUpdate(context: common.UIAbilityContext): Promise<CheckUpdateResult>	检查更新接口，用于检测当前是否有新版本。
showUpdateDialog(context: common.UIAbilityContext): Promise<ShowUpdateResultCode>	显示升级对话框接口，用于提示用户进行升级。

两个接口均接收一个 common.UIAbilityContext 类型的上下文参数，并返回一个 Promise 对象，便于开发者使用异步方式处理结果。

checkAppUpdate 接口

• 入参 ：context，类型为 common.UIAbilityContext，表示当前 UIAbility 的上下文。开发者需要通过 getUIContext().getHostContext() 等方式获取有效的上下文对象。
• 返回值 ：Promise<CheckUpdateResult>，异步返回检查结果对象。
• 结果说明 ：CheckUpdateResult 中包含 updateAvailable 等属性。当 updateAvailable 为 true 时，表示存在可更新版本；为 false 时，表示当前已是最新版本或不满足检测条件。开发者可根据该属性决定是否继续调用显示升级对话框接口。

调用示例已在前文开发步骤中给出，此处不再重复。

showUpdateDialog 接口

• 入参 ：context，类型为 common.UIAbilityContext，表示当前 UIAbility 的上下文。与 checkAppUpdate 接口的入参要求一致。
• 返回值 ：Promise<ShowUpdateResultCode>，异步返回显示结果码。
• 结果说明 ：ShowUpdateResultCode 表示升级对话框的显示结果。开发者可根据结果码判断对话框是否成功展示、用户是否进行了相关操作（如点击更新、取消等）。具体结果码含义可参考接口文档。

需要注意的是，通常应先调用 checkAppUpdate 确认存在新版本后，再调用 showUpdateDialog。如果在无新版本的情况下直接调用，可能会导致对话框无法展示或返回错误结果。

适配过程

适配应用市场更新功能需要从设备、版本、签名、调试环境、上架状态等多个维度进行准备和验证。以下是适配过程中需要注意的关键点。

设备适配

根据应用的目标设备类型，确认运行环境版本是否满足要求：

• 如果应用面向 Phone、Tablet、PC / 2in1 设备，可直接使用该功能，无需额外判断。
• 如果应用面向 TV 设备，需确保系统版本不低于 5.1.1(19)。
• 如果应用面向 Wearable 设备，需确保系统版本不低于 6.0.0(20)。

在集成前，建议开发者明确应用的目标设备范围，避免在不支持的设备上调用接口导致异常。如果应用需要覆盖多种设备类型，可以在代码中添加设备类型或系统版本判断逻辑，仅当满足条件时才调用更新相关接口。

版本适配

• 应用本地安装版本必须低于应用市场在架版本，才能检查到更新。因此，在开发阶段进行真机调试时，需要确保设备上安装的版本为旧版本，而应用市场已上架新版本。
• 版本号比较以应用市场的在架版本为准，开发者无需自行实现版本比较逻辑。应用市场更新服务会根据包名和签名信息自动匹配在架版本，并比较版本号高低。

签名一致性适配

本地安装版本与应用市场在架版本必须使用 相同的签名信息。如果签名不一致，即使版本号较低，也无法正常检测到更新。因此，在调试前需确认：

• 真机上安装的包与已上架包使用相同的签名证书。
• 如果使用调试签名或第三方签名，可能导致检测失败。

建议在适配阶段使用与正式发布完全一致的签名配置，避免因签名差异引起不必要的调试困难。

调试环境适配

由于应用市场更新功能不支持模拟器，开发者在适配过程中必须使用真机进行调试。建议准备一台或多台符合目标设备类型的真机，并确保真机已连接网络、已登录华为账号（如需要）且系统版本满足要求。

此外，真机上安装的应用版本应低于在架版本，且签名与在架版本一致，这样才能完整验证检查更新和显示对话框的全流程。

上架状态适配

应用必须已在应用市场上架。如果是新建应用或尚未上架，需要先完成上架流程，再进行更新功能的联调与验证。邀请测试和公开测试环境暂不支持该功能，因此测试时需使用正式上架版本作为"在架版本"。

开发步骤详解

下面分别介绍检测应用新版本和显示升级对话框的详细开发步骤，包含导入模块、构造参数、调用接口和结果处理。

检测应用新版本

导入模块

首先导入 updateManager 模块及相关公共模块：

import { updateManager } from '@kit.AppGalleryKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import type { common } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

其中：

• updateManager 是应用市场更新服务的核心模块，提供了 checkAppUpdate 和 showUpdateDialog 接口。
• hilog 用于日志输出，便于开发者调试和记录运行状态。
• common 类型用于声明 UIAbility 上下文。
• BusinessError 类型用于捕获和处理业务异常。

构造参数

checkAppUpdate 接口的入参为 common.UIAbilityContext 类型的 Context。可以通过 UIAbility 上下文获取：

let context: common.UIAbilityContext = this.getUIContext().getHostContext() as common.UIAbilityContext;

在实际开发中，请确保 this 指向当前 UIAbility 实例，且 getUIContext() 方法可用。

调用接口

调用 checkAppUpdate 方法检查应用版本是否有更新，并处理返回结果和异常：

try {
  updateManager.checkAppUpdate(context)
    .then((checkResult: updateManager.CheckUpdateResult) => {
      hilog.info(0, 'TAG', 'Succeeded in checking Result updateAvailable:' + checkResult.updateAvailable);
    }).catch((error: BusinessError) => {
      hilog.error(0, 'TAG', `checkAppUpdate onError.code is ${error.code}, message is ${error.message}`);
    });
} catch (error) {
  hilog.error(0, 'TAG', `checkAppUpdate onError.code is ${error.code}, message is ${error.message}`);
}

上述代码使用 try...catch 包裹接口调用，并在 Promise 的 then 和 catch 中分别处理成功和失败情况。日志中记录了 updateAvailable 的值和错误码、错误信息，便于排查问题。

结果处理

• 当 checkResult.updateAvailable 为 true 时，表示存在可更新版本，开发者可以根据业务需要决定是否弹出升级对话框。
• 当 checkResult.updateAvailable 为 false 时，表示当前已是最新版本，无需进一步操作。
• 在 catch 中捕获 BusinessError 异常，记录错误码和错误信息，便于定位问题原因。

显示升级对话框

导入模块

与检测更新相同，首先导入所需模块：

import { updateManager } from '@kit.AppGalleryKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import type { common } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

构造参数

showUpdateDialog 接口的入参同样为 common.UIAbilityContext 类型的 Context：

let context: common.UIAbilityContext = this.getUIContext().getHostContext() as common.UIAbilityContext;

调用接口

调用 showUpdateDialog 方法显示升级对话框：

try {
  updateManager.showUpdateDialog(context)
    .then((resultCode: updateManager.ShowUpdateResultCode) => {
      hilog.info(0, 'TAG', 'Succeeded in showing UpdateDialog resultCode:' + resultCode);
    })
    .catch((error: BusinessError) => {
      hilog.error(0, 'TAG', `showUpdateDialog onError.code is ${error.code}, message is ${error.message}`);
    });
} catch (error) {
  hilog.error(0, 'TAG', `showUpdateDialog onError.code is ${error.code}, message is ${error.message}`);
}

同样使用 try...catch 和 Promise 链处理成功与失败情况。

结果处理

• 成功时，resultCode 为 ShowUpdateResultCode 类型，表示对话框展示结果。开发者可根据具体业务逻辑记录日志或执行后续操作，例如统计更新提示的展示次数、用户点击更新后的跳转行为等。
• 失败时，在 catch 中捕获 BusinessError 异常，记录错误码和错误信息。

注意事项

1. 调用顺序

   通常先调用 checkAppUpdate 检查是否有新版本，只有确认存在新版本后再调用 showUpdateDialog 显示升级对话框。避免在无新版本时直接弹出对话框导致用户体验不佳或接口返回异常。

2. Context 有效性

   传入的 context 必须是有效的 common.UIAbilityContext，否则接口可能抛出异常或返回错误。建议在调用前对 context 进行非空判断。

3. 真机调试

   务必使用真机进行调试，不要在模拟器上测试该功能，以免出现"无法获取内容，请点击屏幕重试"的提示。同时确保真机系统版本满足设备支持要求。

4. 签名一致性

   确保本地安装版本与应用市场在架版本签名一致，否则无法正常检测到更新。在开发、测试和发布阶段尽量使用统一的签名配置。

5. 版本要求

   本地版本必须低于在架版本才能触发更新。若本地版本等于或高于在架版本，则不会检测到更新。因此，在调试时需要刻意安装旧版本应用。

6. 暂不支持测试环境

   邀请测试和公开测试环境暂不支持应用市场更新功能，需在正式上架后验证。如果应用正在参与测试，可能无法正常使用该功能。

7. 网络状态

   应用市场更新服务依赖网络通信，如果设备处于无网络或网络不稳定的环境，接口可能调用失败或返回错误。建议在代码中处理网络异常情况。

8. 用户体验

   避免过于频繁地弹出版本更新对话框，以免干扰用户正常使用。建议在合适的时机（如应用启动、用户主动触发）进行检测和提示。

总结

应用市场更新功能为开发者提供了便捷的版本检测与更新提醒能力，通过两个简单接口即可完成集成。适配过程中需重点关注设备支持范围、版本要求、签名一致性、真机调试以及应用上架状态等条件。只有在满足所有约束的前提下，应用才能正常检测到新版本并向用户展示升级对话框，从而提升用户的使用体验和应用活跃度。

该功能的接入成本低、流程清晰，能够有效帮助开发者提高新版本的分发效率，减少因版本过旧导致的用户流失和兼容性问题。建议开发者在应用内合理设计更新检测时机，充分利用该能力为用户提供及时、友好的升级提醒。