Repository files navigation

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 athttps://firebase.google.com.

1. Getting Started
2. Testing
   1. Unit Testing
   2. Integration Testing
3. Proguarding
   1. APIs used via reflection
   2. APIs intended for developer consumption
   3. APIs intended for other Firebase SDKs
4. Publishing
   1. Dependencies
   2. Commands
5. Code Formatting
6. Contributing

• 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 clonedthe repo without the submodules, you can update the submodules by runninggit submodule update --init --recursive.
• Import the firebase-android-sdk gradle project into Android Studio using theImportproject(Gradle, Eclipse ADT, etc.) option.
• firebase-crashlytics-ndk must be built with NDK 21. Seefirebase-crashlytics-ndk for more details.

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

⚠️Running tests with errorprone

To run with errorprone addwithErrorProne to the command line, e.g.

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

These are tests that run on your machine's local Java Virtual Machine (JVM). At runtime, these testsare executed against a modified version of android.jar where all final modifiers have been strippedoff. 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

These are tests that run on a hardware device or emulator. These tests have access toInstrumentation APIs, give you access to information such as theAndroid Context. In Firebase,instrumentation tests are used at different capacities by different projects. Some tests mayexercise device capabilities, while stubbing any calls to the backend, while some others may callout to nightly backend builds to ensure distributed API compatibility.

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

Before you can run integration tests, you need to add agoogle-services.json file to the root ofyour checkout. You can use thegoogle-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 testswrite random data.

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

• Open theFirebase 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 resultinggoogle-services.json file and put it in the root of your checkout.

Integration tests can be executed on the command line by running

./gradlew :<firebase-project>:connectedCheck

You need additional setup for this to work:

• gcloud needs to beinstalled on local machine
• gcloud needs to be configured with a project that has billing enabled
• gcloud needs to be authenticated with credentials that have '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 theproject, the tests will run onmodel=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>',  ]}

Firebase SDKs use some special annotations for tooling purposes.

APIs that need to be preserved up until the app's runtime can be annotated with@Keep. The@Keep annotation isblessed to be honored by android'sdefault proguard configuration. Acommon use for this annotation is because of reflection. These APIs should be generallydiscouraged, because they can't be proguarded.

APIs that are intended to be used by Firebase SDKs should be annotated with@KeepForSdk. The keybenefit here is that the annotation isblessed to throw linter errors on Android Studio if used bythe developer from a non firebase package, thereby providing a valuable guard rail.

We annotate APIs that meant to be used by developers with@PublicAPI. Thisannotation will be used by tooling to help inform the version bump (major, minor, patch) that isrequired for the next release.

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

In addition to preguard.txt, projects declare an additional set of proguard rules in a proguard.txtthat are honored by the developer's app while building the app's proguarded apk. This file typicallycontains 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 isoutside the firebase-android-sdk codebase making annotation based approaches insufficient.Thecombination of keep rules resulting from the annotations, the preguard.txt and the proguard.txtcollectively determine the APIs that are preserved atruntime.

Firebase is published as a collection of libraries each of which either represents a top levelproduct, or contains shared functionality used by one or more projects. The projects are publishedas managed maven artifacts available atGoogle's Maven Repository. Thissection helps reason about how developers may make changes to firebase projects and have their appsdepend on the modified versions of Firebase.

Any dependencies, within the projects, or outside of Firebase are encoded asmaven dependenciesinto thepom file that accompanies the published artifact. This allows the developer's buildsystem (typically Gradle) to build a dependency graph and select the dependencies using its ownresolution strategy

For more advanced use cases where developers wish to make changes to a project, but have transitivedependencies 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 may take a dependency on these locally published versions by adding themavenLocal()repository to yourrepositories block in yourapp module's build.gradle.

Java and Kotlin are both formatted usingspotless.

To run formatting on a project, run

./gradlew :<firebase-project>:spotlessApply

We love contributions! Please read ourcontribution guidelines to get started.