Chat SDK is a fully featured open source instant messaging framework for Android. Chat SDK is fully featured, scalable and flexible and follows the following key principles:

  • Free. The Chat SDK is free for commercial use
  • Open Source. The Chat SDK is open source
  • Full control of the data. You have full and exclusive access to the user's chat data
  • Quick integration. Chat SDK is fully featured out of the box
  • Firebase Powered by Google Firebase
  • Download the APK to try out the Firebase Chat SDK for Android now!

v4.0 Released

We have just released the latest version of the Android Chat SDK. In this update we have gone over every class and rewritten large portions of the SDK to bring it fully up to date. The changes have focused around four key areas:

Architecture

The project has been completely refactored to make it's architecture fully modular. The project has been split into 3 main modules: core, ui and firebase network adapter. The architecture is now almost identical to the iOS version of the project.

Technology Stack

The technology stack has been fully updated. Promises have been replaced by the more flexible RXJava library. All images are loaded using Fresco. GreenDao and all the other support libraries have been updated to the latest version.

Performance

Performance has been improved in a number of areas. All the list views have been updated to recycler views. Now all network processing happens on background threads. We have also stress tested the code with up to 1000 threads in a view and 10,000 messages in a thread.

UX

The user interface has seen a major update. We have improved the chat view as well as making the entire app more consistent. We have also added an advanced user profile.

Features

  • Private and group messages
  • Public chat rooms
  • Username / password, Facebook, Twitter, Anonymous and custom login
  • Push notifications
  • Text, Image and Location messages
  • User profiles
  • User search
  • Powered by Firebase
  • Cross Platform - iOS, Web

Modules

The Chat SDK has a number of additional modules that can easily be installed including:

Get involved!

We're very excited about the project and we're looking for other people to get involved. Over time we would like to make the best messaging framework for mobile. Helping us could involve any of the following:

  • Providing feedback and feature requests
  • Reporting bugs
  • Fixing bugs
  • Writing documentation
  • Improving the user interface
  • Help us update the library to use Swift
  • Helping to write adapters for other services such as Layer, Pusher, Pubnub etc...
  • Write a tutorial - we pay $100 for quality tutorials

If you're interested please review the Contributing Document for details of our development flow and the CLA then email me at team@chatsdk.co.

Apps that use Chat SDK

If you have an app that uses the Chat SDK let us know and we'll add a link.

Running the demo project

This repository contains a fully functional version of the Chat SDK which is configured using our Firebase account and social media logins. This is great way to test the features of the Chat SDK before you start integrating it with your app.

Note: You should make sure that the correct SDK versions and build tools are installed in Android Studio. To do this open the Preferences panel and navigate to Appearance & Behavour -> System Settings -> Android SDK or click on the SDK Manager icon in the tool bar. Android SDK versions 4.4 and onwards should be installed. Android SDK Build-Tools version 26.0.02 should be installed.

The next step is to setup the Chat SDK using your Firebase and Social Accounts. To do that you need to do the following.

Branches

There are three main branches in the project:

  • master - the latest stable release version of the code
  • dev - the latest unstable version of the code
  • v3_final - the legacy version of the project (no longer maintained)

Setup Service

We provide extensive documentation on Github but if you’re a non-technical user or want to save yourself some work you can take advantage of our setup and integration service.

Adding the Chat SDK to your project

Quick start guide - it takes about 10 minutes!

Integration with an existing project is simple. You can add the core libraries using Gradle.

Gradle

Until the project is published in jCenter, you will need to include the repository manually:

repositories {
    maven { url "http://dl.bintray.com/chat-sdk/chat-sdk-android" }
    maven { url "https://maven.google.com" }
    maven { url "https://jitpack.io" }
}

Then add this to your dependencies area:

compile 'co.chatsdk.chatsdk:chat-sdk-core:4.0.5'
compile 'co.chatsdk.chatsdk:chat-sdk-ui:4.0.5'
compile 'co.chatsdk.chatsdk:chat-sdk-firebase-adapter:4.0.5'
compile 'co.chatsdk.chatsdk:chat-sdk-firebase-file-storage:4.0.5'

You can also add the modules manually by downloading source code and importing the modules to Android Studio.

Firebase depends on Google Services so we need to apply the google services plugin. This will read the Google Services file that we will add during Firebase setup.

buildscript {
    repositories {
        jcenter()
    }
    dependencies {
        classpath 'com.google.gms:google-services:3.1.0'
    }
}

At the end of this file, add the following:

apply plugin: 'com.google.gms.google-services'

Initializing the Chat SDK

Now open your applications's main class and find the onCreate method. Add the following to setup the Chat SDK:

Context context = getApplicationContext();

// Create a new configuration
Configuration.Builder builder = new Configuration.Builder(context);

// Perform any configuration steps (optional)
builder.firebaseRootPath("prod");

// Initialize the Chat SDK
ChatSDK.initialize(builder.build());
UserInterfaceModule.activate(context);

// Activate the Firebase module
FirebaseModule.activate();

// File storage is needed for profile image upload and image messages
FirebaseFileStorageModule.activate();

