Firebase Android Open Source Development

This repository contains the source code for all Android Firebase SDKs except Analytics and Auth.

Firebase is an app development platform with tools to help you build, grow and monetize your app. More information about Firebase can be found at https://firebase.google.com.

Table of Contents

1. Getting Started
2. Testing
   1. Unit Testing
   2. Integration Testing
3. Annotations
   1. @Keep
   2. @KeepForSdk
   3. @PublicApi
4. Proguarding
   1. Proguard config
5. Publishing
   1. Dependencies
   2. Commands
6. Code Formatting
7. Contributing

Getting Started

• Install the latest Android Studio (should be Meerkat | 2024.3.1 or later).
• Clone the repo (git clone --recurse-submodules git@github.com:firebase/firebase-android-sdk.git).
  • When cloning the repo, it is important to get the submodules as well. If you have already cloned the repo without the submodules, you can update the submodules by running git submodule update --init --recursive.
• Import the firebase-android-sdk Gradle project into Android Studio using the Import project (Gradle, Eclipse ADT, etc.) option.
• firebase-crashlytics-ndk must be built with NDK 21. See firebase-crashlytics-ndk for more details.

Testing

Firebase Android libraries exercise all three types of tests recommended by the Android Testing Pyramid. Depending on the requirements of the specific project, some or all of these tests may be used to support changes.

⚠️ Running tests with Error Prone

To run with Error Prone, add withErrorProne to the command line, e.g.:

./gradlew :<firebase-project>:check withErrorProne.

Unit Testing

These are tests that run on your machine's local Java Virtual Machine (JVM). At runtime, these tests are executed against a modified version of android.jar where all final modifiers have been stripped off. This lets us sandbox behaviors at desired places and use popular mocking libraries.

Unit tests can be executed on the command line by running:

./gradlew :<firebase-project>:check

Integration Testing

These are tests that run on a hardware device or emulator. These tests have access to Instrumentation APIs and provide access to information such as the Android Context. In Firebase, instrumentation tests are used in different capacities by different projects. Some tests may exercise device capabilities while stubbing any calls to the backend, whereas others may call out to nightly backend builds to ensure distributed API compatibility.

Along with Espresso, they are also used to test projects that have UI components.

Project Setup

Before you can run integration tests, you need to add a google-services.json file to the root of your checkout. You can use the google-services.json from any project that includes an Android app, though you'll likely want one that's separate from any production data you have because our tests write random data.

If you don't have a suitable testing project already:

• Open the Firebase console.
• If you don't yet have a project you want to use for testing, create one.
• Add an Android app to the project.
• Give the app any package name you like.
• Download the resulting google-services.json file and put it in the root of your checkout.

Running Integration Tests on Local Emulator

Integration tests can be executed on the command line by running:

./gradlew :<firebase-project>:connectedCheck

Running Integration Tests on Firebase Test Lab

You need additional setup for this to work:

• gcloud needs to be installed on your local machine.
• gcloud needs to be configured with a project that has billing enabled.
• gcloud needs to be authenticated with credentials that have the 'Firebase Test Lab Admin' role.

Integration tests can be executed on the command line by running:

./gradlew :<firebase-project>:deviceCheck

This will execute tests on devices that are configured per project. If nothing is configured for the project, the tests will run on model=panther,version=33,locale=en,orientation=portrait.

Projects can be configured in the following way:

firebaseTestLab {
  // To get a list of available devices, execute `gcloud firebase test android models list`
  devices = [
    '<device1>',
    '<device2>',
  ]
}

Annotations

Firebase SDKs use some special annotations for tooling purposes.

@Keep

APIs that need to be preserved up until the app's runtime can be annotated with @Keep. The @Keep annotation is blessed to be honored by Android's default ProGuard configuration. This annotation is commonly used for reflection. These APIs should be generally discouraged because they can't be proguarded.

@KeepForSdk

APIs that are intended to be used by Firebase SDKs should be annotated with @KeepForSdk. The key benefit here is that the annotation is blessed to throw linter errors in Android Studio if used by the developer from a non-Firebase package, thereby providing a valuable guardrail.

@PublicApi

We annotate APIs that are meant to be used by developers with @PublicApi. This annotation will be used by tooling to help inform the version bump (major, minor, patch) that is required for the next release.

Proguarding

Firebase SDKs do not proguard themselves, but support proguarding. Firebase SDKs themselves are proguard-friendly, but the dependencies of Firebase SDKs may not be.

Proguard config

In addition to preguard.txt, projects declare an additional set of proguard rules in a proguard.txt that are honored by the developer's app while building the app's proguarded APK. This file typically contains the keep rules that need to be honored during the app's proguarding phase.

As a best practice, these explicit rules should be scoped to only libraries whose source code is outside the firebase-android-sdk codebase, making annotation-based approaches insufficient. The combination of keep rules resulting from the annotations, preguard.txt, and proguard.txt collectively determines the APIs that are preserved at runtime.

Publishing

Firebase is published as a collection of libraries, each of which either represents a top-level product or contains shared functionality used by one or more projects. The projects are published as managed Maven artifacts available at Google's Maven Repository. This section explains how developers can make changes to Firebase projects and have their apps depend on the modified versions of Firebase.

Dependencies

Any dependencies within the projects or outside of Firebase are encoded as Maven dependencies into the pom file that accompanies the published artifact. This allows the developer's build system (typically Gradle) to build a dependency graph and select the dependencies using its own resolution strategy.

Commands

For more advanced use cases where developers wish to make changes to a project but have transitive dependencies point to publicly released versions, individual projects may be published as follows:

# e.g. to publish Firestore and Functions
./gradlew -PprojectsToPublish="firebase-firestore,firebase-functions" \
    publishReleasingLibrariesToMavenLocal

Developers can depend on these locally published versions by adding the mavenLocal() repository to the repositories block in their app module's build.gradle.

Code Formatting

Java and Kotlin are both formatted using spotless.

To run formatting on a project, run:

./gradlew :<firebase-project>:spotlessApply

Contributing

We love contributions! Please read our contribution guidelines to get started.