Migration from v2

SDK 3.0 (v3) is a fully innovated chat solution for mobile apps and websites. The structure is elegant and the performance has increased dramatically.

  • OpenChannel and GroupChannel are added for Open Channel and Group Channel related features respectively.
  • UserMessage, FileMessage and AdminMessage are added to handle messages.
  • Callbacks and queries are neatly arranged.

We strongly encourage you in moving to v3 from the previous version and here are the migration tips.


SDK Installation

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

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

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

Authentication

Initialize the SDK

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

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

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

Login to SendBird

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

// 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 (previous Open Chat Channel)

From v3, we call Open Chat Channel as 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 open channels

// v2
ChannelListQuery channelListQuery = SendBird.queryChannelList();
channelListQuery.next(ChannelListQueryResult handler);

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

Connect to an open 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.

// 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 an open channel

You don't have to do anything to disconnect the 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.

// 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 messages to an open channel

Mentioned message is NOT currently supported in v3.

// 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

ChannelHandler replaces SendBirdEventHandler. Multiple ChannelHandlers are allowed.

// 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 an open channel

// 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 in an open 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.

// v2
SendBird.queryMemberList(CHANNEL_URL, TRUE_OR_FALSE).get(MemberListQueryResult handler);

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

Group Channel (Previous Messaging Channel)

From v3, we call Messaging Channel as Group Channel. Users joined a group channel are referred to as Members of the channel. GroupChannel and GroupChannelListQuery handle Group Channel related features.

Create a group channel

All startMessaging related methods are replaced by createChannel and createChannelWithUserIds.

// v2
SendBird.startMessaging(USER_IDS);

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

Retrieve a list of group channels

// 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 group 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.

// 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 group channel

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

// v2
SendBird.disconnect();

// v3
// Do nothing.

Invite a user to an existing group channel as a member

// v2
SendBird.inviteMessaging(CHANNEL_URL, USER_ID);

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

Remove a member from a group channel

// v2
SendBird.endMessaging(CHANNEL_URL);

// v3
groupChannel.leave(GroupChannelLeaveHandler handler);

Send messages to a group channel

Mentioned message is NOT currently supported in v3.

// 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

ChannelHandler replaces SendBirdEventHandler. Multiple ChannelHandlers are allowed.

// 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 group channel

// 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.

// v2
SendBird.registerNotificationHandler(SendBirdNotificationHandler handler);

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

Retrieve a list of all members in a group channel

// v2
messagingChannel.getMembers();

// v3
groupChannel.getMembers();

Send typing indicators to other members in a group channel

// v2
SendBird.typeStart();
SendBird.typeEnd();

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

Retrieve a read receipt of a message in a group channel

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.

// v2
long timestamp = messagingChannel.getLastReadMillis(USER_ID);

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

Mark messages as read in a group channel

// 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

// 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

// 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

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


Push Notifications

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

// 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);
    }
});