Firebase Android Open Source Development

This repository contains a subset of the Firebase Android SDK source. Itcurrently includes the following Firebase libraries, and some of theirdependencies:

• firebase-abt
• firebase-common
• firebase-common-ktx
• firebase-crashlytics
• firebase-crashlytics-ktx
• firebase-crashlytics-ndk
• firebase-database
• firebase-database-ktx
• firebase-database-collection
• firebase-datatransport
• firebase-firestore
• firebase-firestore-ktx
• firebase-functions
• firebase-functions-ktx
• firebase-inappmessaging
• firebase-inappmessaging-ktx
• firebase-inappmessaging-display
• firebase-inappmessaging-display-ktx
• firebase-perf
• firebase-perf-ktx
• firebase-remote-config
• firebase-remote-config-ktx
• firebase-storage
• firebase-storage-ktx

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

Table of contents

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

Getting Started

• Install the latest Android Studio (should be 3.0.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. Ifyou have already cloned the repo without the submodules, you can update thesubmodules by running git submodule update --init --recursive.
• Import the firebase-android-sdk gradle project into Android Studio using theImport project(Gradle, Eclipse ADT, etc.) option.
• firebase-crashlytics-ndk must be built with NDK 21. Seefirebase-crashlytics-ndk for moredetails.

Testing

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 thesetests may be used to support changes.

⚠️ Running tests with errorprone

To run with errorprone 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). Atruntime, these tests are executed against a modified version of android.jarwhere all final modifiers have been stripped off. This lets us sandbox behaviorsat 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 haveaccess to Instrumentation APIs, give you access to information such as theAndroid Context.In Firebase, instrumentation tests are used at different capacities by differentprojects. Some tests may exercise device capabilities, while stubbing any callsto the backend, while some others may call out to nightly backend builds toensure distributed API compatibility.

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

Project Setup

Before you can run integration tests, you need to add a google-services.jsonfile to the root of your checkout. You can use the google-services.json fromany project that includes an Android App, though you'll likely want one that'sseparate 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 ofyour 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 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 on model=Pixel2,version=27,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@Keepannotation is blessed to be honored by android's default proguardconfiguration. A common use forthis annotation is because of reflection. These APIs should be generally discouraged, becausethey 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 throwlinter errors on Android Studio if used by the developer from a non firebasepackage, thereby providing a valuable guard rail.

@PublicApi

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.

Proguarding

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

Proguard config

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

As a best practice, these explicit rules should be scoped to only librarieswhose source code is outside the firebase-android-sdk codebase making annotationbased approaches insufficient.The combination of keep rules resulting from theannotations, the preguard.txt and the proguard.txt collectively determine theAPIs that are preserved at runtime.

Publishing

Firebase is published as a collection of libraries each of which eitherrepresents a top level product, or contains shared functionality used by one ormore projects. The projects are published as managed maven artifacts availableat Google's Maven Repository. This section helpsreason about how developers may make changes to firebase projects and have theirapps depend on the modified versions of Firebase.

Dependencies

Any dependencies, within the projects, or outside of Firebase are encoded asmaven dependenciesinto the pom file that accompanies the published artifact. This allows thedeveloper's build system (typically Gradle) to build a dependency graph andselect the dependencies using its own resolutionstrategy

Commands

The simplest way to publish a project and all its associated dependencies is tojust publish all projects. The following command builds SNAPSHOT dependencies ofall projects. All pom level dependencies within the published artifacts willalso point to SNAPSHOT versions that are co-published.

./gradlew publishAllToLocal

Developers may take a dependency on these locally published versions by addingthe mavenLocal() repository to your repositoriesblock inyour app module's build.gradle.

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

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

Code Formatting

Code in this repo is formatted with the google-java-format tool. You can enablethis formatting in Android Studio by downloading and installing thegoogle-java-format plugin.The plugin is disabled by default, but the repo contains configuration informationand links to additional plugins.

To run formatting on your entire project you can run

./gradlew :<firebase-project>:googleJavaFormat

Contributing

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