使用入门

DataWedge 7.4

概述

DataWedge 允许 Zebra 设备上的任何应用程序从条码、MSR、RFID 和其他输入源采集数据，处理数据并将其作为按键、从 Intent 或通过网络连接输出。DataWedge 操作和设置可以使用来自 UI 的 DataWedge 配置文件（也称为“零代码”方法）进行控制，或使用基于 Intent 的 API 进行编程控制。当应用程序屏幕显示在前台时，DataWedge 会自动检测应用程序或活动与哪个配置文件相关联，并应用该配置文件中的配置。两种方法的概述：

  • DataWedge“零代码”：可以通过 DataWedge UI 创建配置文件来控制扫描行为。当应用程序与配置文件关联且输出设置为“按键”后，应用程序中的所有可编辑文本字段就可以采集数据了。可以使用选项来定义采集（输入）和处理数据的方式。使用默认配置文件 Profile0 时，可以在任何应用程序的文本字段中通过使用按键输出采集数据。
  • DataWedge API：使开发人员能够使用 Android Intent 来查询和修改用于数据收集、数据处理和数据输出的 DataWedge 设置，这些 Intent 通常与一般的 Android 编程配合使用，无需考虑底层硬件。DataWedge API 通常优先于 Zebra 的 EMDK。开发 EMDK 应用程序需要全面了解扫描 API - 由于难度较高，设计和编码 EMDK 应用程序非常耗时。DataWedge 的界面较简单，API 更易于使用，灵活性高。无论底层应用程序技术如何（例如 Java、Xamarin、Cordova），都可以从任何应用程序检索 DataWedge 数据。DataWedge 和 EMDK 提供了类似的功能和对数据采集的控制。有关更多信息，请参阅 DataWedge 与 EMDK 比较表。

条码扫描硬件的控制具有排他性。DataWedge 处于活动状态时，应用程序的扫描器和条码 API（比如 EMDK 应用程序）将无法正常工作。同样，当应用程序控制扫描硬件时，其他应用程序（包括 DataWedge）会被锁定。因此，了解如何控制设备的扫描器硬件非常重要，如有必要，在完成扫描时将其对其他应用程序释放。有关更多信息，请参阅有关禁用 DataWedge 的部分。

DataWedge 功能

每个使用 DataWedge 的应用程序都可以与一个 DataWedge 配置文件关联，该配置文件包含决定如何获取（输入）、处理（数据格式）数据并交付到接收应用程序（输出）的选项。这些选项通常称为插件（如条码输入插件）。DataWedge 持续监视前台应用程序 - 当检测到前台应用程序更改时，它会激活与该应用程序关联的相应配置文件（如果存在）。如果应用程序未与任何配置文件关联，则 Profile0 是将会生效的默认通用配置文件。配置文件可以导出，因此可以在多个设备上部署相同的 DataWedge 配置。

例如，“应用程序 A”可能需要在从 DataWedge 传递每个数据集之后发送 TAB，但“应用程序 B”可能需要发送 ENTER。通过配置文件，可配置 DataWedge 以根据任何数量的个别应用程序的要求处理相同的已捕获数据集。或者，可创建单一配置文件，并将其与多个应用程序关联，以相同的方式为所有应用程序获取和处理数据。

