Official Android SDK for Stream Chat

This is the official Android SDK for Stream Chat, a service for building chat and messaging applications. This library includes both a low-level chat SDK and a set of reusable UI components. Most users start with the UI components, and fall back to the lower level API when they want to customize things.

🔗 Quick Links

• Register: Create an account and get an API key for Stream Chat

Small teams and individuals can also apply for a Maker Account that allows you to use Startup Plan for free.

Tutorials

• Chat Tutorial: Learn the basics of the SDK by by building a simple messaging app (Kotlin or Java)

Sample Apps

• UI Components sample app: Full messaging app with threads, reactions, optimistic UI updates and offline storage

• Compose UI Components sample app: Messaging sample app built with Jetpack Compose!

• Android Samples Repo: This repository contains sample projects, guides, tutorials, and links to helpful resources to help you get started with Android Stream SDK.

Documentation

• Client Documentation

• UI Components Documentation

• Compose UI Components Documentation

• UI Team Planning: UI Team public project management board and milestone overview

• Core Team Planning: Core Team public project management board and milestone overview

V5 Migration Guide

For upgrading from V4 to V5, please refer to the V5 Migration Guide

Changelog

Check out the CHANGELOG to see the changes and improvements in each of our releases.

Getting started

There are only 3 steps to get started with Stream!

1. Add Stream chat SDK dependency to your project.

2. Set up Stream chat client to communicate to the API.

3. Connect our components to ViewModels to show data.

Note: Alternatively, you can skip using our UI components and build your custom UI powered by our core SDK.

Let's cover some of these steps.

Add dependency

Add one of the four packages below to your dependencies for your module/app level build.gradle file:

repositories {
  google()
  mavenCentral()
  maven { url "https://jitpack.io" }
  jcenter()
}

dependencies {
  // Client + offline + Compose
  implementation "io.getstream:stream-chat-android-compose:$stream_version"
  // Client + offline + UI components
  implementation "io.getstream:stream-chat-android-ui-components:$stream_version"
  // Client + offline
  implementation "io.getstream:stream-chat-android-offline:$stream_version"
  // Client only
  implementation "io.getstream:stream-chat-android-client:$stream_version"
}

Setup API Client

First, you need to instantiate a chat client. The Chat client will manage API calls, event handling, and manage the WebSocket connection to Stream Chat servers. You should only create the client once and reuse it across your application.

val apiKey = "{{ api_key }}"
val token = "{{ chat_user_token }}"

val client = ChatClient.Builder(apiKey, applicationContext).build()

Next, you need to authenticate and connect the user.

val user = User(
      id = "summer-brook-2",
      name = "Paranoid Android",
      image = "https://bit.ly/2TIt8NR"
)
client.connectUser(
    user = user,
    token = token, // or client.devToken(userId); if auth is disabled for your app
).enqueue { result ->
    if (result.isSuccess) {
        // Handle success
    } else {
        // Handler error
    }
}

The user token is typically provided by your backend when you login or register in the app. If authentication is disabled for your app, you can also use a ChatClient#devToken to generate an insecure token for development. Of course, you should never launch into production with authentication disabled.

There is also a Stream Token Generator which can help you to generate user tokens for prototyping and debugging; usually by hardcoding this into your application or passing it as an environment value at initialization.

For more complex token generation and expiration examples, have a look at Token Expiration.

Offline storage

To add data persistence you can provide the ChatClient.Builder with an instance of StreamOfflinePluginFactory.

val offlinePluginFactory = StreamOfflinePluginFactory(
  config = Config(
    backgroundSyncEnabled = true,
    userPresence = true,
    persistenceEnabled = true,
    uploadAttachmentsNetworkType = UploadAttachmentsNetworkType.NOT_ROAMING,
  ),
  appContext = applicationContext,
)

val client = ChatClient.Builder(apiKey, applicationContext)
    .withPlugin(offlinePluginFactory)
    .build()

Logging

During development, you might want to see the SDK logs to investigate a specific area of interest. Let's see how it can be done!

Please take into account that the SDK will write no logs by default.

Change Logging Level

To enable logging information, you can change the default log level when constructing the client.

val client = ChatClient.Builder(apiKey, applicationContext)
    // Change log level
    .logLevel(ChatLogLevel.ALL)
    .build()

Custom Logger

You can handle the log messages directly instead of have them written to Logcat, this is very convenient if you use an error tracking tool or if you want to centralize your logs into one facility.

val loggerHandler = object : ChatLoggerHandler {
    //...
}
val client = ChatClient.Builder(apiKey, applicationContext)
    // Enable logs
    .logLevel(ChatLogLevel.ALL)
    // Provide loggerHandler instance
    .loggerHandler(loggerHandler)
    .build()

Sample apps

🏗️ Jetpack Compose based

Our Jetpack Compose implementation comes with its own /stream-chat-android-compose-sample, which you can play with to see how awesome Compose is.

To run the sample app, start by cloning this repo:

git clone git@github.com:GetStream/stream-chat-android.git

Next, open Android Studio and open the newly created project folder. You'll want to run the /stream-chat-android-compose-sample module.

📲 XML based

However, if you're still using XML due to technical limitations, our UI Components SDK includes a fully functional /stream-chat-android-ui-components-sample featuring threads, reactions, typing indicators, optimistic UI updates and offline storage. To run the sample app, start by cloning this repo:

git clone git@github.com:GetStream/stream-chat-android.git

Next, open Android Studio and open the newly created project folder. You'll want to run the /stream-chat-android-ui-components-sample app.

Contributing

Code conventions

Make sure that you run the following commands before committing your code:

• ./gradlew spotlessApply -q

• ./gradlew detekt

Public API changes

• run ./gradlew apiCheck -q

Running tests

• run ./gradlew test