iOS
Quick Start

Quick Start

The SendBird SDKs help you to implement real-time chat to any types of your client apps with speed and efficiency. Our iOS SDK provides you with various methods to initialize, configure, and build the chat from the client side - no server side implementation is required because our reliable infra management service is delivered with the SDK. This page presents a brief overview of the SDK’s structure and abilities, then lets you go through the preliminary steps of implementing the SDK in your own app.


First, try out the sample app!

Our sample app is a basic representation of the abilites of the SDK. You can download the app from our repository on GitHub and build it in your workplace. The app gives you a simple picture of what you can build with the SDK, although without the many more capabilities of the actual SDK.

Download Sample App

In fact, a simple way to build your messaging app is to do so on top of our sample app. Note that you should change the application ID of the sample app to your own in this case - see the Create a new SendBird application from your dashboard section for reference.


How SendBird works with messaging

To build your own messaging with the iOS SDK is simple: a user connects, sees a list of channels, selects or creates a channel, then sends a message to the channel, and receives messages from all other users within the channel.

We provide two types: an open channel and a group channel. An open channel is a public channel which anyone can easily participate and chat with others. A group channel is basically a private channel which a user can join as a new member through an invitation. Compared with an open channel, it has distinctive abilities of various properties and features. There are a variety of the subtypes of a group channel such as a public group channel working like an open channel.

All messages within your SendBird application are automatically delivered to channel delegates which are registered to your app. As long as the SendBird instance in your user's client app is connected to our server, the delegates receive callbacks from the server through their didReceiveMessage:, userDidJoin: methods, and so on. These callbacks contain message or channel objects, with the latest information in case of an incoming message or other events related to the objects.


Install and configure iOS SDK

Step 1: Create a new SendBird application from your dashboard

A SendBird application comprises everything that goes in a chatting service such as users, messages, and channels. To create a SendBird application, do the following:

  1. In the SendBird Dashboard, type your email and password to create a new account. You can also sign in or sign up with Google or GitHub accounts.
  2. In the Setup wizard that appears, specify information of your organization to manage SendBird applications.
  3. In your dashboard home that appears after completing the setup, click Create App at the top-right corner for a new application (you can also create via the Platform API).

You can implement only one SendBird application per app for your service, regardless of the platforms. All users within your SendBird application can communicate with each other, across all platforms. This means that your users using iOS, Android, web, .NET, and Unity client apps, can all chat with one another without any further setup. Note that all data are limited to the scope of a single application, and users in different SendBird applications can't talk to each other.

Step 2: Install the SDK

Installing the SDK is simple if you’re familiar with using external libraries or SDK’s in your projects. You can install the iOS SDK using CocoaPods or Carthage like the following.

With CocoaPods

If you've never used CocoaPods for a Xcode project, open a terminal window, move to your project directory, and then create a Podfile by running the following command.

Light Color Skin
Copy
$ pod init

Add the following lines to the Podfile.

Light Color Skin
Copy
platform :ios, '8.0'

target 'YourProject' do
  use_frameworks!

  pod 'SendBirdSDK'
end

And then install the SendBird framework through CocoaPods.

Light Color Skin
Copy
$ pod install

Now you can run your project with the SendBird Framework by opening *YOUR_PROJECT*.xcworkspace. If you don't want to use CocoaPods, check out the manual installation guide.

With Carthage

  1. Add github "sendbird/sendbird-ios-framework" to your Cartfile.
  2. Run carthage update.
  3. Go to your Xcode project's General settings. Open the <YOUR_XCODE_PROJECT_DIRECTORY>/Carthage/Build/iOS in the finder and drag SendBirdSDK.framework to the Embedded Binaries section in Xcode. Make sure the Copy items if needed option is selected and click Finish.

Turn on ARC

To use the SendBird framework, you should turn on the ARC (Automatic Reference Counting). To do that, go to your project's Build Settings, and then set the value of Objective-C Automatic Reference Counting to Yes (in Swift, Yes by default).

If you don't want to turn on ARC in a project-wide scope, then navigate to the Build Phases - Compile Sources and add -fobjc-arc to the Compiler Flags in the source file that the SendBird framework uses. This means that ARC is turned on only that file.

Step 3: Use the SDK in Objective-C and Swift

You can use all classes and methods just with the following one import statement, without a bridging header file, in both Objective-C and Swift.