DataWedge 插件在配置文件中指定，并决定如何采集（输入）、处理（格式化）数据并将其发送到应用程序（输出）。此外，可选的配置文件特定配置设置也归类为实用程序，可与应用程序关联或在运行时进行控制。

  • 输入插件 - 指定如何采集数据：

    • 条码 - 在发送数据进行处理之前，指定设备扫描硬件、解码器、解码器参数、读取器参数以及应用于所采集数据的扫描参数。受支持的硬件可以包括集成的内置设备（如 1D 扫描器、2D 扫描器和摄像头）或外接设备（如条码扫描器、蓝牙扫描器和 USB SSI 扫描器）。
    • MSR（磁条读取器）- 从受支持硬件上的 MSR 卡（如信用卡或借记卡）获取数据。
    • RFID（无线射频识别）- 使用内置在某些 Zebra 移动计算机中的集成 RFID 读取器从 RFID 标签获取数据。
    • 串行端口 - 从通过串行端口连接的外围设备获取数据。
    • 语音 - 通过语音识别获取数据。配置包括：定义开始/结束短语、发送 Tab/Enter 命令、将数据限制为字母或数字字符、语音数据验证和脱机工作。

  • 处理插件 - 指定在将采集的数据传递到输出插件之前如何对其进行格式化：

    • 基本数据格式 (BDF) - 在将数据传递到输出插件之前，使用基本的预定义选项对数据进行格式化。可用选项：添加数据前缀、添加数据后缀、将数据发送到前台应用程序、以十六进制格式发送数据、附加 TAB 键以及附加 ENTER 键。这在扫描数据时非常有用，可以通过添加 TAB 键自动移至下一个文本字段。
    • 高级数据格式 (ADF) - 在将数据传递到输出插件之前，按照特定条件并根据自定义规则对数据进行格式化。这在以下情况下非常有用：仅当获得的 9 位 Code-128 条码的中间 3 位与规则中指定的相同 3 位匹配时，触发用零填充数据的操作。

  • 输出插件 - 指定数据的传送方式：

    • 按键 - 采集的数据作为一系列按键发送至关联应用程序中的可编辑字段内。它可用于在不添加任何代码的情况下向应用程序添加扫描功能，此外，它还可以通过 DataWedge Intent API 进行完全配置。
    • Intent - 使用 Android Intent 机制，以编程方式将获取的数据发送到关联的前台应用程序/活动。当只需将数据发送到应用程序屏幕，而不允许用户编辑数据时，此功能非常有用。注册 DataWedge Intent 以接收采集的数据。*Internet 协议 (IP) – 使用 TCP 或 UDP，通过指定的 IP 地址和端口，将获取的数据通过网络发送到主机。这对于将数据扫描到 PC（如在医疗保健环境中）非常有用。

  • 实用程序 - 可选配置文件配置设置：

    • Data Capture Plus (DCP) – 允许设备屏幕的指定区域在被点击时充当虚拟的扫描触发器，模拟按下硬件触发器时的情形。它可以配置为全屏模式，也可以配置为浮动扫描按钮，位于屏幕的右侧、左侧或两侧。

  • Enterprise Keyboard Designer - 允许在关联的应用程序中使用自定义 Enterprise Keyboard 布局，而无需修改应用程序。使用桌面工具 Keyboard Designer 生成 Enterprise Keyboard 布局。Coming Soon

DataWedge 设置 - 为一般的、没有相关配置文件的 DataWedge 选项提供配置。它包括忽略禁用的配置文件、禁用的应用程序列表、导入/导出配置文件和报告等操作。

自动导入 – 提供在 DataWedge 中自动加载预配置的配置文件的功能。这可用于使用第三方 Enterprise Mobility Management (EMM) 系统等工具进行设备远程部署。DataWedge 监视配置文件的特定文件夹。如果找到了配置文件，它会导入该文件以替换任何现有配置或配置文件。

大规模部署 - 可以手动或通过 Enterprise Mobility Management (EMM) 软件将 DataWedge 配置文件和设置部署到多个设备。当放在 /enterprise/device/settings/datawedge/autoimport 目录中时，导出的配置文件可以自动导入。

DataWedge 编程

DataWedge 利用 Android 编程中常用的应用程序组件，称为 Intent。DataWedge 服务包含一个广播接收器，该接收器会侦听和响应广播 Intent，以根据该 Intent 中包含的额外项确定要执行的操作。DataWedge 编程有两种方法：

  • 最少编码 – 基本方法，用于从 Intent 检索数据，无需使用广播接收器（另一个常用的 Android 组件）进行更精细的扫描活动或数据控制。不会应用 DataWedge Intent API。请参阅基本 Intent 示例应用程序。
  • DataWedge Intent API - 使开发人员能够使用 Intent 指定要执行的命令，从而控制 DataWedge 设置以及如何采集、处理数据并将其交付给应用程序。多个 API 调用可以通过单个 Intent 操作作为额外项发送。请参阅条码扫描示例应用程序。

本节的其余部分将介绍 DataWedge Intent API 的使用。应用程序通过广播查询或修改配置的 Intent 来访问 DataWedge API。根据使用的 API，可以在运行时进行更改。Intent 的操作和数据指定要执行的 DataWedge API 函数。函数原型：

Intent i = new Intent(); i.setAction("com.symbol.datawedge.api.ACTION"); i.putExtra(EXTRA_DATA, "<parameter>");

通过发送广播 Intent 对 DataWedge API 进行查询，然后通过广播 Intent 接收回复。

