From v2 to v3

UIKit v3 for iOS 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 iOS 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 of UIKit using a view controller, which is composed of a module and a view model. In each key function, the module is used to create and display everything UI-related while the view model is in charge of managing data from Chat SDK to apply to each view. 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 in each key function.

In every key function provided by Sendbird UIKit, there's a module, which is composed of several components, in each view controller. These components, also referred to as module components, make up the view in the corresponding key function to create and display an interactive UI. Unlike v2 where the view controller handled all UI-related features, the modules and components now manage the UI of each view controller in v3. These modules and components are customizable to fit your own design needs.

Note: The SBUModuleSet in UIKit v3.0 for iOS has been deprecated starting in v3.5. Refer to the new migration guide from UIKit v3.5 to v3.6.

All modules are owned and managed by the SBUModuleSet global class. If you don't want to use the default module and component provided by UIKit, you can set a custom module and component in the SBUModuleSet so the customized objects become the default settings throughout the entire client app.

All components use a delegate to send events that occur in the view to the view controller and a data source object to receive necessary data from the view controller. Refer to the table below to learn about the relationship between key function, module, component, and view controller.

In a key function, each view controller has a corresponding view model, which processes and requests data directly from Sendbird Chat SDK. Without needing to call the Chat SDK interface, the view controller can simply use a view model to manage and process data needed to build a view in UIKit. Every view model has a delegate that is used to send data updates in the form of events to the view controller. It also uses a data source object to gather necessary data from the view controller.

Refer to the table below to learn about the relationship between key function, view model, and view controller.

Starting in v3 of UIKit for iOS, SBUViewControllerSet and SBUModuleSet have been added to minimize inheriting and overriding when customizing views. In v3, you can now set a custom view controller and module in SBUViewControllerSet and SBUModuleSet respectively, in order to make changes to the view.

In Sendbird UIKit, there is a SBUViewControllerSet global class that manages the view controllers of all key functions. SBUViewControllerSet is a property that's composed of class types of all the view controller classes.

If you don't want to use the default view controller provided by the UIKit, you can set a custom view controller within SBUViewControllerSet. By implementing a view controller that's been customized in the global class, you can use it across the entire client app without having to change it each time. Refer to the example code below:

class CustomGroupChannelListViewController: SBUGroupChannelListViewController {
    // Implement custom code here.
}

// Implement anywhere before using `GroupChannelListViewController`.
SBUViewControllerSet.GroupChannelListViewController = CustomGroupChannelListViewController.self

You can also still use the existing customization method in v2 where you directly implement your own custom view controller.

When creating a custom view controller instance, Sendbird UIKit follows the order of usage below:

1. A view controller that's been customized upon initial setting.
2. A view controller that's been customized within SBUViewControllerSet.
3. A non-customized, default view controller provided by Sendbird UIKit.

If you didn't set your own custom view controller, then a view controller that's been customized within SBUViewControllerSet is used instead throughout the UIKit. If there are no custom view controllers, the default view controller provided by Sendbird UIKit in SBUViewControllerSet is used.

In Sendbird UIKit, there is a SBUModuleSet global class that manages all modules and each module is composed of various components. The global SBUModuleSet provides the corresponding module and its components to each view controller.

If you don't want to use the default module and component provided by the UIKit, you can set a custom module and component in SBUModuleSet so the customized objects become the default setting throughout the entire UIKit without having to change them each time. Refer to the example codes below:

class CustomModule: SBUGroupChannelListModule {
    // Implement custom code here.
}

// Implement anywhere before using `channelListModule`.
SBUModuleSet.channelListModule = CustomModule()

class CustomComponent: SBUChannelListModule.Header {
    // Implement custom code here.
}

// Implement anywhere before using `channelListModule.headerComponent`.
SBUModuleSet.channelListModule.headerComponent = CustomComponent()

When using a customized module or its component, the view controller follows the order below:

1. A module or component that's been customized in the view controller.
2. A custom module or component that's been customized in SBUModuleSet.
3. A non-customized, default module and component provided by Sendbird UIKit.

