Android
Migration

Migration from v2

The new and improved Android SDK 3.0 (v3) supports your chat solution on any mobile apps and websites with the following new features:

  • The OpenChannel and GroupChannel classes have been added.
  • The UserMessage, FileMessage and AdminMessage have been added to handle various types of messages.
  • Event callbacks and new instances for various types of queries have been added.

We recommend you to migrate to v3 from the previous version by the following the below instructions.


Installation

If you are using the gradle, change the version of dependencies in the build.gradle file at the app level (not at the project level).

Light Color Skin
Copy
// v2
dependencies {
    compile 'com.sendbird.sdk:sendbird-android-sdk:2.2.17' // 2.2.17 is the latest v2 SDK as of writing this doc.
}

// v3
dependencies {
    compile 'com.sendbird.sdk:sendbird-android-sdk:3.0.86' // 3.0.92 is the latest SDK as of writing this doc.
}

Authentication

Initialization

As in v2, your client app should initialize the SendBird instance to communicate with SendBird server.

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

// v3
SendBird.init(APP_ID, context);

Login

The login() is no longer used in v3. You only need to call the connect() once after the init().

Light Color Skin
Copy
// v2
SendBird.login(LoginOption option);

// v3
SendBird.connect(USER_ID, ConnectHandler handler); // When you allow guest login.
SendBird.connect(USER_ID, ACCESS_TOKEN, ConnectHandler handler); // When you allow only permitted user login.

If you want to update user information such as nickname, profile image or FCM/GCM registration tokens, use the updateCurrentUserInfo() and registerPushTokenForCurrentUser() after connection is established.


Open channel

In v3, the object formerly known as open chat channel is now called open channel. Users who are participating in an open channel are referred to as participants of the channel. With the OpenChannel and OpenChannelListQuery classes, you can access and use a variety of features related to an open channel.

Retrieve a list of channels

Light Color Skin
Copy
// v2
ChannelListQuery channelListQuery = SendBird.queryChannelList();
channelListQuery.next(ChannelListQueryResult handler);

// v3
OpenChannelListQuery channelListQuery = OpenChannel.createOpenChannelListQuery();
channelListQuery.next(OpenChannelListQueryResultHandler handler);

Connect to a channel

In v3, you only need one connection to handle multiple open channels. The connection is automatically made once you have called the connect() after the init(). Plus, entering an open channel is much simpler in v3 than in v2, since you don’t need to fetch a channel URL and call the join(), queryMessageList() and connect() to enter the channel.

Light Color Skin
Copy
// v2
SendBird.join(CHANNEL_URL);
SendBird.queryMessageList(CHANNEL_URL).prev(Long.MAX_VALUE, LIMIT, new MessageListQueryResult() {
    @Override
    public void onResult(List<MessageModel> messageModels) {
        // Connect to SendBird with max messages timestamp to receive new messages since last query.
        SendBird.connect(MAX_MESSAGE_TIMESTAMP);
    }

    @Override
    public void onError(Exception e) {
    }
});

// v3
OpenChannel.getChannel(CHANNEL_URL, new 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;
                }
            }
        });
    }
});

Disconnect from a channel

In the same way as connect to a channel, the connection is automatically disconnected when you call the disconnect() on application termination. If a participant wants to exit an open channel, just call the exit().

Light Color Skin
Copy
// v2
SendBird.leave(CHANNEL_URL);
SendBird.disconnect();

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

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

Send a message to a channel

In v3, the steps of sending text and file messages are simplified into just one method call with the sendUserMessage() and sendFileMessage(). There are a number of methods with the same name but different parameters.

Light Color Skin
Copy
// v2
SendBird.send(MESSAGE);
SendBird.sendWithData(MESSAGE, DATA);

SendBird.uploadFile(FILE, TYPE, SIZE, CUSTOM_FIELD, SendBirdFileUploadEventHandler handler);
FileInfo fileInfo = FileInfo.build(URL_FROM_ABOVE, NAME, TYPE, SIZE, CUSTOM_FIELD);
SendBird.sendFile(fileInfo);

// v3
openChannel.sendUserMessage(MESSAGE, DATA, SendUserMessageHandler handler);
openChannel.sendFileMessage(FILE, FILE_NAME, FILE_TYPE, FILE_SIZE, CUSTOM_DATA, SendFileMessageHandler handler);

Receive messages through an event handler

The SendBirdEventHandler is now replaced with the ChannelHandler. You can create and manage multiple channel handlers.

Light Color Skin
Copy
// v2
SendBird.setEventHandler(new SendBirdEventHandler() {
    ...
});

// v3
SendBird.addChannelHandler(UNIQUE_HANDLER_ID, new SendBird.ChannelHandler() {
    @Override
    public void onMessageReceived(BaseChannel baseChannel, BaseMessage baseMessage) {
    }
});