基本使用指南：

  • 创建配置文件/更新现有配置文件/使用单个 Intent 操作配置多个插件：使用 DataWedge 配置文件自定义数据采集，同时使用 Set Config API 创建配置文件、更新配置文件或通过单一 Intent 配置多个插件（输入、处理、输出、实用程序）。使用案例示例：
    • 修改活动配置文件以仅启用应用程序工作流中特定屏幕中的某些解码器，从而提高扫描性能。
    • 当应用程序在前台运行时，根据用户首选项更新配置文件。
    • 根据在前台运行的应用程序，使用预配置的配置文件采集数据。
    • 修改扫描器参数以执行某些操作，比如通过按一下触发器发出连续扫描光束。
  • 启用/禁用数据采集：通过启用 DataWedge API 启用/禁用 DataWedge 扫描器和前台活动监视。这可用于允许其他应用程序（如企业浏览器）以独占方式使用设备扫描器。
  • 支持在不同的 Zebra 设备中使用多种扫描器类型：要检索设备上可用的扫描器类型（如内部成像器、内部摄像头、连接的蓝牙等），请使用 Enumerate Scanners API。如果应用程序是在支持不同类型扫描器硬件的不同 Zebra 设备上使用，则此功能非常有用。
  • 在应用程序 UI 中启动条码扫描：使用 Soft Scan Trigger API，在应用程序中通过轻触按钮来触发条码扫描。请参阅条码示例应用程序。
  • 检查版本信息以确保功能支持：使用获取版本信息 API 检索设备上的 DataWedge 版本。这可用于确定设备是否支持正在使用的特定功能，并通过根据可用性启用/禁用该功能来采取措施。
  • 在运行时修改条码扫描器参数：当条码扫描器参数需要在运行时动态修改，但不能在配置文件中持久保存时，请使用切换扫描参数 API。例如，应用程序可以有一个按钮，允许用户根据需要将触发器设置为连续模式，而无需在配置文件中进行此设置，因为不希望将其设置为默认行为。这是临时更新 - 当“切换”发生后，如果配置文件更改，则不会保留该设置。
  • 在运行时启用/禁用或临时挂起/恢复条码扫描：动态控制集成条码扫描器（激光、成像器、内部摄像头），以在应用程序工作流的某些区域启用/禁用触发器，或挂起/恢复扫描以使用扫描器输入插件临时激活/停用扫描器。状态更改通知包括活动配置文件名称，这使应用程序仅在状态更改影响相关配置文件时才使用启用/禁用扫描器调用。这对于快速连续地更改扫描器状态非常有用，例如，如果存在多个文本字段，并且需要扫描在特定文本字段处于焦点位置时挂起，请使用扫描器输入插件在该特定文本字段中挂起扫描器。
  • 监视配置、扫描器和配置文件切换更改：使用注册通知 API 注册/注销以接收与配置、扫描器和配置文件切换相关的更改通知。这些更改可能是由 DataWedge API 调用（例如导入配置、切换到配置文件和扫描器输入插件）或 DataWedge 配置文件更改（例如配置文件自动导入）引起的。
  • 导入配置文件或配置：将配置文件或包含多个配置文件的配置文件导出并放入设备中后，可以使用导入配置 API 以编程方式导入这些设置，也可以手动导入。
  • 删除配置文件：当不再需要某个配置文件时，可以使用删除配置文件 API 将其删除。如果有应用程序使用配置文件执行一次性任务，或者退出应用程序时需要删除配置文件，则此功能非常有用。
  • 复制现有的配置文件：使用克隆配置文件 API 创建现有配置文件的副本。如果一个应用程序需要多个既有通用配置参数、又有细微差别的配置文件时，则此功能非常有用 - 复制后，克隆的配置文件可传递到“设置配置”以设置不同的配置。
  • 检索配置文件列表：使用获取配置文件列表 API 检索所有 DataWedge 配置文件。如果应用程序需要查询配置文件列表以查找特定配置文件，或者需要向用户显示列表以供选择配置文件，则此功能非常有用。如果应用程序在启动时创建了一个 DataWedge 配置文件，则可以包括一个检查，通过检索配置文件列表来确定这个配置文件是否存在，从而提高性能并避免不必要的文件输入/输出操作。
  • 根据应用程序工作流使用不同的配置文件：为了灵活使用不与其他应用程序相关联的配置文件，以便在运行时切换配置文件，以及克服只能将应用程序活动与一个配置文件关联的限制，请使用切换到配置文件 API 来激活尚未与另一个应用程序相关联的配置文件。这对于在同一应用程序活动中使用不同的配置文件很有帮助，例如，如果该活动的某个区域需要扫描 PDF417 条码，而另一个区域需要读取 MSR 卡数据。当焦点是扫描 PDF417 条码时，使用 SWITCH_TO_PROFILE 激活包含条码配置的配置文件。同样，当焦点是读取 MSR 数据时，使用 SWITCH_TO_PROFILE 激活包含 MSR 配置的配置文件。两个配置文件都不能已与应用程序相关联。

编程注意事项

下面的信息提供了有关 DataWedge 应用程序开发的指导和最佳实践。

常规

  • 扫描性能优化：为提高扫描性能，Zebra 建议禁用与给定配置文件相关联的应用程序不需要的所有解码器。 Check for status before changing status. Notification methods -ie. 配置文件切换或启用/禁用。应先接收状态更改，然后再继续。
  • 跨多个应用程序的配置文件配置：DataWedge 是一项全局服务，设备上的任何应用程序都可与其交互以配置任何配置文件。因此，如果多个应用程序尝试修改同一组配置文件，则应小心。