// Activate any other modules you need.
// ...

Activate the core Chat SDK modules and any other modules you need. See the module setup guide for more information.

Launch the Chat SDK login activity by adding this to your AndroidManifest.xml:

<activity android:name="co.chatsdk.ui.login.LoginActivity">
    <intent-filter>
        <action android:name="android.intent.action.MAIN" />
        <category android:name="android.intent.category.LAUNCHER" />
    </intent-filter>
</activity>

Or if you want to launch the activity manually, you can do it using:

InterfaceManager.shared().a.startLoginActivity(context, true);

Firebase Setup

  1. Go to the Firebase website and sign up or log in
  2. Go to the Firebase console and make a new project
  3. Click Add project
  4. Choose a name and a location
  5. Click Settings (the gear icon). On the General tab, click Add App -> Add Firebase to your Android app
  6. Enter your package name - found in your app's build.gradle file, app name and SHA-1 key (optional)
  7. Download the google-services.json file and add it to your app project. It should be added inside the app folder.

    Note:
    It is worth opening your downloaded GoogleService-Info.plist and checking there is an API_KEY field included. Sometimes Firebase's automatic download doesn’t include this in the plist. To rectify, just re-download the plist from the project settings menu.

  8. Set a custom root path. The chat SDK allows you to run multiple chat instances on one Firebase database. This could be useful if you want test and production environments for example. To do this set builder.firebaseRootPath("prod") in the configuration builder.

  9. In the Firebase dashboard click Authentication -> Sign-in method and enable all the appropriate methods

Enabling location messages

The Chat SDK needs two google services to support location messages. The Google Places API to select the location and the Google Maps API to display the location.

Then add the following to your AndroidManifest.xml file:

<meta-data android:name="com.google.android.geo.API_KEY" android:value="@string/google_maps_api_key"/> 

Add this to your chat_sdk_firebase.xml file:

<string name="google_maps_api_key">YOUR KEY</string>

You can disable location messages using the configurationBuilder.locationMessagesEnabled(false) option.

Conclusion

Congratulations! 🎉🎉 You've just turned your app into a fully featured instant messenger! Keep reading below to learn how to further customize the Chat SDK.

Next Steps

Check out the Development Guide

We've written a comprehensive Development Guide which is available in the docs repository.

If you thing that something is missing, you can post a new issue and we will update the guide.

We have a number of additional guides available on our Wiki.

Configuration

The Chat SDK can be customized during setup using the configuration builder object. For a full list of options, take a look at here.

Configuration using the Configuration Builder

In your main onCreate method you create a new instance of the Configuration.Builder and pass it to the ChatSDK singleton on initialization.

Here you have the option to set far more properties. For example:

Configure Firebase
builder.firebase("FirebaseURL", "rootPath", "storageUrl", "CloudMessaging Api Key");
Disable Facebook and Twitter login
builder.facebookLoginEnabled(false);
builder.twitterLoginEnabled(false);
Set a custom user name and avatar
builder.defaultUserName("TestUser");
builder.defaultUserAvatarUrl("http://your-site/image.png");

Remember that in the instructions we will advise you to configure using the Android Manifest but you are always free to use the direct configuration method instead.

Module Setup

There are a number of free and premium extensions that can be added to the Chat SDK.

Firebase Modules

For the following modules:

The free modules are located in the main Github repository. The premium modules can be purchased and downloaded from the links provided above.

Social Login

Add the following to your build.gradle

Add the library

Gradle

compile 'co.chatsdk.chatsdk:chat-sdk-firebase-social-login:4.0.5'

Manual Import

compile project(path: ':chat-sdk-firebase-social-login')
Enable the module

In your main class onCreate method add:

FirebaseSocialLoginModule.activate(getApplicationContext());

Facebook

  1. On the Facebook developer site get the App ID and App Secret
  2. Go to the Firebase Console and open the Auth section
  3. On the Sign in method tab, enable the Facebook sign-in method and specify the App ID and App Secret you got from Facebook.
  4. Then, make sure your OAuth redirect URI (e.g. my-app-12345.firebaseapp.com/__/auth/handler) is listed as one of your OAuth redirect URIs in your Facebook app's settings page on the Facebook for Developers site in the Product Settings > Facebook Login config
  5. Add the following to your AndroidManifest.xml:

    <meta-data android:name="com.facebook.sdk.ApplicationId" android:value="@string/facebook_app_id"/>
    

    Add the following to your chat_sdk_firebase.xml file:

    <string name="facebook_app_id">[FACEBOOK APP KEY]</string>
    

Twitter

  1. Register your app as a developer application on Twitter and get your app's API Key and API Secret.
  2. In the Firebase console, open the Auth section.
  3. On the Sign in method tab, enable the Twitter sign-in method and specify the API Key and API Secret you got from Twitter.
  4. Then, make sure your Firebase OAuth redirect URI (e.g. my-app-12345.firebaseapp.com/__/auth/handler) is set as your Callback URL in your app's settings page on your Twitter app's config.
  5. Add the following to your AndroidManifest.xml:

    <meta-data android:name="twitter_key" android:value="@string/twitter_key" />
    <meta-data android:name="twitter_secret" android:value="@string/twitter_secret" />
    

    Add the following to your chat_sdk_firebase.xml file:

    <string name="twitter_key">[TWITTER KEY]</string>
    <string name="twitter_secret">[TWITTER SECRET]</string>
    

