Android
Migration

Migration from v2

The Android SDK 3.0 (v3) has been fully changed from the 2.0 and supports your chat solution on any mobile apps and websites. The structure has been improved and the performance has increased dramatically.

  • The OpenChannel and GroupChannel classes have been added for an open channel and a group channel related features respectively.
  • 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 neatly arranged.

We strongly recommend that you move to v3 from the previous version with the following migration guides.


Installation

If you are using gradle, just change the version of dependencies in build.gradle at app level (not 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

You still need to initialize SendBird once when your application begins.

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

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

Login

login is no longer used in v3. Calling connect just once after init is all you have to do.

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 push tokens, now you can use updateCurrentUserInfo and registerPushTokenForCurrentUser after connection is established.


Open channel (formerly an open chat channel)

From v3, we call an open chat channel as an open channel. Members having entered an open channel are referred to as Participants of the channel. OpenChannel and OpenChannelListQuery handle the Open Channel related features.

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

You don't have to do anything to connect to each open channel in v3. All required connections are automatically made once you have called connect after init. Plus, entering an open channel is much simpler in v3. In v2, you needed to fetch channel URL and call join, queryMessageList and connect.

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) {
        openChannel.enter(OpenChannelEnterHandler handler);
    }
});

Disconnect from a channel

You don't have to do anything to disconnect an open channel in v3. All connections are automatically disconnected when you call disconnect on application termination. If you want a user to leave the open channel, just call 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) {
        openChannel.exit(OpenChannelExitHandler handler);
    }
});

Send a message to a channel

Mentioned message is NOT currently supported in v3.

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

A ChannelHandler replaces the SendBirdEventHandler. Multiple ChannelHandlers are allowed.

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
MessageListQuery messageListQuery = openChannel.createMessageListQuery();
messageListQuery.prev(EARLIEST_MESSAGE_TIMESTAMP, LIMIT, REVERSE_ORDER, MessageListQueryResult handler);

Retrieve a list of all participants of a channel

Participant means online users in a certain open channel. Once a user leaves the open channel, the user is no longer participant of that channel and query does not include him/her.

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 (previously a messaging channel)

From v3, we call a messaging channel as a group channel. Users joined a group channel are referred to as members of the channel. The GroupChannel and GroupChannelListQuery class handle the features related to group channels.

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

You don't have to do anything to connect to each group channel in v3. All required connections are automatically made once you have called connect after init.

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

You don't have to do anything to disconnect a group channel in v3. All connections are automatically disconnected when you call disconnect on application termination.

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

Mentioned message is NOT currently supported in v3.

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

A ChannelHandler replaces the SendBirdEventHandler. Multiple ChannelHandlers are allowed.

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, TRUE_OR_FALSE, MessageListQueryResult handler);

Monitor multiple group channels with a notification handler

ChannelHandler replaces SendBirdNotificationHandler. For details, please refer to Event Handler.

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

From v3, various of methods to get read receipt are possible. You can get a timestamp for a certain member just like in v2 or the automatically calculated read receipt as well.

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

Metadata and metacounter can be created, updated and read in v3 by counter parts of methods in v2.

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

From v3, the SendBirdEventHandler, SendBirdSystemEventHandler and SendBirdNotificationHandler are replaced by a ChannelHandler. Please refer to Event Handler for details.


Push notifications

From v3, you have to call the registerPushTokenForCurrentUser method explicitly after connection is made to register push tokens. Please refer to Push Notifications for details.

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, RegisterPushTokenWithStatusHandler handler);
    }
});