Scan Kit 与扫码直达概述

Scan Kit（统一扫码服务）是 HarmonyOS 提供的软硬协同的系统级扫码服务。该服务创新性地推出了更简单的“扫码直达”接入能力，开发者只需完成少量接入工作，无需在应用中开发专门的扫码模块，即可通过系统级扫码入口实现从扫码到应用内服务页的跳转。

Scan Kit 应用了多项计算机视觉技术和 AI 算法技术，不仅实现了远距离自动扫码，还针对多种复杂扫码场景（如暗光、污损、模糊、小角度、曲面码等）做了识别优化，提升扫码成功率与用户体验。

扫码直达是指：用户可通过控制中心等系统级的常驻入口，扫描开发者应用的二维码、条形码并跳转到开发者应用对应服务页，实现一步直达的体验。该能力为开发者带来以下优势：

• 更浅层的扫码入口和更便捷的“扫码直达”服务体验。
• HarmonyOS 强大的扫码能力。
• 更容易触达用户的全新渠道。

场景介绍

Scan Kit 提供了系统“扫码直达”、开发者应用内扫码等多种能力。优先接入“扫码直达”能力，通过少量的接入工作即可实现开发者应用服务的一步直达。

Scan Kit 支持的主要能力包括：

能力	说明
扫码直达（推荐）	用户通过控制中心等系统级常驻入口扫码，直接跳转到应用对应服务页。
默认界面扫码	提供系统级体验一致的扫码界面，包含相机预览流、相册扫码入口、暗光环境闪光灯开启提示，具备相机预授权，集成简单，适用于通用扫码场景。
自定义界面扫码	提供扫码能力并支持在指定控件上渲染相机预览流，需要开发者实现扫码界面，申请相机权限，适用于个性化定制场景。
图像识码	对图库中的码图或图像数据进行扫描识别。
码图生成	通过文本或字节数组生成码图。

说明： Scan Kit 支持十三种全球主流的码类型识别和生成以及 MULTIFUNCTIONAL CODE 的识别。目前已支持的码类型包括：QR Code、Data Matrix、PDF417、Aztec、EAN-8、EAN-13、UPC-A、UPC-E、Codabar、Code 39、Code 93、Code 128、ITF-14。

约束与限制

支持的设备

• 扫码直达能力：仅支持 Phone、Tablet。
• 默认界面扫码能力和自定义界面扫码能力：支持 Phone、Tablet、Wearable（从 API 版本 6.1.0(23) 开始支持带后置相机的 Wearable，可以通过 getSupportedCameras 接口查询是否带后置相机）。
• 图像识码能力：支持 Phone、Tablet、Wearable（从 API 版本 6.1.0(23) 开始支持 Wearable）。
• 码图生成能力：支持 Phone、Tablet、Wearable、PC/2in1、TV（从 API 版本 5.1.0(18) 开始支持 Wearable，从 API 版本 5.1.1(19) 开始支持 PC/2in1、TV）。

功能使用限制

扫码直达能力的限制条件如下：

1. 当前只支持开发者配置 HTTPS 架构的网页链接接入扫码直达。其他方式接入（如 HTTP 配置）需要通过工单联系华为获取支持。
2. 当前仅支持中国境内（香港特别行政区、澳门特别行政区、中国台湾除外）接入使用。

模拟器支持情况

Scan Kit 支持模拟器，但与真机存在部分能力差异：

• 从 API 版本 6.0.0(20) 开始，模拟器支持默认界面扫码能力开发，但模拟器中默认界面扫码的相机流存在镜像问题，且由于仅支持固定分辨率比例，画面会出现上下黑边。
• 模拟器部分支持自定义界面扫码能力。从 API 版本 6.0.0(20) 开始，模拟器支持部分自定义界面扫码接口开发（支持的接口包括 init、start、stop、release、rescan），可实现自定义界面扫码能力的基本功能验证。
• 模拟器自定义界面扫码能力仅支持 1280*720 分辨率，开发者传入其他分辨率会统一转换成 1280*720。
• 模拟器不支持图像数据识别能力、码图生成能力。

开发准备

在接入“扫码直达”服务之前，需要完成以下准备工作：

1. 参考“应用开发准备”完成基本准备工作。
2. （仅针对“扫码直达”必选）接入 App Linking，需要完成以下步骤：
   • 在 AGC 控制台开通 App Linking 服务。
   • 在开发者网站上关联应用。
   • 在 App Linking 中配置二维码、条形码关联的网址域名。
   • 在应用的 module.json5 文件中关联域名。

说明：

• App Linking 方式当前仅支持 HTTPS 网址，具备应用和网页两种呈现方式。当应用已安装时，优先直达应用内服务页；当应用未安装时，浏览器也可以为用户提供服务。
• App Linking 还广泛应用于社交分享、沉默唤醒、广告引流等场景。
• 接入 App Linking 不能使用 DevEco 的自动签名功能，必须使用手动签名。

接入“扫码直达”服务开发步骤

业务流程

1. 开发者参考 App Linking 指导完成域名注册。
2. 用户通过 HarmonyOS 扫码入口发起扫码请求。
3. HarmonyOS 扫码入口调用系统能力解析码值，查询码值对应的应用信息后拉起应用。
4. 解析码值结果跳转应用服务页。

具体开发步骤

步骤一：完成开发准备

参考第 4 节“开发准备”完成必要的准备工作，包括开通 App Linking、关联应用、配置域名以及在 module.json5 中关联域名。

步骤二：处理接收到的码值，完成应用内页面跳转逻辑

在应用的 UIAbility 中，需要在冷启动和热启动场景下分别获取扫码传入的链接信息，并解析后跳转到对应服务页。