Load previous messages in a channel

Light Color Skin
Copy
// v2
SendBird.queryMessageList(SendBird.getChannelUrl()).prev(Long.MAX_VALUE, LIMIT, MessageListQueryResult handler);

// v3
PreviousMessageListQuery prevMessageListQuery = openChannel.createPreviousMessageListQuery();
prevMessageListQuery.load(LIMIT, IS_REVERSED, new PreviousMessageListQuery.MessageListQueryResult() {
    @Override
    public void onResult(List<BaseMessage> messages, SendBirdException e) {
        if (e != null) {    // Error.
            return;
        }
    }
});

Retrieve a list of all participants of a channel

A participant refers to the participating user in an open channel. Once a user exits the open channel, the user is no longer a participant of that channel and the retrieved results of a query do not include the user.

Light Color Skin
Copy
// v2
SendBird.queryMemberList(CHANNEL_URL, TRUE_OR_FALSE).get(MemberListQueryResult handler);

// v3
UserListQuery query = openChannel.createParticipantListQuery();
query.next(UserListQueryResultHandler handler);

Group channel

In v3, the object formerly known as messaging channel is now called group channel. Users who are joining in a group channel are referred to as members of the channel. With the GroupChannel and GroupChannelListQuery classes, you can access and use a variety of features related to a group channel.

Create a channel

All startMessaging related methods are replaced by createChannel and createChannelWithUserIds.

Light Color Skin
Copy
// v2
SendBird.startMessaging(USER_IDS);

// v3
GroupChannel.createChannelWithUserIds(USER_IDS, TRUE_OR_FALSE, GroupChannelCreateHandler handler);

Retrieve a list of channels

Light Color Skin
Copy
// v2
MessagingListQuery messagingChannelListQuery = SendBird.queryMessagingChannelList();
messagingChannelListQuery.setLimit(LIMIT);
messagingChannelListQuery.next(MessagingChannelListQueryResult handler);

// v3
GroupChannelListQuery query = GroupChannel.createMyGroupChannelListQuery();
query.setIncludeEmpty(TRUE_OR_FALSE); // If you want to only retrieve channels having previous messages, set this false. 
query.next(GroupChannelListQueryResultHandler handler);

Connect to a channel

In v3, you only need one connection to handle multiple group channels. The connection is automatically made once you have called the connect() after the init(). Plus, joining a group channel is much simpler in v3 than in v2, since you don’t need to fetch a channel URL and call the queryMessageList(), join() and connect() to join the channel.

Light Color Skin
Copy
// v2
SendBird.queryMessageList(CHANNEL_URL).load(Long.MAX_VALUE, PREV_LIMIT, NEXT_LIMIT, new MessageListQueryResult() {
    @Override
    public void onResult(List<MessageModel> messageModels) {
        SendBird.join(CHANNEL_URL);
        SendBird.connect(MAX_MESSAGE_TIMESTAMP);
    }

    @Override
    public void onError(Exception e) {
    }
});

// v3
// Do nothing.

Disconnect from a channel

In the same way as connect to a channel, the connection is automatically disconnected when you call the disconnect() on application termination. If a member wants to leave a group channel, just call the leave().

Light Color Skin
Copy
// v2
SendBird.disconnect();

// v3
// Do nothing.

Invite a user to a channel as a member

Light Color Skin
Copy
// v2
SendBird.inviteMessaging(CHANNEL_URL, USER_ID);

// v3
groupChannel.inviteWithUserIds(USER_IDS, GroupChannelInviteHandler handler);

Remove a member from a group channel

Light Color Skin
Copy
// v2
SendBird.endMessaging(CHANNEL_URL);

// v3
groupChannel.leave(GroupChannelLeaveHandler handler);

Send a message to a channel

In v3, the steps of sending text and file messages are simplified into just one method call with the sendUserMessage() and sendFileMessage(). There are a number of methods with the same name but different parameters.

Light Color Skin
Copy
// v2
SendBird.send(MESSAGE);
SendBird.sendWithData(MESSAGE, DATA);

SendBird.uploadFile(FILE, TYPE, SIZE, CUSTOM_FIELD, SendBirdFileUploadEventHandler handler);
FileInfo fileInfo = FileInfo.build(URL_FROM_ABOVE, NAME, TYPE, SIZE, CUSTOM_FIELD);
SendBird.sendFile(fileInfo);

// v3
groupChannel.sendUserMessage(MESSAGE, DATA, SendUserMessageHandler handler);
groupChannel.sendFileMessage(FILE, FILE_NAME, FILE_TYPE, FILE_SIZE, CUSTOM_DATA, SendFileMessageHandler handler);

Receive messages through an event handler

The SendBirdEventHandler is now replaced with the ChannelHandler. You can create and manage multiple channel handlers.

