Installation
Get the Kotlin Android template building and running in an emulator or on a device.
This guide takes you from a fresh clone to the app running from Android Studio or the Gradle command line.
The app is designed to build and boot with zero service keys. Add
local.properties values later as you connect Supabase, RevenueCat, FCM,
PostHog, Sentry, Play release signing, and app links.
Prerequisites
- Android Studio Meerkat or newer. The template uses AGP 9.2.1, Kotlin 2.3.0, KSP 2.3.9, and Gradle wrapper 9.4.1.
- JDK 17+. Use Android Studio's bundled JDK unless your local toolchain is already pinned.
- An API 26+ emulator or Android device. A Play-services emulator image is recommended because FCM, Play In-App Updates, Play In-App Review, and purchase testing depend on Google Play services.
- A Google Play developer account only when you are testing real Play Billing or preparing a Play release.
Setup
Clone the template
git clone <repo-url>
cd soar-kotlinOpen it in Android Studio
Open the repository root, not just the app/ folder. Let Gradle sync finish so
Android Studio resolves Compose, Hilt, Supabase, Firebase, RevenueCat, PostHog,
Sentry, and Play Core dependencies.
Optional: fill local.properties
Android Studio usually creates sdk.dir automatically. The service keys are
optional for a first run:
sdk.dir=/path/to/Android/sdk
SUPABASE_URL=https://your-project-ref.supabase.co
SUPABASE_PUBLISHABLE_KEY=your_publishable_key
GOOGLE_WEB_CLIENT_ID=your_google_oauth_web_client_id
REVENUECAT_ANDROID_KEY=your_public_revenuecat_android_keyEvery missing string key is read as an empty BuildConfig value. See
Configuration for the full key reference.
Run the app
Select the app run configuration and an emulator or device, then press
Run. With no backend keys, the app still reaches the onboarding / consent /
login flow and the local Component gallery can render offline.
Command-line equivalents
The template's Gradle commands are:
# Debug build
./gradlew assembleDebug
# Install on a connected emulator or device
./gradlew installDebug
# Unit tests
./gradlew testDebugUnitTest
# Instrumented tests; requires a connected emulator or device
./gradlew connectedDebugAndroidTest
# Android lint for the debug variant
./gradlew lintDebug
# Release App Bundle; signing keys are read from local.properties
./gradlew bundleReleaseLaunch an installed debug build from the command line:
adb shell am start -n com.soarstarter.kotlin/.MainActivityVerify the installation
With no service keys configured, confirm the app gets through its local launch surfaces:
- The app installs and launches without a crash.
- Onboarding appears and can be completed.
- The legal consent gate appears and can be accepted.
- The login screen renders. The Google button is hidden until
GOOGLE_WEB_CLIENT_IDis set. - The Component tab works offline because it renders local Compose demos.
Auth, todos, profile, uploads, subscriptions, and push need backend setup. Go to Supabase Setup after the app boots locally.
Common first-run failures
| Symptom | Likely cause | Fix |
|---|---|---|
| Gradle sync cannot find AGP or Kotlin plugins | Old Android Studio or stale Gradle cache | Update Android Studio, then sync again from the project root |
JAVA_HOME / toolchain errors | JDK below 17 or Android Studio using the wrong JDK | Point Gradle to Android Studio's bundled JDK 17+ |
sdk.dir missing | local.properties was not created | Open once in Android Studio or add sdk.dir=/path/to/Android/sdk |
| FCM, updates, review, or Billing flows do not work on the emulator | The emulator image lacks Play services or the app was not installed through Play | Use a Play-services image; real purchase and update flows need Play delivery |
| Google Sign-In button is absent | GOOGLE_WEB_CLIENT_ID is empty | Add the OAuth web client ID to local.properties and configure the Google provider in Supabase |
| KSP / Kotlin dependency mismatch | Versions were changed independently | Keep the template pins together: Kotlin 2.3.0, KSP 2.3.9, supabase-kt 3.2.6, Ktor 3.3.1 |