English한국어

시작하기

ChannelIO iOS SDK(이하 SDK)는 Swift / Objc로 작성된 애플리케이션에 실시간 상담 채팅 모듈을 쉽게 설치할 수 있는 플러그인입니다. 웹뷰 안이나 모바일 웹에 설치하고자 하는 경우는 JavaScript SDK 설치 가이드를 참고합니다.

시작하기 전에

SDK를 사용하기 위한 최소 요구사항은 다음과 같습니다.

  • 채널톡 유료 플랜
    • 구독 및 결제 페이지에서 현재 플랜을 확인할 수 있습니다.
  • iOS deployment target 12.0 이상
  • Swift 5.0 이상
  • ChannelIO SDK 10.0.0 이상

설치하기

CocoaPods Carthage compatible Swift Package Manager compatible Version

Swift Package Manager, CocoaPods, Carthage 를 통해 ChannelIO를 설치할 수 있습니다.

📘

Privacy manifest에 대하여

iOS SDK는 v11.5.0 버전 이상부터 PrivacyInfo.xcprivacy를 SDK 내에 포함하고 있습니다. Privacy manifest 파일이 필요한 경우 해당 버전 이상을 사용해야 합니다.

Swift Package Manager로 설치하기

Swift Package Manager를 이용하여 SDK를 설치할 수 있습니다. Xcode 11 버전 이상이 필요합니다.

  1. Xcode의 네비게이터로 이동하여, 프로젝트 중 패키지를 설치할 프로젝트를 선택합니다.
    Swift Package 탭으로 이동하여, + 버튼을 클릭합니다.

  1. 아래의 ChannelIO 의 패키지 주소를 입력합니다. 버전을 설정한 뒤, Add Package 버튼을 클릭합니다.
https://github.com/channel-io/channel-talk-ios-framework

CocoaPods로 설치하기

CocoaPods를 이용하여 ChannelIO iOS SDK를 설치할 수 있습니다. CocoaPods 1.10.0 버전 이상이 필요합니다.

  1. 프로젝트의 Podfile에 아래와 같이 ChannelIOSDK를 추가합니다.
pod 'ChannelIOSDK', podspec: 'https://mobile-static.channel.io/ios/latest/xcframework.podspec'

특정 패키지 버전을 설치하는 경우는 스크립트 중간의 latest를 특정 버전으로 변경합니다. 예시는 다음과 같습니다.

pod 'ChannelIOSDK', podspec: 'https://mobile-static.channel.io/ios/10.0.7/xcframework.podspec'
  1. Podfile 이 위치한 디렉토리에서 pod install 커맨드를 실행하여 패키지를 설치합니다.
  2. Project_Name.xcworkspace을 열어 사용합니다.

Carthage로 설치하기

Carthage를 이용하여 ChannelIO iOS SDK를 설치할 수 있습니다.

  1. 프로젝트의 Cartfile에 아래와 같이 ChannelIOSDK를 추가합니다.
binary "https://mobile-static.channel.io/ios/latest/channeliosdk-ios.json"
  1. Cartfile 이 위치한 곳에서 아래 커맨드를 이용하여 패키지를 설치합니다.
carthage update --platform iOS --use-xcframeworks
  1. PROJECT_DIR/Carthage/build 폴더 안에 다운로드된 패키지를 Xcode로 드래그하여 추가합니다. 아래 사진을 참고합니다.

설치하고 나서

SDK를 사용하기 위해 다음과 같은 권한이 필요합니다. info.plist 에 아래 권한에 따른 설명을 추가합니다.

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

SDK 버전이 10.0.7 미만 또는 iOS 최소 버전이 13 미만일 경우 아래의 권한을 추가합니다.

KeyValue
Privacy - Photo Library Usage DescriptionAccessing to photo library in order to save photos

채널톡 사용하기

Step 1. Framework 추가하기

채널톡 사용이 필요한 곳에서 SDK를 import 합니다.

import ChannelIOFront

#import <ChannelIOFront/ChannelIOFront-swift.h>

