FirebaseUI for Android — UI Bindings for Firebase
FirebaseUI is an open-source library for Android that allows you to quickly connect common UI elements to the Firebase database for data storage, allowing views to be updated in realtime as they change, providing simple interfaces for common tasks like displaying lists or collections of items, and displaying prompts for user authentication.
A compatible FirebaseUI client is also available for iOS.
Table of Content
- Installation
- Using FirebaseUI for Authentication
- Using FirebaseUI to Populate a ListView
- Using FirebaseUI to Populate a RecyclerView
- Contributing
Installation
If your Android app already uses Firebase, you have added a dependency to the Firebase SDK to your dependencies. In this step we'll add the FirebaseUI library as another dependency.
You can also add the library dependency directly to your app's gradle.build file:
dependencies {
compile 'com.firebaseui:firebase-ui:0.3.1'
}
After the project is synchronized, we're ready to start using Firebase functionality in our app.
Using FirebaseUI for Authentication
FirebaseUI has a built-in dialog that you can use pop up to allow your users to log in.
To use FirebaseUI to authenticate users we need to do a few things:
- Add SDK dependencies
- Add Facebook/Twitter/Google keys to strings.xml
- Change our AndroidManifest.xml
- Inherit from FirebaseLoginBaseActivity
- Enable authentication providers
- Call showFirebaseLoginDialog();
We'll go into each of these steps below.
Add SDK dependencies
Since FirebaseUI depends on the SDKs of various providers, we'll need to include those in our dependencies as well.
dependencies {
...
compile 'com.facebook.android:facebook-android-sdk:4.6.0'
compile 'com.google.android.gms:play-services-auth:8.3.0'
compile 'org.twitter4j:twitter4j-core:4.0.2'
}
Add Facebook/Twitter/Google keys
Open your application's res/values/strings.xml
file and add the following lines, replacing [VALUE]
with your key.
Keep in mind, these are all optional. You only have to provide values for the providers you plan to use.
FirebaseLoginBaseActivity.java
.
<string name="facebook_app_id">[VALUE]</string>
<string name="twitter_app_key">[VALUE]</string>
<string name="twitter_app_secret">[VALUE]</string>
If you're using Google authentication, place your google-services.json
in the app folder.
Change our AndroidManifest.xml
Open your manifests/AndroidManifest.xml
file. This will allow Android to recognize the various activities that FirebaseUI exposes.
First though, double check that you've requested the INTERNET
permission in your <manifest>
tag.
<uses-permission android:name="android.permission.INTERNET"></uses-permission>
If you're using Twitter authentication, add the following to your <application>
tag.
<!-- Twitter Configuration -->
<activity android:name="com.firebase.ui.auth.twitter.TwitterPromptActivity" />
<meta-data
android:name="com.firebase.ui.TwitterKey"
android:value="@string/twitter_app_key"/>
<meta-data
android:name="com.firebase.ui.TwitterSecret"
android:value="@string/twitter_app_secret"/>
If you're using Facebook authentication, add the following to your <application>
tag.
<!-- Facebook Configuration -->
<activity
android:name="com.facebook.FacebookActivity"
android:configChanges="keyboard|keyboardHidden|screenLayout|screenSize|orientation"
android:label="@string/app_name"
android:theme="@android:style/Theme.Translucent.NoTitleBar" />
<meta-data
android:name="com.facebook.sdk.ApplicationId"
android:value="@string/facebook_app_id" />
Inherit from FirebaseLoginBaseActivity
Now we get to the juicy bits. Open your MainActivity
and change your activity to extend FirebaseLoginBaseActivity
public class MainActivity extends FirebaseLoginBaseActivity {
...
}
This activity should implement a few methods so your application can react to changing authentication state.
public class MainActivity extends FirebaseLoginBaseActivity {
...
@Override
public Firebase getFirebaseRef() {
// TODO: Return your Firebase ref
}
@Override
public void onFirebaseLoginProviderError(FirebaseLoginError firebaseError) {
// TODO: Handle an error from the authentication provider
}
@Override
public void onFirebaseLoginUserError(FirebaseLoginError firebaseError) {
// TODO: Handle an error from the user
}
}
In addition you can override these methods to customize what happens when a user logs in or out:
@Override
public void onFirebaseLoggedIn(AuthData authData) {
// TODO: Handle successful login
}
@Override
public void onFirebaseLoggedOut() {
// TODO: Handle logout
}
If you want to know the current AuthData
at any point, you can call getAuth()
. This will return the AuthData
for the currently authenticated user, or null
if no user is authenticated.
Enable Authentication Providers
Now that our activity is set up, we can enable authentication providers. The FirebaseUI login prompt will only display providers you enable here, so don't worry if you don't want to use them all!
public class MainActivity extends FirebaseLoginBaseActivity {
...
@Override
protected void onStart() {
super.onStart();
// All providers are optional! Remove any you don't want.
setEnabledAuthProvider(AuthProviderType.FACEBOOK);
setEnabledAuthProvider(AuthProviderType.TWITTER);
setEnabledAuthProvider(AuthProviderType.GOOGLE);
setEnabledAuthProvider(AuthProviderType.PASSWORD);
}
Call showFirebaseLoginPrompt();
You're now ready to display the login dialog!
Simply call showFirebaseLoginPrompt()
from within your activity and you'll see the dialog!
For example, if we had a mLoginButton, we could display the dialog when the user clicks the button.
mLoginButton.setOnClickListener(new View.OnClickListener() {
@Override
public void onClick(View view) {
showFirebaseLoginPrompt();
}
});
Using FirebaseUI to Populate a ListView
To use the FirebaseUI to display Firebase data, we need to do a few things:
- Create a class to represent the properties of our objects, as they are stored into the database
- Create a custom list adapter to map from Firebase to Android
Creating a model class
In your app, create a class that represents the data from Firebase that you want to show in the ListView.
So say we have these chat messages in our Firebase database:
We can represent a chat message with this Java class:
public class ChatMessage {
String message;
String name;
public ChatMessage() {
}
public ChatMessage(String name, String message) {
this.message = message;
this.name = name;
}
public String getMessage() {
return message;
}
public String getName() {
return name;
}
}
A few things to note here:
- the field have the exact same name as the properties in Firebase. This allows Firebase to automatically map the properties to these fields.
- there is a default (parameterless constructor) that is necessary for Firebase to be able to create a new instance of this class
- there is a convenience constructor that takes the member fields, so that we easily create a fully initialized
ChatMessage
in our app - the
getMessage
andgetName
methods are so-called getters and follow a JavaBean pattern
A little-known feature of Firebase for Android is that you can pass an instance of this ChatMessage
class to setValue()
:
Firebase ref = new Firebase("https://nanochat.firebaseio.com/");
ChatMessage msg = new ChatMessage("puf", "Hello FirebaseUI world!");
ref.push().setValue(msg);
The Firebase Android client will read the values from the msg
and write them into the properties of the new child in the database.
Conversely, we can read a ChatMessage
straight from a DataSnapshot
in our event handlers:
ref.limitToLast(5).addValueEventListener(new ValueEventListener() {
@Override
public void onDataChange(DataSnapshot snapshot) {
for (DataSnapshot msgSnapshot: snapshot.getChildren()) {
ChatMessage msg = msgSnapshot.getValue(ChatMessage.class);
Log.i("Chat", chat.getName()+": "+chat.getMessage());
}
}
@Override
public void onCancelled(FirebaseError firebaseError) {
Log.e("Chat", "The read failed: " + firebaseError.getMessage());
}
});
In the above snippet we have a query for the last 5 chat messages. Whenever those change (i.e. when an new message is added)
we get the ChatMessage
objects from the DataSnapshot
with getValue(ChatMessage.class)
. The Firebase Android client will
then read the properties that it got from the database and map them to the fields of our ChatMessage
class.
But when we build our app using FirebaseUI, we often won't need to register our own EventListener. The
FirebaseListAdapter
takes care of that for us.
Find the ListView
We'll assume you've already added a ListView
to your layout and have looked it up in the onCreate
method of your activity:
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_main);
ListView messagesView = (ListView) findViewById(R.id.messages_list);
}
Connect to Firebase
First we'll tell Firebase that we intend to use it in this activity and set up a reference to the database of chat message.
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_main);
ListView messagesView = (ListView) findViewById(R.id.messages_list);
Firebase.setAndroidContext(this);
Firebase ref = new Firebase("https://nanochat.firebaseio.com");
}
Create custom FirebaseListAdapter subclass
Next, we need to create a subclass of the FirebaseListAdapter
with the correct parameters and implement its populateView
method:
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_main);
ListView messagesView = (ListView) findViewById(R.id.messages_list);
Firebase.setAndroidContext(this);
Firebase ref = new Firebase("https://nanochat.firebaseio.com");
mAdapter = new FirebaseListAdapter<ChatMessage>(this, ChatMessage.class, android.R.layout.two_line_list_item, ref) {
@Override
protected void populateView(View view, ChatMessage chatMessage, int position) {
((TextView)view.findViewById(android.R.id.text1)).setText(chatMessage.getName());
((TextView)view.findViewById(android.R.id.text2)).setText(chatMessage.getMessage());
}
};
messagesView.setAdapter(mAdapter);
}
In this last snippet we create a subclass of FirebaseListAdapter
.
We tell is that it is of type <ChatMessage>
, so that it is a type-safe collection. We also tell it to use
ChatMessage.class
when reading messages from the database. Next we say that each message will be displayed in
a android.R.layout.two_line_list_item
, which is a built-in layout in Android that has two TextView
elements
under each other. Then we say that the adapter belongs to this
activity and that it needs to monitor the
data location in ref
.
We also have to override the populateView()
method, which is abstract in the FirebaseListAdapter
. The
FirebaseListAdapter
will call our populateView
method for each ChatMessage
it finds in the database.
It passes us the ChatMessage
and a View
, which is an instance of the android.R.layout.two_line_list_item
we specified in the constructor. So what we do in our subclass is map the fields from chatMessage
to the
correct TextView
controls from the view
. The code is a bit verbose, but hey... that's Java and Android for you.
Clean up When the Activity is Destroyed
Finally, we need to clean up after ourselves. When the activity is destroyed, we need to call cleanup()
on the ListAdapter
so that it can stop listening for changes in the Firebase database.
@Override
protected void onDestroy() {
super.onDestroy();
mAdapter.cleanup();
}
Send Chat Messages
Remember when we showed how to use the ChatMessage
class in setValue()
.
We can now use that in our activity to allow sending a message:
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_main);
ListView messagesView = (ListView) findViewById(R.id.messages_list);
Firebase.setAndroidContext(this);
Firebase ref = new Firebase("https://nanochat.firebaseio.com");
mAdapter = new FirebaseListAdapter<ChatMessage>(this, ChatMessage.class, android.R.layout.two_line_list_item, ref) {
@Override
protected void populateView(View view, ChatMessage chatMessage, int position) {
((TextView)view.findViewById(android.R.id.text1)).setText(chatMessage.getName());
((TextView)view.findViewById(android.R.id.text2)).setText(chatMessage.getMessage());
}
};
messagesView.setAdapter(mAdapter);
final EditText mMessage = (EditText) findViewById(R.id.message_text);
findViewById(R.id.send_button).setOnClickListener(new View.OnClickListener() {
@Override
public void onClick(View v) {
mRef.push().setValue(new ChatMessage("puf", mMessage.getText().toString()));
mMessage.setText("");
}
});
}
@Override
protected void onDestroy() {
super.onDestroy();
mAdapter.cleanup();
}
You're done! You now have a minimal, yet fully functional, chat app in about 30 lines of code. Not bad, right?
Using FirebaseUI to Populate a RecyclerView
RecyclerView is the new preferred way to handle potentially long lists of items. Since Firebase collections
can contain many items, there is an FirebaseRecyclerAdapter
too. Here's how you use it:
- Create a custom ViewHolder class
- Create a custom subclass FirebaseListAdapter
The rest of the steps is the same as for the FirebaseListAdapter
above, so be sure to read that first.
Create a custom ViewHolder
A ViewHolder is similar to container of a ViewGroup that allows simple lookup of the sub-views of the group.
If we use the same layout as before (android.R.layout.two_line_list_item
), there are two TextView
s in there.
We can wrap that in a ViewHolder with:
public static class ChatMessageViewHolder extends RecyclerView.ViewHolder {
TextView messageText;
TextView nameText;
public ChatMessageViewHolder(View itemView) {
super(itemView);
nameText = (TextView)itemView.findViewById(android.R.id.text1);
messageText = (TextView) itemView.findViewById(android.R.id.text2);
}
}
There's nothing magical going on here; we're just mapping numeric IDs and casts into a nice, type-safe contract.
Create a custom FirebaseRecyclerAdapter
Just like we did for FirebaseListAdapter
, we'll create an anonymous subclass for our ChatMessages, but this time we'll use FirebaseRecyclerAdapter
:
RecyclerView recycler = (RecyclerView) findViewById(R.id.messages_recycler);
recycler.setHasFixedSize(true);
recycler.setLayoutManager(new LinearLayoutManager(this));
mAdapter = new FirebaseRecyclerAdapter<ChatMessage, ChatMessageViewHolder>(ChatMessage.class, android.R.layout.two_line_list_item, ChatMessageViewHolder.class, mRef) {
@Override
public void populateViewHolder(ChatMessageViewHolder chatMessageViewHolder, ChatMessage chatMessage, int position) {
chatMessageViewHolder.nameText.setText(chatMessage.getName());
chatMessageViewHolder.messageText.setText(chatMessage.getMessage());
}
};
recycler.setAdapter(mAdapter);
Like before, we get a custom RecyclerView populated with data from Firebase by setting the properties to the correct fields.
Clean up When the Activity is Destroyed
Just like in the ListAdapter
example, we need to clean up after ourselves. Call cleanup()
on the RecyclerAdapter
so that it can stop listening for changes in the Firebase database.
@Override
protected void onDestroy() {
super.onDestroy();
mAdapter.cleanup();
}
Contributing
Installing locally
We are still working on deploying FirebaseUI to Maven Central. In the meantime, you can download the latest release from the Releases tab on the Github repo and install it into your local Maven repository with:
mvn install:install-file -Dfile=/path/to/library-debug.aar -DgroupId=com.firebaseui -DartifactId=firebase-ui -Dversion=0.1.0 -Dpackaging=aar
Deployment
To get the build server ready to build FirebaseUI-Android
- Install a JDK (if it's not installed yet):
sudo apt-get install default-jdk
- Run
./gradlew
(which will install gradle if it's not yet installed) - Install the Android SDK tool for Linux
wget http://dl.google.com/android/android-sdk_r22.0.5-linux.tgz
tar -xvzf android-sdk_r22.0.5-linux.tgz
- Add the android SDK path to
.bashrc
: export ANDROID_HOME=~/android-sdk-linux/
export PATH=$PATH:~/android-sdk-linux/tools
- Install the Android SDK needed for FirebaseUI
android update sdk -u
android list sdk --all
android update sdk -u --all --filter platform-tools,android-22,extra-android-support
android update sdk --no-ui --filter extra
- The Android aapt tool is 32-bit only. If the machine is 64-bit, we'll need to install some compatibility libraries:
uname -a
- > Linux puf 3.16.0-45-generic #60~14.04.1-Ubuntu SMP Fri Jul 24 21:16:23 UTC 2015 x86_64 x86_64 x86_64 GNU/Linux
sudo apt-get install lib32stdc++6
sudo apt-get install lib32z1
- Run
./gradlew
to ensure it loads/parses the project - Now run a build
./gradlew build
- Set up for signing and uploading the aar
vi ~/.gradle/gradle.properties
signing.keyId=94B86DB8 signing.password=PrivateKeyPassword signing.secretKeyRingFile=/path/to/gpg/secring.gpgsonatypeRepo=https://oss.sonatype.org/service/local/staging/deploy/maven2/ sonatypeUsername=YourSonatypeJiraUsername sonatypePassword=YourSonatypeJiraPassword
to build a release
- build the project in Android Studio or with Gradle
- this generates the main binary:
library/build/outputs/aar/library-debug.aar
- open the Gradle projects tab, by clicking the tiny gradle tab on the right (or View > Tool Windows > Gradle)
- select :library > Tasks > other > bundleReleaseJavadoc
- this generates the javadoc:
library/build/outputs/library-javadoc.jar
to tag a release on Github
- ensure that all your changes are on master and that your local build is on master
- ensure that the correct version number is in both
library/build.gradle
andlibrary/pom.xml
to deploy a release to Maven Central
- log onto the build box
- checkout and update the master branch
./release.sh
to build the library and update maven- close/release the repository from sonatype
Contributor License Agreements
We'd love to accept your sample apps and patches! Before we can take them, we have to jump a couple of legal hurdles.
Please fill out either the individual or corporate Contributor License Agreement (CLA).
- If you are an individual writing original source code and you're sure you own the intellectual property, then you'll need to sign an individual CLA.
- If you work for a company that wants to allow you to contribute your work, then you'll need to sign a corporate CLA.
Follow either of the two links above to access the appropriate CLA and instructions for how to sign and return it. Once we receive it, we'll be able to accept your pull requests.
Contribution Process
- Submit an issue describing your proposed change to the repo in question.
- The repo owner will respond to your issue promptly.
- If your proposed change is accepted, and you haven't already done so, sign a Contributor License Agreement (see details above).
- Fork the desired repo, develop and test your code changes.
- Ensure that your code adheres to the existing style of the library to which you are contributing.
- Ensure that your code has an appropriate set of unit tests which all pass.
- Submit a pull request and cc @puf or @mcdonamp