Chat UIKit iOS v3
Chat UIKit iOS
Chat UIKit
iOS
Version 3

Send your first message

Copy link

Sendbird UIKit for iOS is a set of prebuilt UI components that allows you to easily craft an in-app chat with all the essential messaging features. Our development kit includes light and dark themes, fonts, colors and more. You can customize these components to create an interactive messaging interface unique to your brand identity.

Sendbird UIKit supports both open channels and group channels. Follow the guide below to start sending a message from scratch using Swift.


Requirements

Copy link

The minimum requirements for UIKit for iOS are:

  • iOS 11.0 and later
  • Swift 5.0+
  • Xcode 14.1 and later
  • Sendbird Chat SDK for iOS 4.0.13 and later

Note: Starting on April 25, 2023, you must build and test your app with Xcode 14.1 or later to submit to the App Store. You can use the existing Sendbird SDK versions built with both Xcode 13.x and Xcode 14.1+ but Sendbird is repackaging Chat UIKit for iOS with Xcode 14.1 and minimum iOS version of 11.0 starting on April 25, 2023.


Before you start

Copy link

Before installing Sendbird Chat SDK, you need to create a Sendbird application on the Sendbird Dashboard, which comprises everything required in a chat service including users, messages, and channels. You will need the App ID of your Sendbird application when initializing the Chat SDK.

Note: Each Sendbird application can be integrated with a single client app. Within the same application, users can communicate with each other across all platforms, whether they are on mobile devices or on the web.


Get started

Copy link

You can start building a messaging experience in your app by installing Sendbird UIKit. This developer kit is an add-on feature to Sendbird Chat SDK so installing it will also install the core Chat SDK. The minimum requirement of Chat SDK for iOS is 4.0.13 or later.

Step 1 Create a project

Copy link

To get started, open Xcode and create a new project. Sendbird UIKit supports swift.

Step 2 Install UIKit

Copy link

You can install UIKit for iOS through either Swift Packages, CocoaPods, or Carthage.

Swift Packages

Copy link
  1. In Xcode, select File > Add Packages.

  2. Search for SendbirdUIKit spm repository and add it to your Package repository. You can also choose the dependency rule that you want to use in the repository and keep the latest version by selecting the main branch.

https://github.com/sendbird/sendbird-uikit-ios-spm
  1. When finished, Xcode automatically begins resolving and downloading your dependencies to the repository in the background.

Note: A build error may occur whlie using Swift packages with Xcode due to issues with caching. To resolve this error, try resetting the Xcode package caches. Open the File menu, go to Packages, and select Reset Pacakge Caches. This deletes all local package data and redownloads each package from its online source.

CocoaPods

Copy link
  1. Add SendBirdUIKit into your Podfile in Xcode as below:
platform :ios, '11.0'
use_frameworks!

target YOUR_PROJECT_TARGET do
    pod 'SendBirdUIKit' # Add this line.
end
  1. Install the SendBirdUIKit framework through CocoaPods.
$ pod install
  1. Update the SendBirdUIKit framework through CocoaPods.
$ pod update

Carthage

Copy link
  1. Add SendbirdUIKit and SendbirdChatSDK into your Cartfile as below:
github "sendbird/sendbird-uikit-ios"
github "sendbird/sendbird-chat-sdk-ios"
  1. Install the SendbirdUIKit framework through Carthage.
$ carthage update --use-xcframeworks

Note: Building or creating the SendbirdUIKit framework with Carthage can only be done using the latest Swift. If your Swift is not the most recent version, the framework should be copied into your project manually.

  1. Go to your Xcode project target's General settings tab in the Frameworks and Libraries section. Then drag and drop SendbirdUIKit.xcframework and SendbirdChatSDK.xcframework from the <YOUR_XCODE_PROJECT_DIRECTORY>/Carthage/Build folder.

Note: Errors may occur if you're building your project with Xcode 11.3 or earlier versions. To fix these errors, refer to Handle errors caused by unknown attributes.

Step 3 Initialize with APP_ID

Copy link

To integrate and run Sendbird UIKit in your app, you need to first initialize the SendbirdUI instance through AppDelegate.

Sendbird UIKit relies on local caching and synchronization for efficient data handling. Due to local caching, the data base must be migrated during the initialization process of the SendbirdUI instance. And, the UIKit won’t advance to subsequent steps until its initialization process has been fully completed. To enhance user experience and manage expectations during this process, we recommend you implement a visual loading indicator as follows:

  • Display when startHandler is called.
  • Hide when completionHandler is called.

Note: If you wish to have the initialization run asynchronously, you can set the needsSynchronous parameter to false within InitParams of the initParamsBuilder block.

// AppDelegate.swift

import SendbirdUIKit

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    let APP_ID = "YOUR_APP_ID"    // Specify your Sendbird application ID.

    SendbirdUI.initialize(
        applicationId: APP_ID
    ) { params in
        // This is the builder block where you can modify the initParameter.
        //
        // [example]
        // params.needsSynchronous = false
    } startHandler: {
        // This is the origin.
        // Initialization of SendbirdUIKit has started.
        // We recommend showing a loading indicator once started.
    } migrationHandler: {
        // DB migration has started.
    } completionHandler: { error in
        // If DB migration is successful, proceed to the next step.
        // If DB migration fails, an error exists.
        // We recommend hiding the loading indicator once done.
    }
}

