Mobile App
The SPICE mobile app is a native Android application (Kotlin) used by field staff. It works offline: data is stored in an encrypted on-device database and synchronised with the backend in the background. The server address is compiled into the app, so you build the app for your own deployment and distribute that build.
Deploy the backend services first. You need the public API address of the reverse proxy (for example https://<api-host>).
Toolchain
Versions below come from the project's build files.
Android Studio
A current stable release that supports Android Gradle Plugin 9.2
JDK
17 or later (Java 17 is the compile target)
Gradle
9.6.1, supplied by the Gradle wrapper (./gradlew)
Android Gradle Plugin
9.2.1
Kotlin
2.4.10
Android SDK
Platform 37 (compileSdk and targetSdk 37)
NDK
26.1.10909125
Minimum supported Android version
API 23 (Android 6.0)
Install the Android SDK Platform 37 and the NDK version above from the Android Studio SDK Manager. Gradle is configured to use up to 4 GB of heap (org.gradle.jvmargs in gradle.properties), so use a build machine with at least 8 GB of RAM.
The project README mentions Java 18. The build files compile for Java 17, so JDK 17 or later works.
Get the source
git clone <your-mobile-repository-url> spice_mobile
cd spice_mobile/<android-project-directory>The Android project is the directory that contains gradlew, build.gradle.kts, settings.gradle.kts and the app and analytics modules. All commands below run from that directory.
Configure the build
Server addresses and keys
The build reads deployment-specific values from a properties file named environment.properties in the project root (next to build.gradle.kts). The file is listed in .gitignore; keep it out of source control and out of shared storage. Gradle injects the values into the app as BuildConfig fields:
<PREFIX>_API_BASE_URL
API_BASE_URL
Public API address of your backend, including the scheme and a trailing slash, for example https://<api-host>/. All API calls are sent to <API_BASE_URL>auth-service/..., spice-service/... and offline-service/..., matching the reverse proxy paths
<PREFIX>_ADMIN_BASE_URL
ADMIN_BASE_URL
Address of the web portal; used to open the privacy policy page
<PREFIX>_SALT_KEY
SALT
Key used to hash the password on the device (HMAC-SHA512) before sign-in. It must be the same value that your administrator web portal uses as its password hash key and that your stored password hashes were created with
<PREFIX>_DB_ENCRYPTION_KEY
ROOM_DB_ENCRYPTION_KEY
Passphrase that encrypts the on-device database
<PREFIX> is chosen per build flavor. The file contains one block of four properties for each flavor you build:
Treat the salt and the encryption key as long-lived secrets:
Do not change the encryption key after you have released the app. The existing on-device database can no longer be opened with a different key, so users would lose any data that has not yet synchronised.
Do not change the salt unless you also re-create the stored password hashes, otherwise nobody can sign in.
Use a different encryption key for each environment, and store them in your organisation's secret manager.
Build flavors
The app module defines product flavors in the version dimension (productFlavors in app/build.gradle.kts). Each flavor sets its own application ID suffix, app name, signing configuration and the four BuildConfig fields above. To build for your deployment, add a flavor that follows the same pattern and point it at your properties:
If you install more than one flavor on the same device, give each a unique applicationIdSuffix so that they can coexist. The Gradle tasks are named after the flavor: with a flavor myorg, the tasks are assembleMyorgDebug, assembleMyorgRelease and bundleMyorgRelease.
Signing configuration
app/build.gradle.kts defines the signing configurations (signingConfigs). Each one has a key alias, a key password and a store password read from environment.properties, and a keystore file in the app directory. A flavor chooses one signing configuration with signingConfig = .... Debug variants of a flavor use the same signing configuration as its release variant, so the keystore and the credentials must be in place for any APK build.
Create a keystore for your organisation once and keep it safe. If you lose it you cannot publish updates to installed apps:
Copy the keystore into the
appdirectory and update thesigningConfigsblock to reference your file name and your property names.Add the alias, key password and store password to
environment.properties. Never commit the keystore or its passwords.
Third-party service configuration
The app module applies a crash-reporting plugin and a third-party services plugin (see the plugins block in app/build.gradle.kts). The services plugin expects a configuration file at app/google-services.json.
Build
Run these commands from the project root. Replace <Flavor> with your flavor name in the Gradle task name (first letter capitalised).
Outputs are written under app/build/outputs/:
APK
app/build/outputs/apk/<flavor>/<buildType>/*.apk
App Bundle
app/build/outputs/bundle/<flavor>Release/*.aab
Notes:
Running
./gradlew assembleDebugwithout a flavor builds every flavor. Always use a flavor-qualified task.A flavor named
productionhas its debug variant disabled; build its release variant instead.Release builds are shrunk and obfuscated; keep the generated mapping file (
app/build/outputs/mapping/) for each release if you analyse crash reports.Run the unit tests with
./gradlew :app:test<Flavor>DebugUnitTest :analytics:testDebugUnitTest.
Distribute the app
Managed distribution (mobile device management, MDM)
Organisation-owned devices
Upload the signed release APK or bundle to your MDM, assign it to device groups and mark it as a required app so that updates install automatically
Direct APK
Pilots and small deployments
Share the signed release APK over a trusted channel (for example your own HTTPS download page). Users must allow installation from that source in Android settings
App store
Large or public deployments
Upload the .aab produced by bundle<Flavor>Release. Sign it with the upload key your store requires
Whichever route you use, serve the API over HTTPS and distribute only builds that you signed with your own keystore.
Versioning and upgrades
The app version is set in
defaultConfiginapp/build.gradle.kts(versionNamefor display andversionCodeas an integer). IncreaseversionCodefor every release you distribute; Android only installs a build with a higherversionCodethan the installed one, and it must be signed with the same key.On start-up the app asks the backend whether its
versionCodeis still accepted (POST /spice-service/static-data/app-version). The backend'sVERSION_CODEsetting is the minimum accepted code. When you publish a mandatory update, raiseVERSION_CODEonspice-serviceafter the new build is available, and older installations are blocked with a message until they update.VERSION_CHECK_EXEMPT_USERSlists usernames that skip the check.The on-device database is exported as versioned schemas and migrated on upgrade, so users keep unsynchronised data when they install a newer build. Do not change the database encryption key (see above).
Roll a new release out to a small group first and confirm sync before making it mandatory.
First launch and initial data load
Install the app on a device with network access and open it.
Sign in with a user account that exists on the server and is assigned to a facility or area. The app hashes the password with the salt and sends it to
/auth-service/session.After sign-in the app downloads the configuration it needs: user data, form definitions and metadata (the
/spice-service/static-data/...APIs), then requests an offline-sync package fromoffline-serviceand downloads the households, members and follow-ups that belong to the user. The first synchronisation is the largest; use a good connection and keep the app open until it finishes.After the initial load the app can be used without a network connection. Later changes are uploaded and downloaded by background work whenever the device is online.
The sync package is built by offline-service from the FHIR data via fhir-mapper, and it needs RabbitMQ; if the first sync never completes, check those services first. For loading existing records before go-live, see Data Import and Migration.
Verify that the app syncs with the server
Check the server is reachable from the device's network: open
https://<api-host>/spice-service/actuator/healthin the device browser and confirm it reportsUP.Sign in on a test device with a test user. A wrong server address shows as a network error; a wrong salt shows as a failed sign-in even though the password is right.
Watch the backend logs while the app starts its first sync: you should see requests to
auth-service(session),spice-service(static data) andoffline-service(sync create and status) with successful responses.When the sync finishes, open a household or a member list in the app and confirm it matches what the server holds for that user.
Switch the device to flight mode, create a record, switch the network back on and confirm that the record reaches the server (for example, it appears in the web portal or reporting application after sync).
Last updated