README.md

Sendbird UIKit for iOS

We are introducing a new version of the Sendbird UIKit. Version 3 features a new modular architecture with more granular components that give you enhanced flexibility to customize your web and mobile apps. Check out our migration guides and download our samples

With the official release of the v3 version, the name of the master branch was changed to the main branch, and the main branch was changed to the contents of the v3. If you have to keep using v2, please use the main-v2 branch.

• v3: main
• v2: main-v2

Table of contents

1. Introduction
2. Before getting started
3. Getting started
4. Implementation guide
5. UIKit at a glance

Introduction

Sendbird UIKit for iOS is a development kit with an user interface that enables an easy and fast integration of standard chat features into new or existing client apps. From the overall theme to individual styles such as colors and fonts, components can be fully customized to create an in-app chat experience unique to your brand identity.

Note: Currently, UIKit for iOS now supports both group channels and open channels.

This repository houses the UIKit source code and UIKit sample in addition to a UIKit Framework.

• Sources is where you can find the open source code. Check out UIKit Open Source Guidelines for more information regarding our stance on open source.
• Sample is a chat app which contains custom sample code for various key features written in Swift.

Benefits

• Easy installation
• Fully-featured chat with a minimal amount of code
• Customizable components, events, and views
• Customizable user list to enable chat among specified users

More about Sendbird UIKit for iOS

Find out more about Sendbird UIKit for iOS on UIKit for iOS doc. If you have any comments or questions regarding bugs and feature requests, visit Sendbird community.

Before getting started

This section shows the prerequisites you need to check to use Sendbird UIKit for iOS.

Requirements

The minimum requirements for Sendbird UIKit for iOS are:

• iOS 12+
• Swift 5.0+
• Sendbird Chat SDK for iOS 4.23.1+

Getting started

This section gives you information you need to get started with Sendbird UIKit for iOS.

Try the sample app

Our sample app has all the core features of Sendbird UIKit for iOS. Download the app from our GitHub repository to get an idea of what you can build with the actual UIKit before building your own project.

• Samples

Create a project

You can get started by creating a project. Sendbird UIKit support Swift, so you can create and work on a project in the language you want to develop with.

Install UIKit for iOS

UIKit for iOS can be installed through either CocoaPods, Carthage or Swift Package Manager:

Note: Sendbird UIKit for iOS is Sendbird Chat SDK-dependent.

- Swift Packages

1. Go to your Swift Package Manager's File tab and select Swift Packages. Then choose Add package dependency....

2. Add SendbirdUIKit into your Package Repository as below:

https://github.com/sendbird/sendbird-uikit-ios-spm.git

3. 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.

- CocoaPods

1. Add SendBirdUIKit into your Podfile in Xcode as below:

platform :ios, '12.0'
use_frameworks!

target YOUR_PROJECT_TARGET do
    pod 'SendBirdUIKit'
end

2. Install the SendbirdUIKit framework through CocoaPods.

$ pod install

3. Update the SendbirdUIKit framework through CocoaPods.

$ pod update

Note: Cocoapod uses the name of SendBirdUIKit, not SendbirdUIKit.

- Carthage

1. Add SendbirdUIKit and SendBirdSDK into your Cartfile as below:

github "sendbird/sendbird-uikit-ios"
github "sendbird/sendbird-chat-sdk-ios"

2. 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.

3. Go to your Xcode project target's General settings tab in the Frameworks and Libraries section. Then drag and drop SendbirdUIKit.framework 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.

Get attachment permission

Sendbird UIKit offers features to attach or save files such as photos, videos, and documents. To use those features, you need to request permission from end users.

- Media attachment permission

Applications must acquire permission from end users to use their photo assets or to save assets into their library. Once the permission is granted, users can send image or video messages and save 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>
...

(Optional) Document attachment permission

If you want to attach files from iCloud, you must activate the iCloud feature. Once it is activated, users can also send a message with files from iCloud.

Go to your Xcode project's Signing & Capabilities tab. Then, click + Capability button and select iCloud. Check iCloud Documents.

Implementation guide

Initialize with APP_ID

In order to use the Chat SDK's features, you must initialize the SendbirdUIKit instance with APP_ID. This step also initializes the Chat SDK for iOS.

Initialize the SendbirdUIKit instance through AppDelegate as below:

// AppDelegate.swift