If you didn't set a custom module or component in the view controller, then a custom module or component that's been set in SBUModuleSet is used instead throughout the UIKit. If there are no custom modules or components, the default objects provided by Sendbird UIKit in SBUModuleSet are used.

See the breaking changes below in each key function.

Note : You'll be notified of changes in the code through warning and error messages in the build phase of Xcode.

The following tables show the changes made to the initialization functions in UIKit v3. When initializing Sendbird UIKit, we recommend displaying a loading indicator to show the initialization progress and indicate that other succeeding steps should wait. The indicator should be displayed when startHandler is called and hidden when completionHandler is called. Refer to initialize(applicationId:startHandler:migrationHandler:completionHandler:) in SendbirdUI.

The following tables show what changes were made in SBUStringSet from v2 to v3.

The following objects have been added to SBUStringSet in v3:

• UserList_Title_Muted_Participants
• Empty_No_Muted_Participants

• MemberList_Header_Title

The following tables show what changes were made from v2 to v3.

The following tables show what changes were made in SBUChannelListViewController from v2 to v3.

The following objects have been added to SBUGroupChannelListViewController in v3:

• headerComponent
• listComponent
• viewModel

To learn more, go to the Usage section of the view controller page.

Due to the addition of local caching, the following properties have been deprecated in v3:

• isLoading
• lastUpdatedTimestamp
• lastUpdatedToken

The following methods have been moved to the view model in v3:

• loadNextChannelList(reset:)
• sortChannelList(needReload:)
• updateChannels(_:needReload:)
• upsertChannels(_:needReload:)
• deleteChannels(channelURLs:needReload:)
• changePushTriggerOption(option:channel:completionHandler:)
• leaveChannel(_:completionHandler:)

Due to the addition of local caching, the following methods have been deprecated in v3:

• channel(_:userDidJoin user:)
• channel(_:userDidLeave user:)
• channelWasChanged(_:)
• channel(_:messageWasDeleted:)
• channelWasFrozen(_:)
• channelWasUnfrozen(_:)
• channel(_:userWasBanned:)
• didSucceedReconnection()

The following tables show what changes were made in SBUBaseChannelViewController from v2 to v3.

The following objects have been added to SBUBaseChannelViewController in v3:

• baseHeaderComponent
• baseListComponent
• baseInputComponent
• baseViewModel

Depending on the channel type, the base components and base view model become channel-specific. The appropriate components and view model are then used in each SBUGroupChannelViewController and SBUOpenChannelViewController.

The following methods have been moved to the view model in v3:

• loadChannel(channelURL:messageListParams:)
• clearMessageList()
• upsertMessagesInList(messages:needUpdateNewMessage:needReload:)
• deleteMessagesInList(messageIds:excludeResendableMessages:needReload:)
• deleteResendableMessage(_:needReload:)
• deleteResendableMessages(requestIds:needReload:)
• sortAllMessageList(needReload:)
• updateUserMessage(message:text:)
• updateUserMessage(message:messageParams:)
• resendMessage(failedMessage:)
• sendUserMessage(text:)
• sendUserMessage(text:parentMessage:)
• sendUserMessage(messageParams:parentMessage:)
• sendFileMessage(fileData:fileName:mimeType:)
• sendFileMessage(fileData:fileName:mimeType:parentMessage:)
• sendFileMessage(messageParams:parentMessage:)

The following tables show what changes were made in SBUChannelViewController from v2 to v3.

The following objects have been added to SBUGroupChannelViewController in v3:

• headerComponent
• listComponent
• inputComponent
• viewModel

To learn more, go to the Usage section of the view controller page.

The following methods have been moved to the view model in v3:

• channel(_:didReceive:)
• channel(_:didUpdate:)
• channel(_:messageWasDeleted:)
• didSucceedReconnection()

The following tables show what changes were made in SBUOpenChannelViewController from v2 to v3.

The following objects have been added to SBUOpenChannelViewController in v3:

