Android release builds
Build and sign the bundle we upload to Google Play, or an APK to install directly, on your own machine. For maintainers, and for anyone building their own version.
Google Play takes an Android App Bundle (.aab) signed with the app's upload key. We build it locally with expo prebuild and Gradle. No Expo account or build service is involved, and the key never leaves the machine that builds it.
What you need
- The Android SDK and Java 17, as in Development setup.
- The upload keystore and its password.
Google only accepts bundles signed with the upload key. If the key or its password is lost, a maintainer has to ask Google for an upload key reset, which takes a few days.
Create an upload key
Skip this if you already have the keystore.
keytool -genkeypair -v -storetype PKCS12 -keystore ~/keys/openbeacon-upload.jks -alias openbeacon-upload -keyalg RSA -keysize 2048 -validity 10000The name and organisation it asks for aren't shown to anyone, because Google re-signs the app with its own app signing key before it reaches phones.
To register a new key with Google, during setup or an upload key reset, export its certificate and upload the .pem file in Play Console:
keytool -export -rfc -keystore ~/keys/openbeacon-upload.jks -alias openbeacon-upload -file ~/keys/openbeacon-upload.pemPoint the build at the key
Keep the keystore outside the repository. Release builds read where it is from apps/mobile/credentials.json, which is gitignored because it holds the password.
cp apps/mobile/credentials.json.example apps/mobile/credentials.json| Field | What to put |
|---|---|
keystorePath | Absolute path to the .jks file. |
keystorePassword | The keystore password. |
keyAlias | The alias the key was created with. |
keyPassword | The key password. For a PKCS12 keystore, like the one above, this is the keystore password. |
To keep the file somewhere else, for example in CI, set ORG_GRADLE_PROJECT_openbeaconCredentials to its path. A relative path is read from apps/mobile.
Set the environment
The build reads apps/mobile/.env, like a development build. Set EXPO_PUBLIC_GOOGLE_WEB_CLIENT_ID there. Release builds ignore EXPO_PUBLIC_DEV_API_URL, so a development server never ends up in a release.
Push notifications
The app wakes up for place alerts and notices through Firebase Cloud Messaging. Copy four values from the Firebase project's google-services.json into apps/mobile/.env. Don't commit the file or put it in the build.
| Variable | Value in google-services.json |
|---|---|
FIREBASE_APP_ID | client[0].client_info.mobilesdk_app_id |
FIREBASE_API_KEY | client[0].api_key[0].current_key |
FIREBASE_PROJECT_ID | project_info.project_id |
FIREBASE_SENDER_ID | project_info.project_number |
The plugins/withFirebasePush.js config plugin writes them into the app at prebuild, and the app starts Firebase from them. If any of the four is missing, it writes none of them and the app runs without push. Phones then get alerts and notices on their next upload instead. Development builds read the same .env, so they get push too when the values are there.
The app doesn't use the google-services Gradle plugin, Firebase Analytics or Firebase's automatic start-up. It only asks Firebase for a token once its server says it sends pushes, so phones on a server without push never contact Firebase.
HTTPS
Development builds can use an http:// backend, but release builds only connect over https:// with a certificate Android trusts. To test a release build against your own backend, serve it over HTTPS.
Build the bundle
Every upload needs a higher android.versionCode than any bundle Play has seen, including ones that were never released. Every pull request that changes the app already bumps it. See Versions and releases.
From the repository root or apps/mobile:
bun run build-aabBefore the slow part starts, the build stops if:
- there are uncommitted changes, because they would end up in the release;
EXPO_PUBLIC_GOOGLE_WEB_CLIENT_IDisn't set;- any of the four Firebase values isn't set, because the release would have no push;
credentials.jsonis missing or incomplete, or the keystore doesn't open with its password;keyPassworddiffers fromkeystorePasswordin a PKCS12 keystore.
It then generates the Prisma client, regenerates android/ with expo prebuild --clean, and runs ./gradlew bundleRelease. The bundle is saved as apps/mobile/openbeacon-<version>-<versionCode>.aab. Regenerating android/ throws away any edits in it.
The build prints the SHA1 of the key it signed with. Check it matches the upload key certificate in Play Console, under Protected with Play › Play Store protection › Manage Play app signing.
For a test build you won't upload, bun run build-aab --allow-dirty includes uncommitted changes.
Upload
Upload the bundle in Play Console, usually to Internal testing first.
Build an APK
To install a release build directly onto a phone without Google Play, build an APK instead. From the repository root or apps/mobile:
bun run build-apkIt signs with the key in credentials.json and runs the same checks as build-aab, including --allow-dirty, except that missing Firebase values only print a warning and the APK is built without push. It also needs apksigner from the Android SDK build tools in ANDROID_HOME to check the signature. The APK is saved as apps/mobile/openbeacon-<version>-<versionCode>.apk. Install it with:
adb install -r apps/mobile/openbeacon-<version>-<versionCode>.apkadb install -r refuses an APK with a lower versionCode than the copy already on the phone.
A copy installed from Google Play is signed with Google's app signing key, so the APK can't be installed over it. Remove it first with adb uninstall net.openbeacon.app, which deletes the app's data on that phone.
To check an APK's signature yourself, use apksigner verify --print-certs on it. keytool can't read an APK's signature.
Code shrinking
Release builds run R8, which removes unused code and renames classes. Debug builds don't, so test a release build after adding or upgrading a native library. If a library breaks only in release builds, usually with ClassNotFoundException in adb logcat, add keep rules to extraProguardRules under expo-build-properties in apps/mobile/app.json.
Build your own version
Anyone can build and sign OpenBeacon with their own key. To publish it on Google Play separately from us, you also need:
- your own package name, in
android.packageinapps/mobile/app.json, because a package name belongs to one Play developer; - your own upload key;
- your own Firebase project, if you want push. Register your package name in it and set the four Firebase values from its
google-services.json. Your server then needs a service account key from the same project, in theFCM_*environment variables. Without one, build an APK and the app works without push.
A build you only install yourself can keep our package name, but it can't be installed over the Play Store version. Either way, the app uses our hosted server until you choose another one.