以下为示例代码：

import { UIAbility, Want } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { router, window } from '@kit.ArkUI';

export default class EntryAbility extends UIAbility {
  private page: string = 'pages/Index';
  private uiContext?: UIContext;

  // 冷启动场景通过 onCreate 回调获取码值信息
  onCreate(want: Want): void {
    hilog.info(0x0001, '[Scan Access]', 'Succeeded in getting want in onCreate');

    // 从 want 中获取传入的链接信息。如传入的 url 为：https://www.example.com/scan
    this.getRouterUri(want);
  }

  // 热启动场景通过 onNewWant 回调获取码值信息
  onNewWant(want: Want): void {
    hilog.info(0x0001, '[Scan Access]', 'Succeeded in getting want in onNewWant');
    // 从 want 中获取传入的链接信息
    this.getRouterUri(want);
  }

  onWindowStageCreate(windowStage: window.WindowStage): void {
    hilog.info(0x0001, '[Scan Access]', 'Ability onWindowStageCreate');
    try {
      windowStage.getMainWindow().then((windowObj: window.Window) => {
        try {
          windowStage.loadContent(this.page).then(() => {
            hilog.info(0x0001, '[Scan Access]', 'Succeeded in loading the content.');
            try {
              this.uiContext = windowObj.getUIContext();
              hilog.info(0x0001, '[Scan Access]', 'Succeeded in getting UIContext.');
            } catch (err) {
              hilog.error(0x0001, '[Scan Access]', `Failed to get UIContext by windowObj. Code: ${err.code}.`);
            }
          }).catch((err: BusinessError) => {
            hilog.error(0x0001, '[Scan Access]', `Failed to load the content. Code: ${err.code}.`);
          })
        } catch (err) {
          hilog.error(0x0001, '[Scan Access]', `Failed to load the content. Code: ${err.code}.`);
        }
      }).catch((err: BusinessError) => {
        hilog.error(0x0001, '[Scan Access]', `Failed to get MainWindow. Code: ${err.code}.`);
      })
    } catch (err) {
      hilog.error(0x0001, '[Scan Access]', `Failed to get MainWindow. Code: ${err.code}.`);
    }
  }

  // 解析扫码结果，跳转相应页面
  private getRouterUri(want: Want): void {
    const uri: string | undefined = want?.uri;
    if (!uri) {
      return;
    }
    this.page = 'pages/Access';

    if (this.uiContext) {
      // 开发者根据解析的 uri 跳转至相应页面，例如需要跳转页面：pages/Access
      const status: router.RouterState = this.uiContext.getRouter().getState();
      if (status && status.name !== 'Access') {
        try {
          // 根据 uri 参数做业务处理
          this.uiContext.getRouter().pushUrl({
            url: 'pages/Access'
          }).catch((err: BusinessError) => {
            hilog.error(0x0001, '[Scan Access]', `Failed to pushUrl by getRouter. Code: ${err.code}.`);
          });
        } catch (err) {
          hilog.error(0x0001, '[Scan Access]', `Failed to pushUrl by getRouter. Code: ${err.code}.`);
        }
      }
    }
  }
}

代码说明：

• 冷启动时，系统会通过 onCreate(want: Want) 将扫码得到的 Want 传入，开发者可从 want.uri 获取链接信息。
• 热启动时（应用已在后台运行），系统会调用 onNewWant(want: Want)，同样可从 want.uri 获取链接信息。
• getRouterUri 方法解析 uri，如果存在则设置目标页面为 pages/Access，并通过 uiContext.getRouter().pushUrl 跳转。开发者可根据实际业务解析 URI 中的参数并跳转到具体服务页。

验证“扫码直达”服务

完成开发后，按以下步骤验证“扫码直达”服务是否正常工作：

1. 将配置好域名映射关系的测试应用安装到本地设备。
2. 打开 HarmonyOS 扫码入口（例如控制中心的扫码入口），扫描应用发行的二维码。
3. 确认能否拉起应用并跳转到目标服务页。

开发后验证标准

应用完成开发后，可参照以下标准检查集成扫码直达后的用户体验是否符合预期：

标准编号	标准项名称	类型	标准详细描述
1	应用已安装跳转体验	规则	通过系统扫一扫扫描码图可以跳转到履约页面。履约页面指的是扫码后的目标服务页面，例如，扫支付码跳转到应用的支付页面，而非首页。
2	应用未安装跳转体验	建议	通过系统扫一扫扫描码图会拉起浏览器加载码值所对应的网页，请设计网页满足用户诉求、指导用户安装应用等。

注意事项

1. 扫码直达能力当前仅支持 HTTPS 架构的网页链接，如需使用 HTTP 配置，可通过工单联系华为获取支持。
2. 扫码直达能力当前仅支持 中国境内（香港特别行政区、澳门特别行政区、中国台湾除外）接入使用。
3. 接入 App Linking 时不能使用 DevEco 的自动签名功能，必须使用手动签名。
4. 若应用未安装，扫码后将拉起浏览器加载对应的网页，开发者应确保网页内容能够正确引导用户。
5. 示例工程可参考 Scan Kit 提供的样例工程进行接入，该工程体现了默认界面扫码、自定义界面扫码、图像识码、码图生成等特性。

总结

扫码直达是 Scan Kit 提供的一种轻量级、高效率的扫码接入方案。开发者只需完成 App Linking 域名配置并在应用 UIAbility 中处理扫码传入的 Want 信息，即可实现从系统级扫码入口直达应用内服务页的体验。接入过程中需重点关注 HTTPS 域名要求、手动签名、冷热启动处理以及跳转页面准确性等关键点，确保用户扫码后能够准确到达目标服务页。