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 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.
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:
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.
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.
// Use non-customized fragments through the builder.
val fragment: Fragment = ChannelListFragment.Builder()
.setUseHeader(false)
.build()
// Use custom fragments.
class CustomChannelListFragment : ChannelListFragment() {
override fun onConfigureParams(module: ChannelListModule, args: Bundle) {
val params = module.params
params.setUseHeader(false)
}
}
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.
// Apply custom theme to non-customized fragments through the builder.
val fragment: Fragment = ChannelListFragment.Builder(R.style.custom_theme_resource_id).build()
// Apply custom theme to customized fragments.
class CustomChannelListFragment : ChannelListFragment() {
override fun onCreateModule(args: Bundle): ChannelListModule {
val params = ChannelListModule.Params(requireContext(), R.string.custom_theme_resource_id)
return ChannelListModule(requireContext(), params)
}
}
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.
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 custom ChannelListFragment as an example.
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 custom UIKitFragmentFactory.
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.
KotlinJava
class CustomFragmentFactory : UIKitFragmentFactory() {
override fun newChannelFragment(channelUrl: String, args: Bundle): Fragment {
return ChannelFragment.Builder(channelUrl)
.setCustomFragment(CustomChannelFragment())
.withArguments(args)
.build()
}
}
Set the custom fragment factory to Application using SendbirdUIKit.setUIKitFragmentFactory(UIKitFragmentFactory).
KotlinJava
class MyApplication : Application() {
override fun onCreate() {
SendbirdUIKit.setUIKitFragmentFactory(CustomFragmentFactory())
}
}
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.
val fragment: Fragment = ChannelListFragment.Builder()
.setHeaderLeftButtonListener(leftButtonListener)
.setHeaderRightButtonListener(rightButtonListener)
.setItemClickListener(itemClickListener)
.setItemLongClickListener(itemLongClickListener)
.build()
val fragment: Fragment = ChannelListFragment.Builder()
.setOnHeaderLeftButtonClickListener(leftButtonListener)
.setOnHeaderRightButtonClickListener(rightButtonListener)
.setOnItemClickListener(itemClickListener)
.setOnItemLongClickListener(itemLongClickListener)
.build()
val fragment: Fragment = ChannelFragment.Builder(channelUrl)
.setHeaderLeftButtonListener(leftButtonListener)
.setHeaderRightButtonListener(rightButtonListener)
.setInputLeftButtonListener(inputClickListener)
.setOnProfileClickListener(profileClickListener)
.build()
val fragment: Fragment = ChannelFragment.Builder(channelUrl)
.setOnHeaderLeftButtonClickListener(leftButtonListener)
.setOnHeaderRightButtonClickListener(rightButtonListener)
.setOnInputLeftButtonClickListener(inputClickListener)
.setOnMessageProfileClickListener(profileClickListener)
.build()
In the ChannelFragment.Builder class, the setListItemClickListener method and setListItemLongClickListener method have separated into individual event listener methods for each view item.
val fragment: Fragment = ChannelFragment.Builder(channelUrl)
.setListItemClickListener(identifiableItemClickListener)
.setListItemLongClickListener(identifiableItemLongClickListener)
.build()
// Or use the code below.
class CustomChannelFragment : ChannelFragment() {
override fun onIdentifiableItemClick(view: View, identifier: String, message: BaseMessage) {
when (identifier) {
is StringSet.Chat -> {}
is StringSet.Profile -> {}
is StringSet.QuoteReply -> {}
}
}
}
val fragment: Fragment = OpenChannelFragment.Builder(channelUrl)
.setHeaderLeftButtonListener(leftButtonListener)
.setHeaderRightButtonListener(rightButtonListener)
.setInputLeftButtonListener(inputClickListener)
.setOnProfileClickListener(profileClickListener)
.build()
val fragment: Fragment = OpenChannelFragment.Builder(channelUrl)
.setOnHeaderLeftButtonClickListener(leftButtonListener)
.setOnHeaderRightButtonClickListener(rightButtonListener)
.setOnInputLeftButtonClickListener(inputClickListener)
.setOnProfileClickListener(profileClickListener)
.build()
In the OpenChannelFragment.Builder class, the setListItemClickListener method and setListItemLongClickListener method have now been divided into individual event listener methods for each view item.
val fragment: Fragment = OpenChannelFragment.Builder(channelUrl)
.setListItemClickListener(identifiableItemClickListener)
.setListItemLongClickListener(identifiableItemLongClickListener)
.build()
// Or use the code below.
class CustomChannelFragment : OpenChannelFragment() {
override fun onIdentifiableItemClick(view: View, identifier: String, message: BaseMessage) {
when (identifier) {
is StringSet.Chat -> {}
is StringSet.Profile -> {}
}
}
}
val fragment: Fragment = OpenChannelFragment.Builder(channelUrl)
.setOnMessageClickListener(messageClickListener)
.setOnProfileClickListener(messageProfileClickListener)
.setOnMessageLongClickListener(messageLongClickListener)
.setOnMessageProfileLongClickListener(messageProfileLongClickListener)
.build()
// Or use the code below.
class CustomOpenChannelFragment : OpenChannelFragment() {
override fun onMessageClicked(view: View, position: Int, message: BaseMessage) {}
override fun onMessageProfileClicked(view: View, position: Int, message: BaseMessage) {}
}
val fragment: Fragment = CreateChannelFragment.Builder(CreateableChannelType.Normal)
.setHeaderLeftButtonListener(leftButtonListener)
.setCustomUserListQueryHandler(customQueryHandler)
.build()
val fragment: Fragment = CreateChannelFragment.Builder(CreatableChannelType.Normal)
.setOnHeaderLeftButtonClickListener(leftButtonListener)
.setCustomPagedQueryHandler(customQueryHandler)
.build()
val fragment: Fragment = ChannelSettingsFragment.Builder(channelUrl)
.setHeaderLeftButtonListener(leftButtonListener)
.setMemberSettingClickListener(memberSettingClickListener)
.setOnSettingMenuClickListener(menuClickListener)
.build()
val fragment: Fragment = ChannelSettingsFragment.Builder(channelUrl)
.setOnHeaderLeftButtonClickListener(leftButtonListener)
.setOnMenuClickListener(menuItemClickListener)
.build()
val fragment: Fragment = OpenChannelSettingsFragment.Builder(channelUrl)
.setHeaderLeftButtonListener(leftButtonListener)
.setMemberSettingClickListener(memberSettingClickListener)
.setOnSettingMenuClickListener(menuClickListener)
.build()
val fragment: Fragment = OpenChannelSettingsFragment.Builder(channelUrl)
.setOnHeaderLeftButtonClickListener(leftButtonListener)
.setOnMenuClickListener(menuItemClickListener)
.build()
val fragment: Fragment = InviteUserFragment.Builder(channelUrl)
.setHeaderLeftButtonListener(leftButtonListener)
.setUserListAdapter(userListAdapter)
.setCustomUserListQueryHandler(userListQueryHandler)
.build()
val fragment: Fragment = InviteUserFragment.Builder(channelUrl)
.setOnHeaderLeftButtonClickListener(leftButtonListener)
.setInviteUserListAdapter(inviteUserListAdapter)
.setCustomPagedQueryHandler(customPagedQueryHandler)
.build()
val fragment: Fragment = RegisterOperatorFragment.Builder(channelUrl)
.setHeaderLeftButtonListener(leftButtonListener)
.setUserListAdapter(userListAdapter)
.setCustomUserListQueryHandler(userListQueryHandler)
.build()
val fragment: Fragment = RegisterOperatorFragment.Builder(channelUrl)
.setOnHeaderLeftButtonClickListener(leftButtonListener)
.setRegisterOperatorListAdapter(registerOperatorListAdapter)
.setCustomPagedQueryHandler(customPagedQueryHandler)
.build()