Android
Quick Start

Quick Start

The SendBird SDKs help you to implement real-time chat to any types of your client apps with speed and efficiency. Our Android SDK provides you with various methods to initialize, configure, and build the chat from the client side - no server side implementation is required because our reliable infra management service is delivered with the SDK. This page presents a brief overview of the SDK’s structure and abilities, then lets you go through the preliminary steps of implementing the SDK in your own app.


First, try out the sample app!

Our sample app is a basic representation of the abilites of the SDK. You can download the app from our repository on GitHub and build it in your workplace. The app gives you a simple picture of what you can build with the SDK, although without the many more capabilities of the actual SDK.

Download Sample App

In fact, a simple way to build your messaging app is to do so on top of our sample app. Note that you should change the application ID of the sample app to your own in this case - see the Create a new SendBird application from your dashboard section for reference.


How SendBird works with messaging

To build your messaging with the Android SDK is simple: a user connects, sees a list of channels, selects or creates a channel, then sends a message to the channel, and receives messages from all other users within the channel.

We provide two types: an open channel and a group channel. An open channel is a public channel which anyone can easily participate and chat with others. A group channel is basically a private channel which a user can join as a new member through an invitation. Compared with an open channel, it has distinctive abilities of various properties and features. There are a variety of the subtypes of a group channel such as a public group channel working like an open channel.

All sent messages within your SendBird application are automatically delivered to channel event handlers which are registered to your app. As long as the SendBird instance in your user's client app is connected to our server, the event handlers receive callbacks from the server through their onMessageReceived(), onUserJoined() methods, and so on. These callbacks contain message or channel objects, with the latest information in case of an incoming message or other events related to the objects.


Install and configure Android SDK

Step 1: Create a new SendBird application from your dashboard

A SendBird application comprises everything that goes in a chatting service such as users, messages, and channels. To create a SendBird application, do the following:

  1. In the SendBird Dashboard, type your email and password to create a new account. You can also sign in or sign up with Google or GitHub accounts.
  2. In the Setup wizard that appears, specify information of your organization to manage SendBird applications.
  3. In your dashboard home that appears after completing the setup, click Create App at the top-right corner for a new application (you can also create via the Platform API).

You can implement only one SendBird application per app for your service, regardless of the platforms. All users within your SendBird application can communicate with each other, across all platforms. This means that your users using iOS, Android, web, .NET, and Unity client apps, can all chat with one another without any further setup. Note that all data are limited to the scope of a single application, and users in different SendBird applications can't talk to each other.

Step 2: Install the SDK

Installing the Android SDK is simple if you’re familiar with using external libraries or SDK’s in your projects. To install the SDK using Gradle, add the following lines to a build.gradle file at the app level.

build.gradle
Light Color Skin
Copy
repositories {
    maven { url "https://raw.githubusercontent.com/sendbird/SendBird-SDK-Android/master/" }
}
dependencies {
    implementation 'com.sendbird.sdk:sendbird-android-sdk:3.0.96'
}

Alternatively, you can download the .jar file from the link below. Copy this file into your libs/ folder, and make sure you include the library in your build.gradle file as well.

Download Latest SDK

Step 3: Grant system permissions to the SDK

The Android SDK requires system permissions. These permissions allow the SDK to communicate with SendBird server and read/write files to a device's external storage. For granting system permissions, add the following lines to your AndroidManifest.xml file.

AndroidManifest.xml
Light Color Skin
Copy
<uses-permission android:name="android.permission.INTERNET" />

<!-- READ/WRITE_EXTERNAL_STORAGE permissions are required to upload or download files from/into external storage. ->
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />

(Optional) Step 4: Configure ProGuard for shrinking code and resources

When you build your APK with minifyEnabled true, add the following line to the module's ProGuard rules file.

Light Color Skin
Copy
-dontwarn com.sendbird.android.shadow.**

Send your first message

The Android SDK simplifies messaging into an effortless and straightforward process. To send your first message, do the following steps:

Note: The methods in the following steps are all asynchronous, excluding the SendBird.init() method. This means that you should make sure that a client app receives a success callback from the SendBird server through a handler to proceed to the next step. A good way to do this is the nesting of methods - see the example in the Step 4: Enter the channel which shows how you can nest the openChannel.enter() in the OpenChannel.getChannel() method.

Step 1: Initialize the SDK

Initialization binds the SDK to Android’s context, thereby allowing it to respond to connection and state changes. Pass in the App ID of your SendBird application created earlier in the dashboard to initialize the SDK.

Note: The SendBird.init() method must be called once across your Android client app. We recommend that you initialize the Android SDK in the onCreate() method of the Application instance.

Light Color Skin
Copy
SendBird.init(APP_ID, Context context);

Step 2: Connect to SendBird server

Connect a user to SendBird server using their unique user ID. Any untaken user ID is automatically registered as a new user to the SendBird system before connected, while an existing ID makes the user log in directly.

Note: Authenticating with an access token is discussed in the Authentication section.

Light Color Skin
Copy
SendBird.connect(USER_ID, new ConnectHandler() {
    @Override
    public void onConnected(User user, SendBirdException e) {
        if (e != null) {    // Error.
            return;
        }
    }
});

Step 3: Create a new open channel

Create an open channel. Once created, all users in your SendBird application can easily participate the channel to converse.

Note: In a similar way, you can create a group channel with inviting any other users as new members to the channel.

Light Color Skin
Copy
OpenChannel.createChannel(new OpenChannel.OpenChannelCreateHandler() {
    @Override
    public void onResult(OpenChannel openChannel, SendBirdException e) {
        if (e != null) {    // Error.
            return;
        }
    }
});

Step 4: Enter the channel

Enter the channel to view and send messages.

Light Color Skin
Copy
OpenChannel.getChannel(CHANNEL_URL, new OpenChannel.OpenChannelGetHandler() {
    @Override
    public void onResult(OpenChannel openChannel, SendBirdException e) {
        if (e != null) {    // Error.
            return;
        }

        openChannel.enter(new OpenChannel.OpenChannelEnterHandler() {
            @Override
            public void onResult(SendBirdException e) {
                if (e != null) {    // Error.
                    return;
                }
            }
        });
    }
});

Step 5: Send a message to the channel

And finally, send a message to the channel! There are three types: a user message is a plain text, a file message is a binary file, such as an image or PDF, and an admin message is a plain text sent through the dashboard or Platform API for special purpose.

Light Color Skin
Copy
openChannel.sendUserMessage(MESSAGE, new BaseChannel.SendUserMessageHandler() {
    @Override
    public void onSent(UserMessage userMessage, SendBirdException e) {
        if (e != null) {    // Error.
            return;
        }
    }
});