Step 2. 초기화

SDK 사용을 위해 초기화가 필요합니다. AppDelegate.swift의 application(_:didFinishLaunchingWithOptions) 메소드에 initialize를 선언합니다.

// 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;
}

만약 SceneDelegate.swift 에서 window를 관리하는 경우, scene(_:willConnectTo:options:) 메소드 안에 아래 ChannelIO.initializeWindow 메소드를 추가합니다.

// 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 는 SDK를 사용하기 위해 필요한 정보를 로드하는 과정입니다. 부트를 성공한 이후에는 SDK의 기능을 사용할 준비를 마칩니다.

부트에는 플러그인 키가 필요합니다. 플러그인 키는 채널톡 웹 데스크에서 플러그인 키를 얻어내는 방법을 참고하여 준비합니다.
Boot 는 두가지 종류로, 익명의 유저로 부트하거나, 멤버 유저로 부트할 수 있습니다.
유저에 대한 자세한 설명은 멤버 유저를 참고합니다.

익명의 유저로 부트하기

익명의 유저란, memberId가 부여되지 않은 유저입니다. 아래는 익명의 유저로 Boot 한 뒤, Boot의 결과값을 받는 예시입니다.

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 의 메소드 파라미터인 BootConfig 에는 pluginKey를 포함하여 몇가지 부트 옵션을 제공합니다.

멤버 유저로 부트하기

멤버 유저란, memberId 가 부여된 유저입니다. 만약 로그인 되어있는 상태와 같이 자체적으로 유저를 구분할 수 있는 경우에는 memberId를 부여하여 멤버 유저로 부트합니다. 채널톡은 memberId를 이용하여 각 유저를 구분합니다.

Profile 모델을 이용하여, 유저에게 추가적인 정보를 주입할 수 있습니다.

❗️

보안을 위해서 멤버 해시 사용을 권장합니다

만약 아이디, 이메일과 같은 예측 가능한 값으로 memberId를 설정할 경우 인증되지 않은 제3자가 memberId를 유추할 수 있습니다. 이 경우 제3자가 고객의 개인 정보나 채팅 내역을 탈취할 수 있는 등 보안 위협에 노출될 수 있습니다. 보안을 위해서 멤버 해시를 설정하는 것을 권장합니다.

아래는, 특정 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) { }];

📘

동일한 사람이라고 판단되는 유저는 합쳐질 수 있습니다

익명 유저 상태에서 멤버 유저로 부트를 하는 경우 채널톡이 같은 유저라고 판단할 수 있는 합리적인 근거가 있다면 채팅 목록과 같은 유저 정보를 합칠 수 있습니다. 더 자세한 내용은 고객 정보 통합하기를 참고합니다.

부트 결과 전달 받기

부트 과정에는 인터넷 연결이 필요하므로, 약간의 시간이 소요될 수 있습니다. 만약 채널톡 부트가 완료된 후에 특정한 작업이 필요하거나, 부트가 실패한 상황에 처리해야 하는 작업이 있다면 BootCallback 을 활용할 수 있습니다.

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
  }
}];

부트 상태에 관한 정보는 BootStatus 를 참고합니다.

채널 버튼 표시하기

SDK는 사용자가 메신저를 띄울 수 있도록 채널 버튼을 제공하고 있습니다. showChannelButton 과 hideChannelButton 을 호출하여 채널 버튼을 나타내거나 숨길 수 있습니다.

다른 방법으로 메신저를 띄우거나, 채널 버튼의 UI를 변경하고자 하는 경우에는 커스터마이징 하기를 참고합니다.

ChannelIO.showChannelButton()
ChannelIO.hideChannelButton()

[ChannelIO showChannelButton];
[ChannelIO hideChannelButton];

Shutdown

SDK의 모든 기능을 사용 중지합니다. 만약 SDK의 기능을 다시 사용하기 위해서는 다시 부트해야 합니다.

ChannelIO.shutdown()

[ChannelIO shutdown];