Quickstart

Channel.io iOS SDK is a plugin that provides you install real-time customer chat on applications written in Swift/Objc.
If you want to install it in a web view or mobile web, See the JavaScript SDK Installation Guide.

Prerequisite

The minimum conditions of SDK are the following:

  • Paid Channel.io service plan.
  • iOS deployment target ≥ 11.0
  • Swift 5.0 and later
  • ChannelIO SDK 9.0.0 and later

Installation

CocoaPods Carthage compatible Swift Package Manager compatible

You can install ChannelIO SDK through Swift Package Manager, CocoaPods, and Carthage.

Swift Package Manager

You can use Swift Package Manager to install ChannelIO SDK. Xcode 11 version or later is required.

  1. Go to Xcode Navigator, and select the project to install the package.
    Select Swift Package tab, and click the + button.
1126
  1. Add the ChannelIO Swift package repository URL. After setting the version, click the Add Package button.
https://github.com/channel-io/channel-talk-ios-framework
1126

CocoaPods

You can use CocoaPods to install ChannelIO SDK. CocoaPods 1.10.0 version or later is required.

  1. Add ChannelIOSDK to the 'Podfile' of the project as below.
target YOUR_PROJECT_TARGET do
  pod 'ChannelIOSDK', podspec: 'https://mobile-static.channel.io/ios/latest/xcframework.podspec'
end

If you need to install a specific package version, change the 'latest' in the middle of the script to a particular version. For example:

target YOUR_PROJECT_TARGET do
  pod 'ChannelIOSDK', podspec: 'https://mobile-static.channel.io/ios/10.0.7/xcframework.podspec'end
  1. In the directory where 'Podfile' is located, run the pod install command to install the package.
  2. open Project_Name.xcworkspace

Carthage

You can use Carthage to install ChannelIO SDK.

  1. Add ChannelIOSDK to the Cartfile of the project as below.
binary "https://mobile-static.channel.io/ios/latest/channeliosdk-ios.json"

If you need to install a specific package version, change the script as below.

// Compatible version
binary "https://mobile-static.channel.io/ios/latest/channeliosdk-ios.json" ~> 8.0.0
// Specific version
binary "https://mobile-static.channel.io/ios/latest/channeliosdk-ios.json" == 8.0.0
  1. In the directory where Cartfile is located, run the carthage update command to install the package. For example:
carthage update --platform iOS --use-xcframeworks
  1. The ChannelIO package is built inside the PROJECT_DIR/Carthage/build directory. Drag this package to Xcode to add it.

After installation

The following permissions are required to use the SDK. Add the following key value and description to the project's info.plist.

KeyValue
Privacy - Camera Usage DescriptionAccessing to the camera in order to provide a better user experience
Privacy - Photo Library Additions Usage DescriptionAccessing to photo library in order to save photos
Privacy - Microphone Usage DescriptionAccessing to microphone to record voice for video

If you use an SDK version lower than 10.0.7, or if your app's min deployment target version is lower than iOS 13.0, add the permission below additionally.

KeyValue
Privacy - Photo Library Usage DescriptionAccessing to photo library in order to provide a better user experience

Using Channel.io

Step 1. Add Framework

Import the SDK where you need to use it.

import ChannelIOFront
import ChannelIO
#import <ChannelIOFront/ChannelIOFront-swift.h>
@import ChannelIO;

Step 2. initialize

You need to initialize for using SDK before using it. add the initialize method below in the application(_:didFinishLaunchingWithOptions) in the AppDelegate.swift.

// AppDelegate.swift

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    ... 
    ChannelIO.initialize(application)
    ... 
    return true
 }
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
  [ChannelIO initialize:application];
  return YES;
}

If you manage app’s window on SceneDelegate.swift, add the initializeWindow method below in the scene(_:willConnectTo:options:).

// SceneDelegate.swift

// add: 
var channelWindow: UIWindow?

func scene(_ scene: UIScene, willConnectTo session: UISceneSession, options connectionOptions: UIScene.ConnectionOptions) {
  guard let windowScene = (scene as? UIWindowScene) else { return } 
  channelWindow = ChannelIO.initializeWindow(with: windowScene)
}
//  SceneDelegate.m

@interface SceneDelegate ()
@property (strong, nonatomic) UIWindow * channelWindow;
@end

@implementation SceneDelegate


- (void)scene:(UIScene *)scene willConnectToSession:(UISceneSession *)session options:(UISceneConnectionOptions *)connectionOptions {
  _channelWindow = [ChannelIO initializeWindowWith:(UIWindowScene *)scene];
}
@end

Step 3. Boot

Boot is the preparation process for using the SDK.