import SendbirdUIKit

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    
    let APP_ID = "2D7B4CDB-932F-4082-9B09-A1153792DC8D"    // The ID of the Sendbird application which UIKit sample app uses.
    SendbirdUI.initialize(applicationId: APP_ID) {
        // Do something to display the start of the SendbirdUIKit initialization.
    } migrationHandler: {
        // Do something to display the progress of the DB migration.
    } completionHandler: { error in
        // Do something to display the completion of the SendbirdChat initialization.
    }
    
}

Note: In the above, you should specify the ID of your Sendbird application in place of the APP_ID.

Set the current user

User information must be set as currentUser in the SBUGlobal prior to launching Sendbird UIKit. This information will be used within the kit for various tasks. The userId field must be specified whereas other fields such as nickname and profileURL are optional and filled with default values if not specified.

Set the currentUser for UIKit through the AppDelegate as below:

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

// AppDelegate.swift

import SendbirdUIKit

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    
    // 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})
    
}

Note: If the currentUser is not set in advance, there will be restrictions to your usage of UIKit.

Channel list

UIKit allows you to create a channel specifically for 1-on-1 chat and to list 1-on-1 chat channels so that you can easily view and manage them. With the SBUChannelListViewController class, you can provide end users a complete chat service featuring a List channels.

Implement the code below wherever you want to start UIKit.

import SendbirdUIKit

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

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

Note: At this point, you can confirm if the service is working by running your client app.

Channel

With the SBUGroupChannelViewController class, you can build a channel-based chat service instead of a channel list-based one.

Note: You should have either a Channel object or a ChannelURL in order to run a channel-based chat service.

Use the following code to implement the chat service.

import SendbirdUIKit

let channelVC = SBUGroupChannelViewController(channelURL: {CHANNEL_URL})
let naviVC = UINavigationController(rootViewController: channelVC)
present(naviVC, animated: true)

Distribution setting

UIKit is distributed in the form of a fat binary, which contains information on both Simulator and Device architectures. Add the script below if you are planning to distribute your application in the App Store and wish to remove unnecessary architectures in the application's build phase.

Go to your Xcode project target's Build Phases tab. Then, click + and select New Run Script Phase. Append this script.

APP_PATH="${TARGET_BUILD_DIR}/${WRAPPER_NAME}"

# This script loops through the frameworks embedded in the application and
# removes unused architectures.
find "$APP_PATH" -name '*.framework' -type d | while read -r FRAMEWORK
do
    FRAMEWORK_EXECUTABLE_NAME=$(defaults read "$FRAMEWORK/Info.plist" CFBundleExecutable)
    FRAMEWORK_EXECUTABLE_PATH="$FRAMEWORK/$FRAMEWORK_EXECUTABLE_NAME"
    echo "Executable is $FRAMEWORK_EXECUTABLE_PATH"
    
    EXTRACTED_ARCHS=()
    
    for ARCH in $ARCHS
    do
        echo "Extracting $ARCH from $FRAMEWORK_EXECUTABLE_NAME"
        lipo -extract "$ARCH" "$FRAMEWORK_EXECUTABLE_PATH" -o "$FRAMEWORK_EXECUTABLE_PATH-$ARCH"
        EXTRACTED_ARCHS+=("$FRAMEWORK_EXECUTABLE_PATH-$ARCH")
    done
    
    echo "Merging extracted architectures: ${ARCHS}"
    lipo -o "$FRAMEWORK_EXECUTABLE_PATH-merged" -create "${EXTRACTED_ARCHS[@]}"
    rm "${EXTRACTED_ARCHS[@]}"
    
    echo "Replacing original executable with thinned version"
    rm "$FRAMEWORK_EXECUTABLE_PATH"
    mv "$FRAMEWORK_EXECUTABLE_PATH-merged" "$FRAMEWORK_EXECUTABLE_PATH"
done

UIKit at a glance

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:

Component	Description
SBUGroupChannelListViewController	A ViewController that manages a group channel list.
SBUGroupChannelViewController	A ViewController that manages a 1-on-n group chat channel.
SBUOpenChannelViewController	A ViewController that manages a open chat channel.
SBUCreateChannelViewController	A ViewController that creates a channel.
SBUInviteUserViewController	A ViewController that invites a user to a channel.
SBURegisterOperatorViewController	A ViewController that registers as operator in a channel.
SBUUserListViewController	A ViewController that shows a list of members or participants in a channel.
SBUGroupChannelSettingsViewController	A ViewController that configures a group channel.
SBUOpenChannelSettingsViewController	A ViewController that configures a open channel.
SBUModerationsViewController	A ViewController that moderates a channel.
SBUMessageSearchViewController	A ViewController that searches messages 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.
SBUGlobalSet	A class that contains static attributes required when using Sendbird UIKit.