stream-chat-android

stream-chat-android is the official Android SDK for Stream Chat, a service for building chat applications.

As a first step try the tutorial: Java Chat Tutorial, Kotlin Chat Tutorial.

You can sign up for a Stream account at https://getstream.io/chat/get_started/. This library includes both a low level chat SDK and a set of reusable UI components. Most users start out with the UI components, and fall back to the lower level API when they want to customize things.

Installation

Step 1 Add repository into root build.gradle

allprojects {
    repositories {
    ...
    maven {
        url 'https://jitpack.io' }
    }
}

Step 2 Add library dependency into app build.gradle

See the jitpack badge above for the latest version number

android {
    ...
    dataBinding {
        enabled = true
    }
	
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }
}

dependencies {
    implementation 'com.github.getstream:stream-chat-android:<latest-version>'
}

Proguard/R8

If you're using Proguard/R8 you'll want to have a look at the proguard file we use for the sample.

Setup Stream Chat

Make sure to initialize the SDK only once; the best place to do this is in your Application class.

public class BaseApplication extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        StreamChat.init("STREAM-API-KEY", getApplicationContext());
    }
}

If this is a new Android app you will need to register BaseApplication inside AndroidManifest.xml as well.

...

<application
    android:name=".BaseApplication"
    ...
>

...

</application>

With this you will be able to retrieve the shared Chat client from any part of your application using StreamChat.getInstance(). Here's an example:

public class MainActivity extends AppCompatActivity {

	@Override
	protected void onCreate(Bundle savedInstanceState) {
		super.onCreate(savedInstanceState);
		Client client = StreamChat.getInstance(this.getApplication());
		...
	}

Make sure that your AndroidManifest.xml file include INTERNET and ACCESS_NETWORK_STATE permissions:

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android" package="...">

    ... 

    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
    <uses-permission android:name="android.permission.INTERNET" />

    ...

</manifest>

Initialize Chat for a user

Retrieve the chat client:

Client client = StreamChat.getInstance(this.getApplication());

Setup a user, you can use as many custom fields as you want. Both name and image are used automatically by UI components:

HashMap<String, Object> extraData = new HashMap<>();
extraData.put("name", "Happy Android");
extraData.put("image", "https://bit.ly/2TIt8NR");
User user = new User(USER_ID, extraData);

Setup chat for current user:

client.setUser(user, USER_TOKEN);

The USER_TOKEN variable is the unique token for the user with ID USER_ID in this case is hard-coded but in real-life it will be something that comes from your auth backend.

Once you called setUser you will be able to use Stream Chat APIs; all calls will automatically wait for the setUser call to complete. No need to add callbacks or complex syncronization code from your end.

If needed you can add callbacks to setUser via Client.onSetUserCompleted(ClientConnectionCallback)

client.onSetUserCompleted(new ClientConnectionCallback() {
    @Override
    public void onSuccess(User user) {
    	Log.i(TAG, "user connected!");
	// do some more initialization
    }

    @Override
    public void onError(String errMsg, int errCode) {
    }
});

Retrieve tokens server-side / Handle tokens with expiration

If you generate user tokens with an expiration (exp field) you can configure the SDK to request a new token upon expiration.

Here's an example where we make an HTTP call to retrieve a token for current user.

client.setUser(user, listener -> {
            OkHttpClient httpClient = new OkHttpClient()
                    .newBuilder()
                    .build();

            // request the token for this user
            Request request = new Request.Builder()
                    .url("https://path/to/my/backend/")
                    .header("Authorization", "user-session-id")
                    .build();

            httpClient.newCall(request).enqueue(new Callback() {
                @Override
                public void onFailure(@NotNull Call call, @NotNull IOException e) {
                    // the request to get the token failed
                }

                @Override
                public void onResponse(@NotNull Call call, @NotNull Response response) throws IOException {
                    Log.w(TAG, "getting the token worked!");
                    listener.onSuccess(response.body.string());
                }
            });
        }
);

The listener will be called to fetch the user token and once the token is expired; the SDK will retry failed API calls and re-sync history so that no messages are lost during the renewal process.

Online status

Connection status to Chat is available via StreamChat.getOnlineStatus() which returns a LiveData object you can attach observers to.

StreamChat.getOnlineStatus().observe(...);

UI Components

Documentation

Java Chat Tutorial page Official API Docs

Supported features

Channels list UI
Channel UI
Message Reactions
Link preview
Images, Videos and Files attachments
Edit and Delete message
Typing Inditicators
Read Inditicators
Push Notifications
Image gallery
GIF support
Light/Dark themes
Style customization
UI customization
Threads
Slash commands
Offline support

Getting started

TODO: https://getstream.io/chat/docs/#introduction but with Android code examples

bevzaanton/stream-chat-android