The Blue Alliance - Android App

An Android app for accessing information about the FIRST Robotics Competition. This is the native Android client for The Blue Alliance.

Available on the Google Play Store.

Alpha Testing

We publish pre-release builds to a closed alpha track on Google Play. To join, request access to the thebluealliance-android-alpha Google Group, then opt in to the alpha on the Play Store listing.

Get Involved

The Blue Alliance is built by volunteers. We'd love your help!

• Chat with us on Slack (request an invite on the mailing list)
• Report bugs or request features on the issue tracker
• Contribute code by forking the repo, making changes on a branch, and opening a pull request

Tech Stack

Kotlin, Jetpack Compose (Material 3), Hilt, Room, Retrofit, Firebase.

First-time setup

Fresh clone to running app in three steps.

1. Prerequisites

• Android Studio — on first open of the project, Gradle sync installs the required SDK components for you.
• JDK 17 — bundled with Android Studio (jbr/). If you build from the CLI without Android Studio, install one separately (brew install openjdk@17 on macOS).

2. Clone and stub google-services.json

git clone https://github.com/the-blue-alliance/the-blue-alliance-android.git
cd the-blue-alliance-android
cp  app/src/debug/google-services.json.example  app/src/debug/google-services.json
cp wear/src/debug/google-services.json.example wear/src/debug/google-services.json

You don't need a real Firebase project or a local.properties file for the first build — the stubs are enough, and Gradle falls back to sane defaults for everything else.

3. Open in Android Studio and run

Open the cloned directory in Android Studio. It will download Gradle, the Android SDK platform, and build tools on first sync (takes a few minutes). Then Tools → Device Manager → Create Device to make an emulator (any recent Phone AVD), select it in the run target dropdown, and hit the green ▶ button.

The app will launch with empty lists because no data source is connected yet — see Connecting to data below.

Connecting to data

After the first build succeeds, pick one of these to see real content.

Option A: Point at the production API (simplest)

Copy the template and edit:

cp local.properties.example local.properties

Then uncomment and fill in:

tba.url.debug=https://www.thebluealliance.com/
tba.api.key.debug=YOUR_KEY_HERE

Get an API key from the TBA Account page. Rebuild and you'll see real events, teams, and matches.

Option B: Run the local backend (for backend development)

The Android debug build defaults to http://10.0.2.2:8080/ (the emulator's alias for the host's localhost), which is where the TBA server runs inside its Docker Compose stack. Follow the setup instructions in the TBA backend repository to start it; once Docker Compose is running, rebuild the Android app and you'll see local data.

The Docker Compose stack includes a Firebase Auth emulator, and debug builds of the Android app are wired to it in AuthModule — so Google Sign-In works against the local backend with the stub google-services.json alone. No real Firebase project needed.

On Android 17 (API 37): the debug build's 10.0.2.2 dev server is on a local network (10.0.0.0/8), which Android 17 gates behind the runtime ACCESS_LOCAL_NETWORK permission (the debug manifest declares it, but as a dangerous permission it isn't auto-granted). scripts/install-and-launch.sh and scripts/emu launch grant it for you; only if you launch straight from Android Studio's ▶ button do you need to grant it once:

adb shell pm grant com.thebluealliance.androidclient.development android.permission.ACCESS_LOCAL_NETWORK

Firebase project (optional)

Only needed if you want to test Google Sign-In or push notifications against production. For local development the stub google-services.json is enough.

To set up a real project:

1. Create a project in the Firebase console.
2. Add an Android app with package name com.thebluealliance.androidclient.development.
3. Add your debug signing SHA-1 fingerprint (instructions).
4. Download the real google-services.json and overwrite app/src/debug/google-services.json.

Code quality

The project enforces formatting and Android Lint in CI via ci-lint.yaml.

Formatting (ktlint)

./gradlew ktlintCheck    # fail on any violation
./gradlew ktlintFormat   # auto-fix what it can

Install the pre-commit hook once to catch formatting issues before they reach CI:

./gradlew addKtlintCheckGitPreCommitHook

Android Lint

./gradlew :app:lintDebug
./gradlew :wear:lintDebug
./gradlew :tv:lintDebug

Testing

./gradlew :app:testDebugUnitTest
./gradlew :tv:testDebugUnitTest