跳转至
For the complete DHIS2 documentation index, see llms.txt.
使用Android SDK开发

短信模块{ #android_sdk_sms_module }

SMS模块可用作Internet连接不可用时的后备方法，以上传数据。它需要在服务器中进行其他设置：必须在服务器中配置SMS网关才能接收SMS；可选地，服务器可能具有将SMS发送回带有响应的客户端的功能。

取决于移动提供商，发送SMS可能意味着额外的费用。因此，SMS模块仅用于**粒度数据上传**。它不用于元数据下载或批量数据下载/上传。此外，数据是使用[SMS压缩库]（https://github.com/dhis2/sms-compression）压缩的，因此内容可以容纳较少的消息。该库与后端共享。

出于测试目的，您可以使用[DHIS2 Android SMS网关]（https://github.com/dhis2/dhis2-sms-android-gateway）。

在 SDK 中，可通过 D2 访问 SMS 模块。

d2.smsModule()

默认情况下禁用此模块，并且必须明确启用和配置该模块。它包括三个可以访问模块功能的组件。

  • ConfigCase：用于设置所有短信发送任务通用的初始数据，如网关号码、超时、执行下载 元数据 ids 对象。
  • 短信提交案例。它用于转换Sdk将发送的*DHIS2*数据，通过短信发送并检查提交进度和结果。
  • QrCodeCase：用于将 DHIS2 数据转换为字符串。该字符串是 DHIS2 数据的压缩表示。这对于避免通过短信发送大量内容很有用。

使用SMS模块的典型工作流程如下：

  • 启用短信模块。
  • 同步元数据。 SMS 模块从服务器下载其他元数据，因此必须在 Internet 连接可用时且**在**模块启用后完成此步骤。
  • 使用短信模块发送数据。

这是典型工作流程的代码示例（为了简化代码，它使用了阻塞方法）：

// Enable SMS Module
d2.smsModule().configCase().setModuleEnabled(true).blockingAwait();

// Sync SMS Module metadata using SMS Module
d2.smsModule().configCase().refreshMetadataIds().blockingAwait();
// or using metadata module
d2.metadataModule().blockingDownload();

// Configure, at least, the gateway number. See ConfigCase for more parameters
d2.smsModule().configCase().setGatewayNumber("gateway-number").blockingAwait();

// Send data. For example a tracker event:
SmsSubmitCase case = d2.smsModule().smsSubmitCase();
Integer numSMSs = case.convertTrackerEvent("event-uid").blockingGet();

case.send().blockingSubscribe();

短信版本

SMS以压缩格式从服务器发送到服务器。该任务由[SMS压缩库]（https://github.com/dhis2/sms-compression）完成，它负责在纯文本和压缩格式之间进行转换。

SDK包含压缩库的最新可用版本，但不能保证服务器也正在使用它。因此，需要检查服务器版本才能启用/禁用某些功能。可以通过以下方式检查服务器中的SMS版本：

d2.systemInfoModule().versionManager().getSmsVersion()

版本概述-功能：

版本1：

  • 汇总数据。
  • 跟踪器/事件数据，但存在一些已知的错误。我们建议不要在版本1中启用跟踪器SMS同步。

版本2：

  • 添加对空列表的支持。
  • 添加对事件中几何图形的支持（POINT）。
  • 在事件（事件数据，截止日期）和注册（执行日期，事件日期）中添加缺少的属性。
  • 添加对在同一SMS提交案例中发送注册和事件的支持。

有关更多信息，请检查[SMS压缩存储库]（https://github.com/dhis2/sms-compression）。

ConfigCase

d2.smsModule().configCase()

使用此情况之前，请先配置SMS模块。至少需要：

  • 启用模块。
  • 设置网关号。
  • 下载元数据ID。

还有其他可选参数可控制SDK是否应等待服务器的响应以及响应超时。另外，可以指定发件人编号，以便忽略从其他发件人收到的消息。

SmsSubmitCase

使用这种情况创建一个新的提交并发送。提交案例不可重复使用，只能发送一次。要创建新的提交案例，请调用方法：

SmsSubmitCase case = d2.smsModule().smsSubmitCase();

发送短信有两种选择：请求权限和直接在应用程序内发送短信；或者获取压缩消息并使用外部应用程序发送短信。

在应用程序内发送短信{ #android_sdk_sms_embedded_submit_case }

提交涉及以下步骤：

  • 指定要提交的数据。这意味着要调用类似 convert*()这样的方法。
  • 发送消息。
  • （可选）检查确认短信。

例如，发送跟踪事件将类似于：

SmsSubmitCase case = d2.smsModule().smsSubmitCase();
Integer numSMSs = case.convertTrackerEvent("event-uid").blockingGet();

case.send().blockingSubscribe();

重要

该应用负责向用户询问权限（READ_PHONE_STATE，SEND_SMS，READ_SMS，RECEIVE_SMS）。否则，SMS模块将失败。

以下方法可用于设置要发送的 DHIS2 数据：

  • convertSimpleEvent（）。设置一个简单的事件。
  • convertTrackerEvent（）。设置跟踪事件。
  • convertEnrollment（）。设置注册。
  • convertDataSet（）。设置数据集。
  • convertRelationship（）。建立关系。
  • convertDeletion（）。删除事件。

上面的方法返回一个包含消息数量的单个 物品占用。使用这些方法的示例显示在 下一个片段。

Single<Integer> convertTask = d2.smsModule().smsSubmitCase()
    .convertEnrollment("enrollment_uid")

要发送之前转换的数据，Sdk 提供了一个 send() 方法。 方法，该方法会返回一个当前状态流。此外，还可以通过调用 提交 ID。

d2.smsModule().smsSubmitCase().send()

也可以通过调用 方法等待短信结果。它会返回一个 Completable 对象，其中 完成表示短信已成功接收。如果 则返回错误信息。接受的日期是 将被检查确认的最小日期。 用于跳过可能具有相同提交 ID 的旧短信。

d2.smsModule().smsSubmitCase().checkConfirmationSms(new Date());

如果某些条件未满足，这些方法可能会失败，并返回一个 PreconditionFailed 对象。 对象。前提条件错误包括

  • NO_NETWORK。
  • NO_CHECK_NETWORK_PERMISSION。
  • NO_RECEIVE_SMS_PERMISSION。
  • NO_SEND_SMS_PERMISSION。
  • NO_GATEWAY_NUMBER_SET。
  • NO_USER_LOGGED_IN。
  • NO_METADATA_DOWNLOADED。
  • SMS_MODULE_DISABLED。

使用外部应用程序发送短信

使用外部应用程序提交涉及以下步骤：

  • 指定要提交的数据并获取压缩信息。这意味着要调用类似 compress*() 的方法。
  • 使用外部应用程序发送消息。
  • 如果您知道消息已发送，则可以选择标记为 SENT_VIA_SMS。
  • （可选）检查确认短信。

例如，发送跟踪事件将类似于：

``java SmsSubmitCase 案例 = d2.smsModule().smsSubmitCase(); String message = case.compressTrackerEvent("event-uid").blockingGet();

// 使用外部应用程序发送短信

// 可选择将案例标记为 SENT_VIA_SMS case.markAsSentViaSMS();

// 如果你收到服务器的响应，你可以检查该消息是否与情况相符。 boolean isResponseMessage = case.isConfirmationMessage("sender_number", "message").blockingGet(); ````

QrCodeCase

java d2.smsModule().qrCodeCase()

使用此方法可获得数据的压缩表示形式。

QrCodeCase 可以转换下一个类型的 DHIS2 对象：

  • 简单事件。使用 generateSimpleEventCode() 方法并传递事件 uid。
  • 跟踪事件。使用 generateTrackerEventCode() 方法并传递事件 uid。
  • 注册。使用 GenerateEnrollmentCode() 方法并传递注册 uid。
  • 关系。使用 GenerateRelationshipCode() 方法并传递关系 uid。
  • 数据集。使用 "生成数据集代码（）"方法并传递数据集 uid、组织单位 uid、属性选项组合和周期 id。

还可以获取可用于删除事件的压缩字符串：

  • 删除。使用 generateDeletionCode() 方法并传递事件的 uid。

These methods returns a Single with the compressed data. The next code snippet shows an example of how it can be used.

java Single<String> convertTask = d2.smsModule().qrCodeCase().generateEnrollmentCode(enrollmentUid);