Light Color Skin
Copy
// v2
SendBird.setEventHandler(new SendBirdEventHandler() {
    ...
});

// v3
SendBird.addChannelHandler(UNIQUE_HANDLER_ID, new SendBird.ChannelHandler() {
    @Override
    public void onMessageReceived(BaseChannel baseChannel, BaseMessage baseMessage) {
    }
});

Load previous messages in a channel

Light Color Skin
Copy
// v2
SendBird.queryMessageList(SendBird.getChannelUrl()).prev(Long.MAX_VALUE, LIMIT, MessageListQueryResult handler);

// v3
PreviousMessageListQuery prevMessageListQuery = groupChannel.createPreviousMessageListQuery();
prevMessageListQuery.load(LIMIT, IS_REVERSED, new PreviousMessageListQuery.MessageListQueryResult() {
    @Override
    public void onResult(List<BaseMessage> messages, SendBirdException e) {
        if (e != null) {    // Error.
            return;
        }
    }
});

Monitor group channels with a notification handler

Also, the SendBirdNotificationHandler is now replaced with the ChannelHandler. Your client app can get notified through channel handlers which support a variety of events. See the Event Handler page for more information.

Light Color Skin
Copy
// v2
SendBird.registerNotificationHandler(SendBirdNotificationHandler handler);

// v3
SendBird.addChannelHandler(UNIQUE_HANDLER_ID, ChannelHandler handler);

Retrieve a list of all members of a channel

Light Color Skin
Copy
// v2
messagingChannel.getMembers();

// v3
groupChannel.getMembers();

Send typing indicators to other members

Light Color Skin
Copy
// v2
SendBird.typeStart();
SendBird.typeEnd();

// v3
groupChannel.startTyping();
groupChannel.endTyping();

Retrieve the read receipts of a message

With v3, there is more than one way to retrieve read receipts. You can get a timestamp for a specific member as did in v2 or get the automatically calculated read receipts.

Light Color Skin
Copy
// v2
long timestamp = messagingChannel.getLastReadMillis(USER_ID);

// v3
long timestamp = groupChannel.getLastSeenAtByWithUserId(USER_ID);
int unreadCount = mGroupChannel.getReadReceipt(MESSAGE);

Mark messages as read

Light Color Skin
Copy
// v2
SendBird.markAsRead();

// v3
groupChannel.markAsRead();

Channel meta-information

You can create, update, and read metadata and metacounter in v3.

Create, update, and retrieve a metadata

Light Color Skin
Copy
// v2
SendBird.queryChannelMetaData(CHANNEL_URL).set(DATA_MAP, ChannelMetaDataQueryResult handler);
SendBird.queryChannelMetaData(CHANNEL_URL).get(KEYS, ChannelMetaDataQueryResult handler);

// v3
channel.createMetaData(DATA_MAP, MetaDataHandler handler);
channel.updateMetaData(DATA_MAP, MetaDataHandler handler);
channel.getMetaData(KEYS, MetaDataHandler handler);

Increase and retrieve a metacounter

Light Color Skin
Copy
// v2
SendBird.queryChannelMetaCounter(CHANNEL_URL).increase(KEY, AMOUNT, ChannelMetaCounterQueryResult handler);
SendBird.queryChannelMetaCounter(CHANNEL_URL).get(KEYS, ChannelMetaCounterQueryResult handler);

// v3
channel.increaseMetaCounters(COUNTER_MAP, MetaCounterHandler handler);
channel.getMetaCounters(KEYS, MetaCounterHandler handler);

Event handler

Also, the SendBirdEventHandler, SendBirdSystemEventHandler, and SendBirdNotificationHandler are all replaced with the ChannelHandler. Your client app can get notified through channel handlers which support a variety of events. See the Event Handler page for more information.


Push notifications

To register a FCM/GCM registration token of the current user to SendBird server in v3, it is recommended that you call the registerPushTokenForCurrentUser method right after a connection is established. See the Push Notifications page for more information.

Light Color Skin
Copy
// v2
SendBird.login(SendBird.LoginOption.build(UUID).setUserName(NICKNAME).setGCMRegToken(TOKEN));

// v3
SendBird.connect(USER_ID, new SendBird.ConnectHandler() {
    @Override
    public void onConnected(User user, SendBirdException e) {

        ...

        SendBird.registerPushTokenForCurrentUser(TOKEN, new SendBird.RegisterPushTokenWithStatusHandler() {
            @Override
            public void onRegistered(SendBird.PushTokenRegistrationStatus ptrs, SendBirdException e) {
                if (e != null) {
                    return;
                }

                if (ptrs == SendBird.PushTokenRegistrationStatus.PENDING) {
                    // A token registration is pending.
                    // Retry the registration after a connection has been successfully established.
                }
            }
        });
    }
});