• headerComponent
• listComponent
• inputComponent
• mediaComponent
• viewModel

To learn more, go to the Usage section of the view controller page.

The following methods have been moved to the view model in v3:

• loadChannel(channelURL:messageListParams:)
• updateMessagesInList(messages:needReload:)
• channel(_:didUpdate:)
• channel(_:messageWasDeleted:)
• didSucceedReconnection()

The following tables show what changes were made in SBUCreateChannelViewController from v2 to v3.

The following objects have been added to SBUCreateChannelViewController in v3:

• headerComponent
• listComponent
• viewModel

To learn more, go to the Usage section of the view controller page.

The following methods have been moved to the view model in v3:

• loadNextUserList(reset:users:)
• createChannel(userIds:)
• createChannel(params:messageListParams:)
• selectUser(user:)

In v3, the SBUInviteUserViewController class has separated into SBUInviteUserViewController and SBURegisterOperatorViewController and SBUBaseSelectUserViewController was added to include shared properties and methods between the two features. The following tables show what changes were made in SBUInviteUserViewController from v2 to v3.

The following objects have been added to SBUInviteUserViewController and SBURegisterOperatorViewController in v3:

• headerComponent
• listComponent
• viewModel

To learn more, go to the Usage section for group channel or open channel under Key functions.

After the view controller class got separated into two view controllers, the type parameter has been removed from the initializers.

The following methods have been moved to the view model in v3:

• loadChannel(channelURL:type:)
• loadNextUserList(reset:users:)
• inviteUsers()
• resetUserList()
• selectUser(user:)

The following tables show what changes were made in SBUMemberListViewController from v2 to v3.

The following objects have been added to SBUUserListViewController in v3:

• headerComponent
• listComponent
• viewModel

To learn more, go to the Usage section for group channel or open channel under Key functions.

The type parameter name has been changed to userListType.

The following methods have been moved to the view model in v3:

• channelDidUpdateOperators(_:)
• channel(_:userDidJoin:)
• channel(_:userDidLeave:)
• channel(_:userDidExit:)
• channel(_:userDidEnter:)

The following tables show what changes were made in SBUBaseChannelSettingViewController from v2 to v3.

The following objects have been added to SBUBaseChannelSettingsViewController in v3:

• headerComponent
• listComponent
• viewModel

The following methods have been moved to the view model in v3:

• loadChannel(channelURL:)
• updateChannel(channelName:coverImage:)
• channel(_:userDidEnter:)
• channel(_:userDidExit:)
• channel(_:userDidJoin:)
• channel(_:userDidLeave:)

The following tables show what changes were made in SBUChannelSettingsViewController from v2 to v3.

The following objects have been added to SBUGroupChannelSettingsViewController in v3:

• headerComponent
• listComponent
• viewModel

To learn more, go to the Usage section of the view controller page.

The following methods have been moved to the view model in v3:

• loadChannel(channelURL:)
• updateChannel(channelName:coverImage:)
• updateChannel(params:)
• leaveChannel()

The following lists show what changes were made in SBUOpenChannelSettingsViewController from v2 to v3.

The following objects have been added to SBUOpenChannelSettingsViewController in v3:

• headerComponent
• listComponent
• viewModel

To learn more, go to the Usage section of the view controller page.

The following methods have been moved to the view model in v3:

• loadChannel(channelURL:)
• updateChannel(channelName:coverImage:)
• updateChannel(params:)
• deleteChannel()

The following tables show what changes were made in SBUModerationsViewController from v2 to v3.

The following objects have been added to SBUModerationsViewController in v3:

• headerComponent
• listComponent
• viewModel

To learn more, go to the Usage section for group channel or open channel under Key functions.

The following method has been moved to the view model in v3:

• loadChannel(channelURL:)

The following tables show what changes were made in SBUMessageSearchViewController from v2 to v3.

The following objects have been added to SBUMessageSearchViewController in v3:

• headerComponent
• listComponent
• viewModel

To learn more, go to the Usage section of the view controller page.

The following method has been moved to the view model in v3:

• message(at:)