Objective-C
Swift
Light Color Skin
Copy
#import <SendBirdSDK/SendBirdSDK.h>
Light Color Skin
Copy
import SendBirdSDK

The Interacting with Objective-C APIs in Swift helps you with understanding how to use the iOS SDK in Swift syntax.


Send your first message

The iOS SDK simplifies messaging into an effortless and straightforward process. To send your first message, do the following steps:

Note: The methods in the following steps are all asynchronous, excluding the initWithApplicationId: method of a SBDMain instance. This means that when you use the asynchronous methods, make sure that they receive a success callback from the SendBird server through their completion handlers to proceed to the next step. A good way to do this is the nesting of methods - see the example in the Step 4: Enter the channel which shows how you can nest the enterChannelWithCompletionHandler: in the getChannelWithUrl:completionHandler: method.

Step 1: Initialize the SDK

To allow the iOS SDK to respond to the connection and state changes in your iOS client app, you first initialzize the SDK in the app. Pass in the App ID of the SendBird application you created earlier in the dashboard for the initialization.

Note: The initWithApplicationId: method of a SBDMain instance must be called once across your iOS client app. We recommend that you initialize the iOS SDK in the application:didFinishLaunchingWithOptions: method of the AppDelegate instance.

Objective-C
Swift
Light Color Skin
Copy
[SBDMain initWithApplicationId:APP_ID];
Light Color Skin
Copy
SBDMain.initWithApplicationId(APP_ID)

Step 2: Connect to SendBird server

Connect a user to SendBird server using their unique user ID. Any untaken user ID is automatically registered as a new user to the SendBird system before connected, while an existing ID makes the user log in directly.

Note: Authenticating with an access token is discussed in the Authentication section.

Objective-C
Swift
Light Color Skin
Copy
[SBDMain connectWithUserId:USER_ID completionHandler:^(SBDUser * _Nullable user, SBDError * _Nullable error) {
    if (error != nil) { // Error.
        return;
    }
}];
Light Color Skin
Copy
SBDMain.connect(withUserId: USER_ID) { (user, error) in
    guard error == nil else {   // Error. 
        return
    }
}

Step 3: Create a new open channel

Create an open channel. Once created, all users in your SendBird application can easily participate the channel to converse.

Note: In a similar way, you can create a group channel with inviting any other users as new members to the channel.

Objective-C
Swift
Light Color Skin
Copy
[SBDOpenChannel createChannelWithCompletionHandler:^(SBDOpenChannel * _Nullable openChannel, SBDError * _Nullable error) {
    if (error != nil) { // Error.
        return;
    }
}];
Light Color Skin
Copy
SBDOpenChannel.createChannel { (openChannel, error) in
    guard error == nil else {   // Error. 
        return
    }
}

Step 4: Enter the channel

Enter the channel to view and send messages.

Objective-C
Swift
Light Color Skin
Copy
[SBDOpenChannel getChannelWithUrl:CHANNEL_URL completionHandler:^(SBDOpenChannel * _Nullable openChannel, SBDError * _Nullable error) {
    if (error != nil) { // Error.
        return;
    }

    [openChannel enterChannelWithCompletionHandler:^(SBDError * _Nullable error) {
        if (error != nil) { // Error.
            return;
        }
    }];
}];
Light Color Skin
Copy
SBDOpenChannel.getWithUrl("CHANNEL_URL") { (openChannel, error) in
    guard error == nil else {   // Error. 
        return
    }

    openChannel?.enter(completionHandler: { (error) in
        guard error == nil else {   // Error.
            return
        }
    })
}

Step 5: Send a message to the channel

And finally, send a message to the channel! There are three types: a user message is a plain text, a file message is a binary file, such as an image or PDF, and an admin message is a plain text sent through the dashboard or Platform API for special purpose.

Objective-C
Swift
Light Color Skin
Copy
[openChannel sendUserMessage:MESSAGE data:DATA customType:CUSTOM_TYPE completionHandler:^(SBDUserMessage * _Nullable userMessage, SBDError * _Nullable error) {
    if (error != nil) { // Error. 
        return;
    }
}];
Light Color Skin
Copy
openChannel?.sendUserMessage(MESSAGE, data: DATA, customType: CUSTOM_TYPE, completionHandler: { (message, error) in
    guard error == nil else {   // Error. 
        return
    }
})