Getting Started

Let's see how you can get started with the Android Chat SDK after adding the required dependencies. This page shows you how to initialize the SDK in your app.

note

If you're looking for a complete, step-by-step guide that includes setting up an Android project from scratch, try the Android In-App Messaging Tutorial instead.

Creating a ChatClient

Your first step is initializing the ChatClient, which is the main entry point for all operations in the library. ChatClient is a singleton: you'll create it once and re-use it across your application.

A best practice is to initialize ChatClient in the Application class:

Kotlin

class App : Application() {
    override fun onCreate() {
        super.onCreate()
        val chatClient = ChatClient.Builder("apiKey", applicationContext).build()
    }
}

Java

class App extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        ChatClient chatClient = new ChatClient.Builder("apiKey", getApplicationContext()).build();
    }
}

The Builder for ChatClient exposes configuration options for features such as Logging.

note

To generate an API key, you can sign up for a free 30-day trial. You can then access your api key in the Dashboard.

If you create the ChatClient instance following the pattern in the previous example, you will be able to access that instance from any part of your application using the instance() method:

Kotlin

class MainActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        val chatClient = ChatClient.instance() // Returns the singleton instance
    }
}

Java

class MainActivity extends AppCompatActivity {
    @Override
    protected void onCreate(@Nullable Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        ChatClient chatClient = ChatClient.instance();  // Returns the singleton instance
    }
}

Adding the Offline Plugin

If you want to have offline support or use the UI Components package, you'll need to initialize the OfflinePlugin class and add it to the ChatClient.Builder. You can skip this initialization step if you're only using the low-level client.

The initialization should be done using StreamOfflinePluginFactory:

Kotlin

val offlinePluginFactory = StreamOfflinePluginFactory(
    config = Config(
        // Enables the background sync which is performed to sync user actions done without the Internet connection.
        backgroundSyncEnabled = true,
        // Enables the ability to receive information about user activity such as last active date and if they are online right now.
        userPresence = true,
        // Enables using the database as an internal caching mechanism.
        persistenceEnabled = true,
        // An enumeration of various network types used as a constraint inside upload attachments worker.
        uploadAttachmentsNetworkType = UploadAttachmentsNetworkType.NOT_ROAMING,
        // Whether the SDK will use a new sequential event handling mechanism.
        useSequentialEventHandler = false,
    ),
    appContext = context,
)

ChatClient.Builder(apiKey, context).withPlugin(offlinePluginFactory).build()

Java

// Enables background sync which is performed to sync user actions done while offline.
boolean backgroundSyncEnabled = true;
// Enables the ability to receive information about user activity such as last active date and if they are online right now.
boolean userPresence = true;
// Enables using the database as an internal caching mechanism.
boolean persistenceEnabled = true;
// An enumeration of various network types used as a constraint inside upload attachments worker.
UploadAttachmentsNetworkType uploadAttachmentsNetworkType = UploadAttachmentsNetworkType.NOT_ROAMING;
// Whether the SDK will use a new sequential event handling mechanism.
boolean useSequentialEventHandler = false;

StreamOfflinePluginFactory offlinePluginFactory = new StreamOfflinePluginFactory(new Config(backgroundSyncEnabled, userPresence, persistenceEnabled, uploadAttachmentsNetworkType, useSequentialEventHandler), context);
new ChatClient.Builder("apiKey", context).withPlugin(offlinePluginFactory).build();

For more about working with OfflinePlugin, see Offline Support

Connecting a User

The next step is connecting the user. This requires a valid Stream Chat token. As you must use your API_SECRET to create this token, it is unsafe to generate this token outside of a secure server.

Kotlin

val user = User(
    id = "bender",
    name = "Bender",
    image = "https://bit.ly/321RmWb",
)

ChatClient.instance().connectUser(user = user, token = "userToken") // Replace with a real token
    .enqueue { result ->
        if (result.isSuccess) {
            // Handle success
        } else {
            // Handle error
        }
    }

Java

User user = new User();
user.setId("bender");
user.setName("Bender");
user.setImage("https://bit.ly/321RmWb");

ChatClient.instance().connectUser(user, "userToken")  // Replace with a real token
        .enqueue((result) -> {
            if (result.isSuccess()) {
                // Handle success
            } else {
                // Handle error
            }
        });

note

To learn about how to create a token and different user types, see Tokens & Authentication.

If the connectUser call was successful, you are now ready to use the SDK! 🎉

warning

You shouldn't call connectUser if the user is already set! You can use ChatClient.instance().getCurrentUser() to verify if the user is already connected.

The methods of the ChatClient class allow you to create channels, send messages, add reactions, and perform many more low-level operations. You can also use the SDK's pre-built UI Components that will perform data fetching and sending for you, as described below.

Adding UI Components

There are two UI Component implementations available: one built on regular, XML based Android Views, and another built from the ground up in Jetpack Compose.

Take a look at the Overview pages of the implementations to get started with them:

• XML based UI Components
• Jetpack Compose UI Components