ThingsBoard移动应用快速入门

• 前置条件
• 步骤1：在移动中心创建Bundle
• 步骤2（可选）：配置推送通知
• 步骤3.[可选]构建并发布移动应用
• 故障排除
  • 应用无法构建
  • 警告”推送通知未配置”
  • 仪表板无法加载
  • 无法登录？
  • 其他问题？
• 后续步骤

欢迎！本指南将带您从零开始，为ThingsBoard实例创建并配置自己的ThingsBoard移动应用。

开始之前，请使用兼容性表选择与ThingsBoard平台匹配的移动应用版本。使用不兼容的版本是登录问题或意外行为的最常见原因。

前置条件

• 可访问ThingsBoard实例。最简单的方式是使用ThingsBoard Cloud。或者，使用官方安装指南安装ThingsBoard。
• 准备构建ThingsBoard移动应用的环境：
  • 安装Flutter SDK，版本需与您的应用版本对应（参见兼容性表）。
  • （推荐）为Flutter开发配置您的IDE（如Visual Studio Code）。
  • 如果您是Flutter新手，请查阅”编写您的第一个Flutter应用”教程。

步骤1：在移动中心创建Bundle

移动中心是创建、配置和管理移动应用的统一控制中心。 它让您能够快速启动为ThingsBoard平台定制的移动应用。

创建新Bundle

Bundle包含Android和/或iOS应用配置——包括OAuth 2.0设置以及布局偏好。所有配置集中管理，便于统一维护。

添加新Bundle：

• 进入”移动中心“页面。
• 在”Bundle“选项卡中，点击右上角的”+ 添加Bundle“按钮。

随后会打开创建Bundle对话框。

基本设置

• 输入Bundle标题。
• 在目标移动平台（Android或iOS）旁点击”创建新“。 这将打开添加应用对话框：
  • 输入应用包名称。
  • 应用密钥将自动生成（您也可以设置自己的）。
  • 设置已发布应用状态——应用已准备好发布。
  • （可选）指定最低和最新应用版本及发布说明。
  • 添加应用商店信息：
    • Android：
      • Google Play Store链接。
      • SHA256证书指纹。
    • iOS：
      • App Store链接。
      • App ID。
  • 点击”添加“保存并继续。
• 然后点击”下一步“。

可选：认证与布局

• OAuth 2.0提供方——如有需要，可为ThingsBoard移动应用配置外部OAuth。完成后点击”下一步“。

• 配置布局——自定义导航菜单以便快速访问功能和仪表板。可添加菜单项、设置图标/标签并调整条目顺序。点击”添加“完成Bundle创建。

使用外部OAuth 2.0提供方在ThingsBoard移动应用中配置认证，并配置布局以便快速访问您最常使用的功能和仪表板。

点击”添加“完成Bundle添加。

配置对话框

添加Bundle后，将出现分步对话框引导您完成剩余设置和部署步骤。 请按步骤操作，完成ThingsBoard移动应用配置。

自ThingsBoard 4.2和移动应用1.7起可用

自ThingsBoard 4.2和移动应用1.7起，应用配置流程已显著改进。 您现在可以直接从平台下载配置文件并将其置于应用代码库根目录——无需手动编辑。

使用1.7应用版本配合4.2之前平台版本时，必须手动创建配置文件，请参阅此GitHub工单获取说明。

重要： 构建或运行应用时，请包含Dart define标志：

1
flutter run --dart-define-from-file configs.json

您可以使用不同名称维护多个配置文件。将相应的文件名传给--dart-define-from-file标志。

最后，根据您的移动平台（Android或iOS），您应看到类似以下的结果：

Android

iOS

提示：在真机上首次启动可能需要一段时间。之后，可使用热重载（hot reload）进行快速更新。

如果使用flutter run从控制台启动，按r可进行热重载（hot reload）。

步骤2（可选）：配置推送通知

我们的系统利用Firebase将ThingsBoard实例的通知直接发送到移动应用。 此设置要求每个平台租户为其账户专门配置Firebase，才能开始向其移动应用分发通知。

步骤2.1创建Firebase项目

接下来，我们将逐步介绍如何创建Firebase项目，并在其中生成私钥。此密钥用于安全地将ThingsBoard实例连接到Firebase服务。

请注意： ThingsBoard CE中，仅系统管理员可配置移动设置。ThingsBoard PE中，租户可使用系统管理员的配置或指定自己的配置。

开始操作：

• 登录您的Firebase账户。登录后，点击”Create a project”按钮；

• 在提供的字段中输入您所需的项目名称，然后点击”Continue”；

• 接下来是决定是否为本项目启用Google Analytics。您可以选择启用或禁用。做出选择后，点击”Continue”；

• 设置Google Analytics后，点击”Create project”按钮确认项目创建；

• 您的Firebase项目已准备就绪。点击”Continue”打开Firebase项目控制面板；

• 在左侧菜单中，进入”Project Overview” -> “Project settings”页面；

• 在”Project settings”页面中，切换到”Cloud Messaging”选项卡。此处确保启用Firebase Cloud Messaging API以使用消息功能；

