Migration guide
UIKit v3 for Android is now available. UIKit v3 has a dependency on Chat SDK v4. Before migrating from v2 to v3, refer to the migration guide of Chat SDK v4 for Android for any breaking changes. The Chat SDK must be updated first before proceeding with the latest version of UIKit.
The biggest change from v2 to v3 is modularization, which allows you to build and customize views at a component level. You can execute key functions, such as list channels, using a fragment, module, and view model. Each fragment has a module that creates the view, and each module is made up of components. A fragment also has a corresponding ViewModel
that provides the necessary data and APIs from Sendbird Chat SDK. This new architecture allows for easier and more detailed customization.
When migrating from v2 to v3, there are several breaking changes you need to remember. Since modules and view models are one of the main parts of the new architecture, you need to make changes to the existing codes in your client app. Refer to the breaking changes below.
Key functions
Key functions are carried out on a screen basis, meaning each function corresponds to a single screen. In v3, a key function is composed of three main components: fragment, module, and ViewModel
. Refer to the table below to see which key functions we provide and the components that make up each key function.
Key function | Fragment | Module | Component | ViewModel |
---|---|---|---|---|
ChannelListFragment | ChannelListModule | HeaderComponent | ChannelListViewModel | |
ChannelFragment | ChannelModule | ChannelHeaderComponent | ChannelViewModel | |
OpenChannelFragment | OpenChannelModule | OpenChannelHeaderComponent | OpenChannelViewModel | |
CreateChannelFragment | CreateChannelModule | SelectUserHeaderComponent | CreateChannelViewModel | |
ChannelSettingsFragment | ChannelSettingsModule | ChannelSettingsHeaderComponent | ChannelSettingsViewModel | |
OpenChannelSettingsFragment | OpenChannelSettingsModule | OpenChannelSettingsHeaderComponent | OpenChannelSettingsViewModel | |
InviteUserFragment | InviteUserModule | SelectUserHeaderComponent | InviteUserViewModel | |
RegisterOperatorFragment | RegisterOperatorModule | SelectUserHeaderComponent | RegisterOperatorViewModel | |
OpenChannelRegisterOperatorFragment | OpenChannelRegisterOperatorModule | SelectUserHeaderComponent | OpenChannelRegisterOperatorViewModel | |
MemberListFragment | MemberListModule | HeaderComponent | MemberListViewModel | |
ParticipantListFragment | ParticipantListModule | HeaderComponent | ParticipantViewModel | |
BannedUserListFragment | BannedUserListModule | HeaderComponent | BannedUserListViewModel | |
OpenChannelBannedUserListFragment | OpenChannelBannedUserListModule | HeaderComponent | OpenChannelBannedUserListViewModel | |
MutedMemberListFragment | MutedMemberListModule | HeaderComponent | MutedMemberListViewModel | |
OpenChannelMutedParticipantListFragment | OpenChannelMutedParticipantListModule | HeaderComponent | OpenChannelMutedParticipantListViewModel | |
OperatorListFragment | OperatorListModule | HeaderComponent | OperatorListViewModel | |
OpenChannelOperatorListFragment | OpenChannelOperatorListModule | HeaderComponent | OpenChannelOperatorListViewModel | |
ModerationFragment | ModerationModule | HeaderComponent | ModerationViewModel | |
OpenChannelModerationFragment | OpenChannelModerationModule | HeaderComponent | OpenChannelModerationViewModel | |
MessageSearchFragment | MessageSearchModule | MessageSearchHeaderComponent | MessageSearchViewModel |
Configuration changes
To migrate to the new version, open the build.gradle
file at the application level. For both Java
and Kotlin
, add the code blocks and dependencies as follows:
API changes in all fragments
In v3, there are new changes to APIs that create and customize fragments. Refer to the breaking changes that apply to all fragments in the UIKit below.
Default setter method value
In v2, the default value of the setter method in a fragment was set to false
. But in v3, the value has changed to true
. For example, the default value of the setUseHeader()
method in the HeaderComponent
of ChannelListFragment
was previously false
but it's now changed to true
. In fragments that previously didn't use a header region in v2, you must now manually change the value to false
if you don't wish to use it in v3. When using custom fragments, call the onConfigureParams
method to access the setter methods that were previously provided by the builder. Refer to the codes below.
Customize theme
Starting in v3, you can't apply a custom theme to customized fragments using a fragment.builder()
class. In order to do so, you must call the Params
class of the fragment and set the style resource as a parameter. For non-custom fragments, you can apply a custom theme using the builder class. See the codes below.
Note: Go to the Customize style resource page to learn more.
Custom fragment changes
Unlike v2, the new version doesn't allow you to use custom fragments through fragment.builder()
to create a view. You can only use default fragments through the builder class. See the guide below on how to build your own custom fragment.
Create a custom fragment
- Inherit the fragment you wish to make changes to and create a custom fragment.
- In each
fragment.builder()
class, there are UI-related APIs such as view properties, methods, and event handlers. To customize each fragment, you must override those setter methods. Refer to the following codes on how to build a customChannelListFragment
as an example.
List of methods to override
The following table shows a list of methods you must override to build a custom fragment.
To v3
Method | Description |
---|---|
onConfigureParams(ChannelListModule, Bundle) | Specifies the method to change the value of view properties using the parameters of the corresponding component. |
onBeforeReady(ReadyStatus, ChannelListModule, ChannelListViewModel) | Specifies the method to set custom adapters in the component once a view has been created. |
onBindHeaderComponent(HeaderComponent, ChannelListViewModel) | Specifies the method to bind event handlers to |
onBindChannelListComponent(ChannelListComponent, ChannelListViewModel) | Specifies the method to bind event handlers to |
onBindStatusComponent(StatusComponent, ChannelListViewModel) | Specifies the method to bind event handlers to |
Set a custom fragment factory
After creating a custom fragment, follow the guide below on how to set a custom fragment factory. In UIKit v3, all activities use the UIKitFragmentFactory
class to create a fragment. UIKitFragmentFactory
is a global class that provides and manages all fragments used in Sendbird UIKit. While an activity creates the basic UI screen and allows the user to navigate between different screens, the fragment within the activity is what allows you to customize components and manage data.
If you wish to customize a fragment, you need to inherit the UIKitFragmentFactory
class and override the method that creates the fragment. Then, you must return the customized fragment in order to apply the customization throughout the UIKit.
Note: If you're only using fragments to build a screen in UIKit instead of using an activity, you can skip the following steps.
- Inherit the
UIKitFragmentFactory
class to create a customUIKitFragmentFactory
. - Override the method that creates the fragment you wish to customize and return the custom fragment. When returning the fragment, the
Bundle
class containing necessary data to build a view is also returned as parameters.
- Set the custom fragment factory to
Application
usingSendbirdUIKit.setUIKitFragmentFactory(UIKitFragmentFactory)
.
List of methods to inherit
The following table shows a list of methods you must inherit to create a new fragment in each key function.
Key function | Fragment | Method |
---|---|---|
List channels | ChannelListFragment | Fragment newChannelListFragment(Bundle) |
Chat in a group channel | ChannelFragment | Fragment newChannelFragment(String, Bundle) |
Chat in an open channel | OpenChannelFragment | Fragment newOpenChannelFragment(String, Bundle) |
Create a group channel | CreateChannelFragment | Fragment newCreateChannelFragment(CreatableChannelType, Bundle) |
Configure group channel settings | ChannelSettingsFragment | Fragment newChannelSettingsFragment(String, Bundle) |
Configure open channel settings | OpenChannelSettingsFragment | Fragment newOpenChannelSettingsFragment(String, Bundle) |
Invite users | InviteUserFragment | Fragment newInviteUserFragment(String, Bundle) |
Register as operator | RegisterOperatorFragment | Fragment newRegisterOperatorFragment(String, Bundle) |
List channel members | MemberListFragment | Fragment newMemberListFragment(String, Bundle) |
List channel participants | ParticipantListFragment | Fragment newParticipantListFragment(String, Bundle) |
List banned users | BannedUserListFragment | Fragment newBannedUserListFragment(String, Bundle) |
List muted members | MutedMemberListFragment | Fragment newMutedMemberListFragment(String, Bundle) |
List operators | OperatorListFragment | Fragment newOperatorListFragment(String, Bundle) |
Moderate channels and members | ModerationFragment | Fragment newModerationFragment(String, Bundle) |
Search messages | MessageSearchFragment | Fragment newMessageSearchFragment(String, Bundle) |
API changes in each fragment
When migrating from v2 to v3, you should be aware of some changes to the setter methods in the builder class of each fragment. Refer to the codes below to see how to migrate the changed APIs for each fragment builder.
ChannelListFragment.Builder
The following methods have changed names in v3.
ChannelFragment.Builder
The following methods have changed names in v3.
In the ChannelFragment.Builder
class, the setListItemClickListener
method and setListItemLongClickListener
method have separated into individual event listener methods for each view item.
OpenChannelFragment.Builder
The following methods have changed names in v3.
In the OpenChannelFragment.Builder
class, the setListItemClickListener
method and setListItemLongClickListener
method have now been divided into individual event listener methods for each view item.
CreateChannelFragment.Builder
The CreateableChannelType
property has been changed to CreatableChannelType
and the following methods have also changed names in v3.
ChannelSettingsFragment.Builder
The following methods have changed names in v3.
OpenChannelSettingsFragment.Builder
The following methods have changed names in v3.
InviteUserFragment.Builder
The following methods have changed names in v3.
RegisterOperatorFragment.Builder
The following methods have changed names in v3.
MemberListFragment.Builder
The following methods have changed names in v3.
ParticipantListFragment.Builder
The following methods have changed names in v3.
MutedMemberListFragment.Builder
The following methods have changed names in v3.
OperatorListFragment.Builder
The following methods have changed names in v3.
ModerationFragment.Builder
The following methods have changed names in v3.
MessageSearchFragment.Builder
The following methods have changed names in v3.