数据采集

  • 在应用程序中临时挂起或停用扫描：将扫描器输入插件 API 与 SUSPEND_PLUGIN/RESUME_PLUGIN 参数配合使用。
  • 对于需要在挂起/恢复状态之间快速更改的情况，请使用扫描器输入插件并注册 SCANNER_STATUS 通知。当扫描器激活时（例如，从配置文件配置或者从 RESUME_PLUGIN 或 ENABLE_PLUGIN Intent API），SCANNER_STATUS 会广播 WAITING 和 SCANNING 状态，根据是否正在进行扫描在各状态之间循环。要让应用程序挂起扫描，请仅在处于 SCANNING 和 WAITING 状态时执行操作 - 当这些状态被广播时，使用 SUSPEND_PLUGIN 参数保持挂起状态并使扫描器不可用。扫描挂起后，SCANNER_STATUS 会广播 IDLE 状态。使用 RESUME_PLUGIN 可重新激活扫描器。
  • 在一个应用程序中采集数据和照片：如果应用程序是以此目的进行设计的，则可以使用相同的应用程序进行拍照和捕获条码数据。
    1. 在应用程序中添加单独的活动：一个用于条码扫描，另一个用于拍照。
    2. 创建具有以下设置的 DataWedge 配置文件：
    3. 将配置文件与拍照活动关联
    4. 在配置文件中禁用扫描
    5. 使用标准 Android-SDK API 来控制摄像头
    6. 应用程序用于扫描时，默认 DataWedge 配置文件将生效。
    7. 为访问特定的解码器、处理规则或其他特殊扫描需求，可创建第二个 DataWedge 配置文件，并将其与应用程序的条码扫描活动关联。
  • 数据发送速度过快：如果发送数据的速度太快，应用程序无法接受（例如使用终端仿真应用程序时），可通过在设置配置中使用 keystroke_character_delay 在发送到应用程序的每个字符之间添加延迟来解决此问题。请参阅“按键输出参数”部分，以及“配置字符间延迟”部分中提供的示例代码。此参数应谨慎使用，因为它会对应用程序性能产生负面影响。
  • 当使用 DataWedge Intent API 查询 DataWedge 信息时（例如“获取活动配置文件”），该应用程序必须进行注册，才能使用标识结果 Intent 操作和类别的过滤器来接收结果。

配置文件

  • 导入配置文件时存在重复的关联应用程序：如果当前的配置文件与正在导入的配置文件之间存在重复的关联应用程序，则正在导入的配置文件将不会生效。例如，如果当前的配置文件 A 配置了关联的应用程序，并且该应用程序又与配置文件 B 关联，则在导入配置文件 B 时，由于重复，导入不会生效。如果某个应用程序在已禁用的应用程序列表中列出，而该应用程序又是正在导入的配置文件中的关联应用程序，则同样适用 - 导入不会生效，该应用程序仍保留在已禁用的应用程序列表中。
  • 活动/应用程序与配置文件关联：可将单个配置文件与一个或多个活动或应用程序相关联。但是，一个活动或应用程序只能与一个配置文件关联。如果需要将活动或应用程序与多个配置文件关联，可以使用不指定任何关联应用程序的 SWITCH_TO_PROFILE 来解决此问题。
    以下示例讨论了将 SWITCH_TO_PROFILE 与 SCANNER_INPUT_PLUGIN 用于两个活动的情况：活动 A 启动并使用切换到配置文件 API 切换到配置文件 A，其中已启用 SCANNER_INPUT_PLUGIN，然后在某些时候禁用扫描器插件。与配置文件 B 关联的活动 B 启动。DataWedge 切换到配置文件 B。当活动 A 从 onResume 方法中返回到前台时，活动 A 需要使用数据“切换到配置文件”切换回配置文件 A，然后再次使用相同的 API Intent 禁用扫描器插件，以返回至其当时所处状态。提醒：使用此 API 只会更改扫描器的运行时状态；它不会保留配置文件更改。上述情况假设配置文件 A 未与任何应用程序/活动关联，那么当焦点切换回活动 A 时，DataWedge 将不会自动切换到配置文件 A，并且活动 A 必须通过 onResume 方法切换回配置文件 A。由于当活动暂停时，DataWedge 将自动切换配置文件，因此建议从活动的 onResume 方法调用此 API 函数。

示例应用程序

截至编写本文时，有以下 DataWedge 示例应用程序可用：

  • 基本扫描应用程序 - 使用没有 DataWedge Intent API 的 Android Intent
  • 扫描应用程序 - 包括使用 DataWedge Intent API 执行以下操作的能力：
    • 选择解码器
    • 创建配置文件
    • 注册扫描器状态通知
    • 接收条码数据
    • 使用软件扫描触发器
  • 签名采集应用程序 – 使用解码器签名捕获文档中的一个区域，例如被特定图案包围的签名，并将其保存到图像中

相关信息：