Build and release ThingsBoard App

Build and release the ThingsBoard app version 1.7 or later for iOS and Android.

Before you start

This guide assumes you have already:

Cloned the app source code and created an app bundle in Mobile apps, as described in the Getting started guide.
Placed the downloaded configs.json file in the project root.
Installed the Flutter version that matches your app version. It is listed in the compatibility matrix and in the .fvmrc file in the project root.

If you need to change any settings, update them in Mobile apps, re-download configs.json, and replace the file in your project.

To re-download the file:

Go to Mobile apps → Bundles in the left main menu.
Click the Configuration app button in the row of the target bundle.
In the Configuration dialog, click Download file to get configs.json.
Replace the existing configs.json in your project root, next to pubspec.yaml, and rebuild the app.

App ID, name and version

You don’t need to rename the app in the source code. The build reads the app ID and name from configs.json:

Platform	App ID	App name
Android	`androidApplicationId` (the application ID)	`androidApplicationName`
iOS	`iosApplicationId` (the bundle ID)	`iosApplicationName`

These values come from the application you added to the bundle in Mobile apps. Without --dart-define-from-file configs.json, the build falls back to the default ThingsBoard app ID, which you can’t publish under your account.

The version shown in the stores comes from the version field in pubspec.yaml (for example, 1.9.1+16 is version 1.9.1, build 16). App Store Connect and Google Play reject an upload whose build number was already used, so raise it for every upload, either in pubspec.yaml or with the --build-name and --build-number build options.

iOS — build and release

Follow the official Build and release an iOS app guide to prepare your app for the App Store and TestFlight.

Configure signing

Starting with version 1.9.1, the iOS project has two targets that are signed and shipped together:

Runner — the app itself.
NotificationServiceExtension — a notification service extension that adds the icon configured in the notification template to push notifications. Its bundle ID is set automatically to <iosApplicationId>.NotificationServiceExtension. Don’t change it: Apple requires an extension’s bundle ID to start with the app’s bundle ID.

Run any iOS build once, for example flutter build ios --no-codesign --no-tree-shake-icons --dart-define-from-file configs.json. It generates ios/Flutter/AppConfig.xcconfig with the bundle ID from configs.json, so Xcode shows your bundle ID instead of the default one.
Open ios/Runner.xcworkspace in Xcode (not Runner.xcodeproj).
Select the Runner target, open the Signing & Capabilities tab, and select your Team.
Select the NotificationServiceExtension target and select the same Team. Both targets come with the ThingsBoard team selected, so the build fails until you change it in both.
With automatic signing, Xcode registers both App IDs and creates their provisioning profiles. With manual signing, also create an App ID and an App Store provisioning profile for <iosApplicationId>.NotificationServiceExtension, and select that profile for the extension target.

Build the archive

flutter build ipa --no-tree-shake-icons --dart-define-from-file configs.json

The .ipa file is written to build/ios/ipa/. Upload it to App Store Connect with the Transporter app, or open the archive from build/ios/archive/ in Xcode and click Distribute App.

Android — build and release

Follow the official Build and release an Android app guide to prepare your app for Google Play.

flutter build appbundle --no-tree-shake-icons --dart-define-from-file configs.json

The app bundle is written to build/app/outputs/bundle/release/app-release.aab. Upload it to the Google Play Console.

After the first upload, copy the SHA-256 certificate fingerprint of the app signing key from the Google Play Console (Release → Setup → App Integrity → App Signing) to the Android application in your Mobile apps bundle. App links and QR code login need it.

Build flags

--no-tree-shake-icons — prevents Flutter from removing icons that the code doesn’t reference directly. The app picks some icons at runtime by name: the icons set in the Mobile apps layout and in notification templates. The iOS notification service extension draws push notification icons from the same icon fonts. Without this flag, those icons are missing or shown as empty boxes.

--dart-define-from-file configs.json — loads the mobile app configuration from the JSON file downloaded from Mobile apps: the server address, app ID and name, app secrets and app links settings. Without it, the build uses the default ThingsBoard settings.

Troubleshooting

Signing fails for NotificationServiceExtension

An error such as Signing for "NotificationServiceExtension" requires a development team or No profiles for '…NotificationServiceExtension' were found means the extension target isn’t signed with your team. Complete Configure signing for both targets.

Embedded binary’s bundle identifier is not prefixed with the parent app’s bundle identifier

The extension’s bundle ID was changed by hand. In the NotificationServiceExtension target, set Bundle Identifier back to $(IOSAPPLICATIONID).NotificationServiceExtension and build again with --dart-define-from-file configs.json.

Was this helpful?