You may need your channel’s plugin key. See how to get a plugin key.
There are two types of Boot: Boot as an anonymous user or Boot as a member user 

For a detailed description of the user, see Member User.

3-1. Boot as an anonymous user

An anonymous user is a user without a memberId. Below is an example of Boot with an anonymous user and receiving the result value of Boot.

let bootConfig = BootConfig(pluginKey: YOUR_PLUGIN_KEY)

ChannelIO.boot(with: bootConfig) { (bootStatus, user) in
  if completion == .success, let user = user {
      // success
  } else {
     // show failed reason from bootStatus
  }
}
BootConfig *bootConfig = [[BootConfig alloc] init];
[bootConfig setPluginKey:YOUR_PLUGIN_KEY];
[ChannelIO bootWith:bootConfig completion:^(BootStatus status, User *user) {
  if (status == BootStatusSuccess && user != nil) {
    // success
  } else {
    // show failed reason from bootStatus
  }
}];

Boot's method parameter, BootConfig, provides several boot options, including pluginKey.

3-2. Boot as a member user

A member user is a user with a memberId. If the user can be identified by itself, such as when signed in to your service, You can boot as a member user by giving memberId. The Channel distinguishes a user by the memberId field.

Additional information can be injected into users using the Profile .

❗️

Use member hash to protect sensitive information of your users

If you set the memberId using predictable values such as user ID or email, an unauthorized third party might acquire your user’s memberId. The unauthorized access might allow the malicious third party to gain your user’s sensitive information, including mobile number and chat logs which can lead to a security breach. Enable member hash for your channel to improve the security level.

Below is an example of Boot a member user with a specific MEMBER_ID.

let profile = Profile()
profile.set(name: "Jason")

let profile = Profile()
  .set(name: USER_NAME)
  .set(propertyKey: KEY, value: VALUE)

let buttonOption = ChannelButtonOption(
  position: .left,
  xMargin: 16,
  yMargin: 23
)

let bootConfig = BootConfig(
  pluginKey: PLUGIN_KEY,
  memberId: MEMBER_ID,
  memberHash: MEMBER_HASH,
  profile: profile,
  channelButtonOption: buttonOption,
  hidePopup: false,
  trackDefaultEvent: true,
  language: .english
)

ChannelIO.boot(with: bootConfig)
Profile *profile = [[Profile alloc] init];
[profile setWithName:USER_NAME];
[profile setWithPropertyKey:KEY value:VALUE];

ChannelButtonOption *buttonOption = [[ChannelButtonOption alloc]
                                     initWithPosition:ChannelButtonPositionLeft
                                     xMargin:16
                                     yMargin:23
                                     ];

BootConfig *bootConfig = [[BootConfig alloc] init];
[bootConfig setWithMemberId:MEMBER_ID];
[bootConfig setMemberHash:MEMBER_HASH];
[bootConfig setProfile:profile];
[bootConfig setLanguage:LanguageOptionEnglish];
[bootConfig setWithUnsubscribed:YES];
[bootConfig setTrackDefaultEvent:YES];
[bootConfig setHidePopup:true];
[bootConfig setChannelButtonOption:buttonOption];

[ChannelIO bootWith:bootConfig completion:^(BootStatus status, User * user) { }];

📘

The information of the same person can be unified

When booting as a member user from an anonymous user state, users can be unified into one if Channel finds a strong evidence that the two users are the same person. See unifying customer information for details.

Awaiting a boot result

Boot requires a network connection which might yield some random delay. BootCallback can be used if there is a task to be processed after boot is complete or fails.

ChannelIO.boot(with: bootConfig) { (bootStatus, user) in
    if completion == .success, let user = user {
        // success
    } else {
        // show failed reason from bootStatus
    }
}
BootConfig *bootConfig = [[BootConfig alloc] init];
[bootConfig setPluginKey:YOUR_PLUGIN_KEY];
[ChannelIO bootWith:bootConfig completion:^(BootStatus status, User *user) {
  if (status == BootStatusSuccess && user != nil) {
    // success
  } else {
    // show failed reason from bootStatus
  }
}];

See BootStatus for the full list of boot results.

Showing the Channel button

SDK provides a default Channel button to launch messengers. You can call showChannelButton and hideChannelButton to show or hide Channel buttons.

ChannelIO.showChannelButton()
ChannelIO.hideChannelButton()
[ChannelIO showChannelButton];
[ChannelIO hideChannelButton];

If you want to change the button’s appearance, see how to customize the Channel button.

Shutdown

Terminates all features of the SDK. If you want to use the feature of SDK again, you may need to Boot again.

ChannelIO.shutdown()
[ChannelIO shutdown];

What’s Next

Not liking our launcher button? Check out Customization