• 接下来进入”Service accounts”选项卡。在”Admin SDK configuration snippet”中，选择”Java”部分。然后，点击”Generate new private key”按钮。此操作将为您的服务账户生成私钥——对安全服务器通信至关重要；

• 点击”Generate key”按钮确认私钥生成。请妥善保管此密钥，ThingsBoard服务器端操作需要用到；

• 以系统管理员身份登录ThingsBoard，打开”Settings”页面并导航至”Notifications”选项卡。在”Mobile settings”部分，上传您在Firebase项目中生成的私钥文件并点击”Save”完成配置。

步骤2.2将Firebase添加到移动应用

要将Firebase集成到移动应用中，您需要完成Firebase官方文档中“Add Firebase to your Flutter app”指南概述的前两个步骤。

[仅限iOS] Apple应用配置

将APNs认证密钥上传到Firebase。

• 首先，使用Apple官方文档在Apple Developer Member Center创建APNs认证密钥；
• 在您的Firebase项目中，进入”Project Settings”页面的”Cloud Messaging”选项卡。向下滚动找到”Apple app configuration”部分；
• 在”APNs authentication key”中点击”Upload”按钮；
• 添加APNs认证密钥并在相应字段中输入”Key ID”和”Team ID”；
• 然后点击”Upload”按钮。

APNs认证密钥已上传。

步骤2.3检查项目配置

成功完成这些步骤后，请确保您的项目包含以下文件：

• 如果ThingsBoard移动应用面向iOS：

1
ios/Runner/GoogleService-Info.plist

• 如果ThingsBoard移动应用面向Android：

1
android/app/google-services.json

请注意： 如果flutter_thingsboard_app项目当前正在运行，请停止它并进行重新构建。

要确认Firebase已正确集成，请运行您的应用。

1
flutter run

如果一切配置正确，您移动应用中的通知菜单应处于激活状态，如下方截屏所示。

了解更多关于通知及如何配置此处。

步骤3.[可选]构建并发布移动应用

如需为iOS或Android构建并发布ThingsBoard移动应用，请参阅本指南。

故障排除

如果在构建或运行移动应用时遇到问题，以下是帮助您解决最常见问题的详细指南。

应用无法构建

ThingsBoard移动应用支持特定的Flutter版本。我们的版本发布与Flutter官方发布并不总是同步，因此较新的Flutter版本可能尚不兼容。

务必使用为您的应用版本指定的确切Flutter版本。否则，构建可能失败或出现意外行为。

如何检查所需的Flutter版本？

1. 查看以下链接的发布说明。

示例：

2. 检查项目根目录的.fvmrc文件：

您将找到类似这样的文件：

1
2
3
{
  "flutter": "3.24.4"
}

这表示我们当前使用Flutter 3.24.4。

安装正确的Flutter版本

选项1：使用FVM（Flutter版本管理器）[推荐]

什么是FVM？

FVM帮助您跨项目管理多个Flutter版本。它让您能够管理多个Flutter版本并轻松按项目切换。 在测试新Flutter版本或为不同项目贡献代码时非常有用。

按照官方安装指南安装FVM。

用法：使用带fvm前缀的Flutter命令，例如：

示例：

1
2
fvm flutter run
fvm flutter build apk

选项2：手动设置全局Flutter版本 [不推荐]

如果您只在一个项目上工作，可以手动设置全局Flutter版本：

1
2
cd ~/dev/flutter
git checkout 3.24.4

警告”推送通知未配置”

如果您看到如下警告：

“推送通知未配置”

这通常意味着Firebase未正确设置。

修复：

注意：您必须首先完成设置指南中的步骤2。

1. 删除文件：lib/firebase_options.dart
2. 重新运行FlutterFire CLI：

1
flutterfire configure

3. 确保firebase_options.dart文件已重新生成并包含Android和iOS或两者的配置。

仪表板无法加载

移动应用并非真正自行加载仪表板——ThingsBoard平台处理所有实际加载。 移动应用仅打开WebView，但应用和平台必须能够相互通信。

首先，检查日志。查找此日志消息：

1
Invoked tbMobileReadyHandler

• 如果未找到，表示平台未向应用发出就绪信号：此情况下，请在ThingsBoard平台仓库提交issue。

• 如果您看到日志但仪表板仍无法加载：此情况下，请在CE移动仓库提交issue。

请尽可能详细，并通过ThingsBoard Support私下提供实例凭据（切勿公开发布）。

无法登录？

检查平台与移动应用版本的兼容性表。版本不匹配是登录问题最常见的原因。

如果版本已对齐但您仍然无法登录：

• 提交GitHub issue。

• 包含：

  • 平台版本
  • 移动应用版本
  • 日志/截屏
  • 设备详情（OS、版本）

其他问题？

以上是最常见的问题——但如果您遇到新情况：

提交GitHub issue。尽可能包含所有上下文（截屏、日志、版本、平台设置等）。

我们将尽力帮助您！

后续步骤

• 自定义应用 - 了解如何自定义ThingsBoard移动应用以满足您的需求。
• 构建并发布ThingsBoard移动应用 - 了解如何构建、发布并将您的ThingsBoard移动应用版本发布到Google Play或App Store。