Firebase Basics

Firebase Android Setup Guide

Prerequisites

1. Firebase CLI: Make sure the Firebase CLI is available and authenticated.

   For detailed instructions about the Firebase CLI, see firebase_basics/references/local-env-setup. Here are high-level instructions for setting up the Firebase CLI.

   1. Ensure the Firebase CLI is available:

      Copy

      npx -y firebase-tools@latest --version

   2. Login to the CLI:

      • local:

        Copy

        npx -y firebase-tools@latest login

      • remote servers:

        Copy

        npx -y firebase-tools@latest login --no-localhost

2. Android project: Create or use an existing Android project in an Android-development IDE.

1. Check if the Android project is connected to a Firebase Project

Check if the Android project already has a google-services.json file in its module (app-level) root directory.

google-services.json file is present

If the Android project already has a google-services.json file, do NOT create a new Firebase project or re-register the app — skip steps 2 through 4 below. Instead, verify the existing Firebase setup within the codebase and fix anything that is missing:

• The google-services.json file is in the module (app-level) root directory: app/google-services.json

• The Google services Gradle plugin (google-services) is added to both the project-level and module (app-level) Gradle build files. If it is missing from either file, add it by following step 5 below.

google-services.json file is NOT present

If the Android project does NOT already have a google-services.json file, then proceed with the remaining steps in this guide.

2. Create a new Firebase project or use an existing one

Check if there's an existing Firebase Project available for use with the Android project:

npx -y firebase-tools@latest projects:list

• If existing Firebase Project: Ask the human user if they want to use the existing project.

• If no existing Firebase Project or human user does not want to use an existing project: Create a new Firebase Project.

  Provide a required unique PROJECT_ID and an optional PROJECT_DISPLAY_NAME:

  Copy

  npx -y firebase-tools@latest projects:create <UNIQUE_PROJECT_ID> --display-name <PROJECT_DISPLAY_NAME>

  Example:

  Copy

  npx -y firebase-tools@latest projects:create my-cool-app-20260330 --display-name MyCoolApp

3. Register the Android project

Register the app module (package name) of the Android project with the Firebase project. Provide an optional APP_DISPLAY_NAME and required PACKAGE_NAME:

npx -y firebase-tools@latest apps:create ANDROID <APP_DISPLAY_NAME> --package-name <PACKAGE_NAME> --project <PROJECT_ID>

Example:

npx -y firebase-tools@latest apps:create ANDROID MyApplication --package-name com.example.myapplication --project my-cool-app-20260330

NOTE: A package name is often referred to as an application ID within an Android project. Find an app's package name in the module (app-level) Gradle file, usually app/build.gradle.kts.

4. Obtain and save google-services.json

1. Fetch the Firebase configuration file (google-services.json) using the Firebase Android APP_ID (which is printed in the output of the previous apps:create command):

   Copy

   npx -y firebase-tools@latest apps:sdkconfig ANDROID <APP_ID> --project <PROJECT_ID>

2. Save the configuration file within the module (app-level) root directory of the Android project: app/google-services.json

5. Add the google-services plugin

[!IMPORTANT] [AGENT] RESOLVING THE PLUGIN VERSION DETERMINISTICALLY Never guess or hardcode a memorized out-of-date plugin version. Before adding dependencies, you MUST query the latest available versions directly from the Google Maven Repository:

Copy

# Find the latest Google services Gradle plugin version
curl -s https://dl.google.com/dl/android/maven2/com/google/gms/google-services/maven-metadata.xml | grep -oE '<latest>[^<]+' | cut -d'>' -f2

These changes are made to the Android project's Gradle files.

Project-level build.gradle.kts (<project>/build.gradle.kts)

Add the latest version of the Google services Gradle plugin to the plugins block:

plugins {
    // ... other plugins

    // [AGENT] Fetch the latest resolved version using the Gradle command above
    id("com.google.gms.google-services") version "<latest_plugin_version>" apply false
}

Module (app-level) build.gradle.kts (<project>/<app-module>/build.gradle.kts)

Add the Google services Gradle plugin to the plugins block:

plugins {
    // ... other plugins
    id("com.google.gms.google-services")
}

6. App Check (Debug Token Persistence)

When using App Check on Android emulators or local development, DebugAppCheckProviderFactory.getInstance() generates a UUID token and stores it in SharedPreferences. Wiping emulator data, clearing app storage, or fresh installs generate a new UUID in Logcat, causing debug token churn in the Firebase Console.

[!WARNING] CRITICAL: Never Hardcode or Commit Debug Tokens App Check debug tokens allow clients to bypass attestation and access backend resources without a genuine device. Never hardcode debug token strings in build.gradle.kts, Java, or Kotlin files, and never commit tokens to version control. If a token is compromised, revoke it immediately in the Firebase Console.

To persist a stable debug token across emulator resets and testing without committing secrets:

1. Obtain or generate a stable UUID debug token and register it in the Firebase Console under Security > App Check > Apps > Manage debug tokens.

2. Store the token in your project's gitignored local.properties:

   Copy

   # In local.properties (ensure this file is in your .gitignore!)
   APP_CHECK_DEBUG_TOKEN=<YOUR_DEBUG_TOKEN>

3. Inject the secret in app/build.gradle.kts for instrumentation/testing:

   Copy

   val localProperties = java.util.Properties().apply {
       val localPropertiesFile = rootProject.file("local.properties")
       if (localPropertiesFile.exists()) {
           load(localPropertiesFile.inputStream())
       }
   }
   val appCheckDebugToken = localProperties.getProperty("APP_CHECK_DEBUG_TOKEN")
       ?: System.getenv("APP_CHECK_DEBUG_TOKEN") ?: ""
   
   android {
       defaultConfig {
           // For normal emulator runs (injects into AndroidManifest)
           manifestPlaceholders["firebaseAppCheckDebugSecret"] = appCheckDebugToken
   
           // For instrumentation tests
           if (appCheckDebugToken.isNotEmpty()) {
               testInstrumentationRunnerArguments["firebaseAppCheckDebugSecret"] = appCheckDebugToken
           }
       }
   }

4. In your application or activity, install the debug provider for debug builds:

   Copy

   if (BuildConfig.DEBUG) {
       Firebase.appCheck.installAppCheckProviderFactory(
           DebugAppCheckProviderFactory.getInstance()
       )
   }

Verification plan

Manual verification

Validate that the Firebase Project was created and the Firebase Android App was registered successfully:

npx -y firebase-tools@latest projects:list
npx -y firebase-tools@latest apps:list --project <PROJECT_ID>