Send your first message
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
The minimum requirements for UIKit for iOS are:
iOS 12.0 and later
Swift 5.0+
Xcode 15.0 or later
Sendbird Chat SDK for iOS 4.19.0 or later
Note: Starting on April 29, 2024, you must build and test your app with Xcode 15.0 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 15.0 and minimum iOS version of 12.0 starting on April 29, 2024.
Before you start
In this quickstart guide, you will be installing Sendbird SDK, implementing codes to create a open channel with a user, and send a message within a few minutes. Before you start, you need to have the following:
- Sendbird application on Sendbird Dashboard
- A user in the Sendbird application
Create a Sendbird application from dashboard
A Sendbird application comprises everything required in a chat service including users, messages, and channels. You need the Application ID of your Sendbird application from the dashboard when initializing the Chat SDK.
-
Go to Sendbird Dashboard and create an account for a free trial. If you already have a Sendbird account, sign into your account.
-
Create a new application by clicking Create + at the bottom right of your screen.
-
Enter a name for your application. Choose a Product Type and Region. Then, click Confirm.
-
Click the application you just created under Applications. You will see the application's Application ID which you will need 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.
Create a user in the Sendbird application
In order to send a message, you need a user in a channel. You can either create a user on the Sendbird dashboard first or you can use a new unique ID that hasn’t been taken by any of your Sendbird application users. In the latter case, a new user is automatically created in your Sendbird application before being connected.
In this guide, we will create a user on the Sendbird dashboard first.
-
Go to the Users menu on the left-hand side of the dashboard and click Create user+.
-
Enter the User ID and Nickname. It is recommended that you check the box next to Issue access token for user authentication. Then, click Create.
Note: Sendbird supports user authentication through access token for stronger security. However, on the dashboard, you can also configure the token permission in Settings > Application > Security > Access token permission to allow users without a token to access our functionalities. To learn more, see Authentication.
- Copy and store the user ID. You will use it to connect to the Sendbird server.
Get started
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
To get started, open Xcode
and create a new project. Sendbird UIKit supports swift
.
Step 2 Install UIKit
You can install UIKit for iOS through either Swift Packages, CocoaPods, or Carthage.
Swift Packages
-
In Xcode, select File > Add Packages.
-
Add
SendbirdUIKit
into yourPackage Repository
as below:
- Swift Package Manager automatically sets the dependency rule to "Up To Next Major" and installs the latest version. Adjust the dependency rule and version according to your needs. You can check out the latest UIKit version on UIKit releases.
Note: A build error may occur while 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 toPackages
, and selectReset Package Caches
. This deletes all local package data and redownloads each package from its online source.
CocoaPods
- Add
SendBirdUIKit
into yourPodfile
in Xcode as below:
- Install the
SendBirdUIKit
framework throughCocoaPods
.
- Update the
SendBirdUIKit
framework throughCocoaPods
.
Carthage
- Add
SendbirdUIKit
andSendbirdChatSDK
into yourCartfile
as below:
- Install the
SendbirdUIKit
framework throughCarthage
.
Note: Building or creating the
SendbirdUIKit
framework withCarthage
can only be done using the latestSwift
. If yourSwift
is not the most recent version, the framework should be copied into your project manually.
- Go to your Xcode project target's General settings tab in the
Frameworks and Libraries
section. Then drag and dropSendbirdUIKit.xcframework
andSendbirdChatSDK.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
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 tofalse
withinInitParams
of theinitParamsBuilder
block.
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 theexecuteHandler
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.
Step 4 Set current user and connect to Sendbird server
Before initiating Sendbird UIKit, configure the currentUser
information in the SBUGlobals
. This information is essential for the kit to perform various tasks. Failing to set currentUser
in advance can result in operational limitations within the UIKit.
Specifically, the userID
field shown below must be defined as in the code below, which is the unique ID set to the user you've created on the dashboard. Other fields such as nickname
and profileURL
are optional, and if not specified, they'll be filled with default values.
Then, call SendbirdUI.connect(completionHandler:)
to connect the user to Sendbird server. The user set as SBUGlobals.currentUser
will be connected to Senbird server. If you haven't created a user yet, specify a unique USER_ID
in the code snippet provided. This action will automatically generate a new user when you connect to the Sendbird server.
Note: Sendbird supports user authentication via access tokens, but defaults to allowing access without a token for ease of initial use. For enhanced security, we recommend adjusting the access settings of new users under Settings > Application > Security > Access token permission on the dashboard. To learn about authentication, see the Authentication guide.
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.
Step 5 Display channel list
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.
Note: If you are already using a navigation controller, you can use the
pushViewController
function.
Step 6 Send your first message
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
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
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.
Document attachment permission (optional)
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
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
Component | Description |
---|---|
SBUGroupChannelListViewController | A |
SBUGroupChannelViewController | A |
SBUGroupChannelSettingsViewController | A |
SBUCreateChannelViewController | A |
SBUInviteUserViewController | A |
SBURegisterOperatorViewController | A |
SBUUserListViewController | A |
SBUMessageSearchViewController | A |
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. |