The initParamsBuilder of the initialize(applicationId:initParamsBuilder:migrationHandler:completionHandler:) function of the SendbirdUI class allows you to modify the use of local caching and the synchronization settings of the initialization task.

Also, if you are using local caching, you can also set the needsSynchronous parameter of the InitParams object to true to ensure that the migration process is completed before the app is fully launched. By default, the needsSynchronous parameter is set to false so that migration proceeds asynchronously for reduced initialization time and thus expedited performance and runtime. However, if you don't need Sendbird UIKit's features upon launching your app, you can set the needsSynchronous parameter to true and have it run synchronously. If you aren't using local caching, this parameter doesn't affect the initialization process.

In the meantime, when you need to call one of the UIKit's functions asynchronously from a different class or method, use the executeOrWaitForInitialization(executeHandler:) method of the SendbirdChat class. This function ensures either of the following two scenarios:

  • If the SendbirdUI initialization has been completed, the function executes the executeHandler block immediately.
  • If not, the function waits until the initialization is completed and then executes the executeHandler block.

This approach allows for seamless integration of the UIKit's functionalities, ensuring that initialization dependencies are properly managed.

Swift
SendbirdChat.executeOrWaitForInitialization {
    // Implement logic to perform once initialization is complete
}

Step 4 Set current user

Copy link

User information must be set as currentUser in the SBUGlobals prior to launching Sendbird UIKit. This information will be used for various tasks within the kit, and if you don't set currentUser in advance, there will be restrictions while using the UIKit. The userID field shown below must be specified. Other fields such as nickname and profileURL are optional, and if not specified, they'll be filled with default values.

Set currentUser for UIKit through the AppDelegate as below:

Note: Even if you don't use AppDelegate, you should still register user information before launching a chat service.

// AppDelegate.swift

import SendbirdUIKit

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    // Initialize with APP_ID on Step 3

    // Case 1: USER_ID only
    SBUGlobals.currentUser = SBUUser(userId: {USER_ID})

    // Case 2: Specify all fields
    SBUGlobals.currentUser = SBUUser(userId: {USER_ID}, nickname:{(opt)NICKNAME}, profileURL:{(opt)PROFILE_URL})

}

Step 5 Display channel list

Copy link

SBUGroupChannelListViewController is the starting point for launching UIKit in your app. Implement the code below wherever you would like to start UIKit. You can see a complete list of group channels that you're a member of.

import SendbirdUIKit;

let channelListVC = SBUGroupChannelListViewController()
let naviVC = UINavigationController(rootViewController: channelListVC)
self.present(naviVC, animated: true)

Note: If you are already using a navigation controller, you can use the pushViewController function.

Step 6 Send your first message

Copy link

You can now run the app on a simulator or a plugged-in device. To send a message, you must first create a group channel by tapping the icon in the top-right corner. Then, you can select users you wish to invite as members to your channel. Once the channel has been created, enter your first message and send.

Note: Sendbird UIKit offers features to attach or save files such as photos, videos, and documents in addition to sending text messages. To learn more about using these features, refer to Get attachment permission in the sample app.

You've successfully sent your first message with Sendbird.

Note: If you wish to distribute your application in the App store and remove unnecessary architectures in the application's build phase, go to Distribution settings in the sample app.


Get attachment permission

Copy link

Sendbird UIKit allows users to attach or save files such as photos, videos, and documents. To use these functionalities, you need to request permission from users using your client apps.

Media attachment permission

Copy link

Client apps must acquire permission from end users to use their photos or save media to their library. Once the permission is granted, users can send image or video messages and download media assets.

...
<key>NSPhotoLibraryUsageDescription</key>
    <string>$(PRODUCT_NAME) would like access to your photo library</string>
<key>NSCameraUsageDescription</key>
    <string>$(PRODUCT_NAME) would like to use your camera</string>
<key>NSMicrophoneUsageDescription</key>
    <string>$(PRODUCT_NAME) would like to use your microphone (for videos)</string>
<key>NSPhotoLibraryAddUsageDescription</key>
    <string>$(PRODUCT_NAME) would like to save photos to your photo library</string>
...

Document attachment permission (optional)

Copy link

To attach documents from iCloud to file messages, you need to activate the iCloud feature. Once activated, users can send file messages containing documents from iCloud. Go to your Xcode project's Signing & Capabilities, add + Capability, and select iCloud. Check iCloud Documents.


UIKit components

Copy link

UIKit for iOS manages the lifecycle of its ViewController along with various views and data from the Chat SDK for iOS. UIKit components are as follows:

List of components

Copy link
ComponentDescription

SBUGroupChannelListViewController

A ViewController that manages a channel list.

SBUGroupChannelViewController
SBUOpenChannelViewController

A ViewController that manages a 1-on-1 chat channel.

SBUGroupChannelSettingsViewController
SBUOpenChannelSettingsViewController

A ViewController that manages the channel settings.

SBUCreateChannelViewController

A ViewController that creates a channel.

SBUInviteUserViewController

A ViewController that invites a user to a channel.

SBURegisterOperatorViewController

A ViewController that registers a user as an operator of a channel.

SBUUserListViewController

A ViewController that shows a list of users in a channel.

SBUMessageSearchViewController

A ViewController that searches a message in a channel.

SBUTheme

A singleton that manages themes.

SBUColorSet

A singleton that manages color sets.

SBUFontSet

A singleton that manages font sets.

SendbirdUI

A class that contains static functions required when using Sendbird UIKit.

SBUGlobals

A class that contains static attributes required when using Sendbird UIKit.