Google

  1. If you haven't yet specified your app's SHA-1 fingerprint, do so from the Settings page of the Firebase console. See Authenticating Your Client for details on how to get your app's SHA-1 fingerprint.
  2. In the Firebase console, open the Auth section.
  3. On the Sign in method tab, enable the Google sign-in method and click Save.
  4. You must pass your server's client ID to the requestIdToken method. To find the OAuth 2.0 client ID.
  5. Open the Credentials page in the API Console.
  6. The Web application type client ID is your backend server's OAuth 2.0 client ID.
  7. Add the following to your AndroidManifest.xml:

    <meta-data android:name="google_web_client_id" android:value="@string/google_web_client_id" />
    

    Add the following to your chat_sdk_firebase.xml file:

    <string name="google_web_client_id">[CLIENT ID]</string>
    

Social login can also be enabled or disabled by changing the Chat SDK configuration.

Push Notifications

Add the following to your build.gradle

Add the library

Gradle

compile 'co.chatsdk.chatsdk:chat-sdk-firebase-push:4.0.5'

Manual Import

compile project(path: ':chat-sdk-firebase-push')
Enable the module

In your main class onCreate method add:

FirebasePushModule.activateForFirebase();
  1. Get the push token. Go to the Firebase Console click your project and then the Settings button. Click the Cloud Messaging tab. Copy the Server Key.
  2. Add the following to your AndroidManifest.xml:

    <meta-data android:name="cloud_messaging_server_key" android:value="@string/firebase_cloud_messaging_server_key" />
    

    Add the following to your chat_sdk_firebase.xml file:

    <string name="firebase_cloud_messaging_server_key">[SERVER KEY]</string>
    

Other Modules

For the following modules:

After you have purchased the module you will be provided with a link to the module source code. Unzip this file and import it into Android Studio.

  1. Click File -> New -> Import Module
  2. Add the module to your build.gradle

    compile project(path: ':chat_sdk_[module name]')
    
  3. Sync Gradle

  4. In your main class onCreate activate the module:

    ContactBookModule.activateForFirebase();
    

    or

    ContactBookModule.activateForXMPP();
    

Security Rules

Firebase secures your data by allowing you to write rules to govern who can access the database and what can be written. On the Firebase dashboard click Database then the Rules tab.

Copy the contents of the rules.json file into the rules and click publish.

Adding Modules Manually

In Android Studio:

File -> New -> Import Module

You must import the following core modules:

  • chat-sdk-core
  • chat-sdk-ui

And at least one network adapter:

And any of the following optional modules:

Now import the modules in your build.gradle file.

compile project(path: ':chat-sdk-ui')
compile project(path: ':chat-sdk-firebase-push')

Configuring the project

Now that the modules have been added, we need to configure the project.

SDK Version

Now you will see that gradle cannot be sync because it missing some parameters. Open to gradle.properties file in the root of the project and add the following lines.

MIN_SDK = 16
ANDROID_BUILD_SDK_VERSION = 25
ANDROID_BUILD_TOOLS_VERSION = 25.0.2
ANDROID_BUILD_TARGET_SDK_VERSION = 25
ANDROID_COMPILE_SDK_VERSION = 25

GOOGLE_SERVICES_VERSION = 10.2.1
ANDROID_SUPPORT_VERSION = 25.3.1

CHAT_SDK_VERSION = 4.0.0
CHAT_SDK_BUILD_NUMBER = 4000
CHAT_SDK_GROUP = co.chatsdk

Note: You should make sure that the correct SDK versions and build tools are installed in Android Studio. To do this open the Preferences panel and navigate to Appearance & Behavior -> System Settings -> Android SDK or click on the SDK Manager icon in the tool bar. Android SDK versions 4.4 and onwards should be installed. Android SDK Build-Tools version 21.1.0 should be installed.

Add any other modules that you need. Then sync the project with gradle.

The license

We offer a choice of two license for this app. You can either use the Chat SDK license or the GPLv3 license.

Most Chat SDK users either want to add the Chat SDK to an app that will be released to the App Store or they want to use the Chat SDK in a project for their client. The Chat SDK license gives you complete flexibility to do this for free.

Chat SDK License Summary

  • License does not expire.
  • Can be used for creating unlimited applications
  • Can be distributed in binary or object form only
  • Commercial use allowed
  • Can modify source-code but cannot distribute modifications (derivative works)

If a user wants to distribute the Chat SDK source code, we feel that any additions or modifications they make to the code should be contributed back to the project. The GPLv3 license ensures that if source code is distributed, it must remain open source and available to the community.

GPLv3 License Summary

  • Can modify and distribute source code
  • Commerical use allowed
  • Cannot sublicense or hold liable
  • Must include original license
  • Must disclose source

What does this mean?

Please check out the Licensing FAQ for more information.