Quickstart

The Channel Talk iOS SDK is a plugin facilitating the installation of real-time customer chat in applications written in Swift/Objc. If you're looking to install it into a web view or mobile web, please refer to the JavaScript SDK Installation Guide.

Prerequisite

The minimum conditions of SDK are the following:

  • A Paid Channel Talk service plan.
  • iOS deployment target ≥ 12.0
  • Swift 5.0 and later
  • ChannelIO SDK 10.0.0 and later

Installation

CocoaPods Carthage compatible Swift Package Manager compatible Versions

You have the option to install the ChannelIO SDK using Swift Package Manager, CocoaPods, or Carthage.

📘

About Privacy manifest

The iOS SDK version 11.5.0 and higher includes a Privacy manifest (PrivacyInfo.xcprivacy). Use this version or higher if you require a Privacy manifest file.

Swift Package Manager

You can use Swift Package Manager to install ChannelIO SDK. make sure you have Xcode 11 or a more recent version.

  1. Navigate to the Xcode Navigator, select the project where you want to install the package, and then choose the Swift Package tab. Finally, click the + button.

  1. Add the ChannelIO Swift package repository URL. Once you've set the version, click the Add Package button.
https://github.com/channel-io/channel-talk-ios-framework

CocoaPods

You can utilize CocoaPods to install the ChannelIO SDK. Please ensure that you have CocoaPods version 1.10.0 or later.

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

If you require a specific package version, modify the 'latest' in the script to the desired version. For example:

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

Carthage

You can utilize Carthage to install ChannelIO SDK.

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

If you need to install a specific package version, modify the script as follows:

// 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. Run the carthage update command in the directory where the Cartfile is located to install the package. For instance:
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

Info.plist

To utilize the SDK, certain permissions are necessary. Please incorporate the corresponding key-value pairs and descriptions into your 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 your SDK version is below 10.0.7, or if the minimum deployment target version of your app is less than iOS 13.0, you will need to add the following permission additionally.

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

Using Channel Talk

Step 1. Add Framework

Import the SDK where you need to use it.

import ChannelIOFront
#import <ChannelIOFront/ChannelIOFront-swift.h>

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

Bootis the preliminary process for utilizing the SDK.

You will require your channel's plugin key. Refer to 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 comprehensive description of the user, refer to Member User.

3-1. Boot as an anonymous user

An anonymous user refers to a user without a memberId. Here's an example of booting with an anonymous user and receiving the result value of the boot process.

let bootConfig = BootConfig(pluginKey: YOUR_PLUGIN_KEY)

ChannelIO.boot(with: bootConfig) { (bootStatus, user) in
  if bootStatus == .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 on its own, such as when signed into your service, you can initiate a boot process as a member user by providing a 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

you set the memberId using predictable values such as user ID or email, an unauthorized third party might obtain your user’s memberId. This unauthorized access might allow the malicious third party to access your user’s sensitive information, including mobile numbers and chat logs, leading to a security breach. Enable the member hash for your channel to enhance 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 may introduce some random delays. BootCallback can be used if there is a task to be processed after the boot is completed or fails.

ChannelIO.boot(with: bootConfig) { (bootStatus, user) in
	if bootStatus == .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 appearance of the button, refer to 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