Installing on Device

Installing on Device

How to get THD Room Finder onto a real Android phone or iPhone.

For agent-specific install workflows (including how to use GITHUB_TOKEN), see For Agents.

---

Android

Prerequisites

• adb on your PATH (part of Android SDK Platform Tools — ships with Android Studio)
• USB debugging enabled: Settings → Developer Options → USB Debugging
• Run adb devices to confirm the phone is listed before proceeding

Install Debug APK

Simplest path — no signing required:

./gradlew installDebug

Or install a pre-built APK manually:

adb install app/build/outputs/apk/debug/app-debug.apk

Install Signed Release APK

Option A — You have keystore credentials

Load secrets and build:

set -a && source .env && set +a   # loads KEYSTORE_* variables
./gradlew assembleRelease
adb install app/build/outputs/apk/release/app-release.apk

Option B — Download from GitHub Releases

If a tagged release exists, the CI-signed APK is attached to it:

set -a && source .env && set +a   # loads GITHUB_TOKEN
gh release list --repo arudaev/THD-Room-Finder
gh release download --repo arudaev/THD-Room-Finder --pattern "*.apk" -D /tmp/release/
adb install /tmp/release/*.apk

---

INSTALL_FAILED_UPDATE_INCOMPATIBLE

What it means: the APK you're installing is signed with a different certificate than the app already on the phone. Android refuses any update where the signing key changes.

Common cause: the phone has the CI-signed release build (from GitHub Releases or TestFlight), and you're trying to install a locally-built unsigned or debug APK.

Fix 1 — Uninstall first (app data is deleted)

adb uninstall de.thd.roomfinder
adb install <your.apk>

Fix 2 — Install the matching signed APK (no data loss) Download the CI-signed release APK using Option B above. It uses the same certificate as the installed build, so Android accepts it as a normal update.

---

Useful ADB Commands

adb devices                                   # list connected devices
adb -s <serial> install <apk>                 # target a specific device by serial
adb shell pm list packages | grep roomfinder  # confirm the app is installed
adb uninstall de.thd.roomfinder               # remove the app

---

iOS

Install on Simulator

Open ios/THDRoomFinder.xcodeproj in Xcode, select an iPhone simulator, press Run (⌘R). No Apple ID or signing needed.

Sideload on a Real iPhone

1. Open the THDRoomFinder target → Signing & Capabilities
2. Set Team to your personal Apple ID (free account works)
3. If Xcode asks, append your name to the bundle ID: de.thd.roomfinder.ios.<yourname>
4. Connect your iPhone, select it in the device dropdown, press Run (⌘R)

Apps sideloaded with a free Apple ID expire after 7 days and must be re-run from Xcode to renew.

Install via TestFlight

TestFlight is the supported real-device path for testers.

1. Ask the maintainer to add your Apple ID as a tester
2. Install TestFlight from the App Store
3. Accept the invite email and install through TestFlight

TestFlight installs don't expire and receive push updates when a new release is uploaded.

---

Env Variables Quick Reference

Variable	Used for
KEYSTORE_FILE	Absolute path to the release .jks keystore
KEYSTORE_PASSWORD	Keystore store password
KEY_ALIAS	Key alias inside the keystore
KEY_PASSWORD	Key password
GITHUB_TOKEN	gh CLI authentication for downloading release APKs

Stored in .env at the repo root (not committed to git).