ChannelIO iOS SDK(이하 SDK)는 Swift / Objc로 작성된 애플리케이션에 실시간 상담 채팅 모듈을 쉽게 설치할 수 있는 플러그인입니다. 웹뷰 안이나 모바일 웹에 설치하고자 하는 경우는 JavaScript SDK 설치 가이드를 참고합니다.
시작하기 전에
SDK를 사용하기 위한 최소 요구사항은 다음과 같습니다.
- 채널톡 유료 플랜
- 구독 및 결제 페이지에서 현재 플랜을 확인할 수 있습니다.
- iOS deployment target 12.0 이상
- Swift 5.0 이상
- ChannelIO SDK 10.0.0 이상
설치하기
Swift Package Manager, CocoaPods, Carthage 를 통해 ChannelIO를 설치할 수 있습니다.
iOS SDK는 v11.5.0 버전 이상부터
PrivacyInfo.xcprivacy
를 SDK 내에 포함하고 있습니다. Privacy manifest 파일이 필요한 경우 해당 버전 이상을 사용해야 합니다.
Swift Package Manager로 설치하기
Swift Package Manager를 이용하여 SDK를 설치할 수 있습니다. Xcode 11 버전 이상이 필요합니다.
- Xcode의 네비게이터로 이동하여, 프로젝트 중 패키지를 설치할 프로젝트를 선택합니다.
Swift Package 탭으로 이동하여,+
버튼을 클릭합니다.
- 아래의
ChannelIO
의 패키지 주소를 입력합니다. 버전을 설정한 뒤,Add Package
버튼을 클릭합니다.
https://github.com/channel-io/channel-talk-ios-framework
CocoaPods로 설치하기
CocoaPods를 이용하여 ChannelIO iOS SDK를 설치할 수 있습니다. CocoaPods 1.10.0 버전 이상이 필요합니다.
- 프로젝트의
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'
Podfile
이 위치한 디렉토리에서pod install
커맨드를 실행하여 패키지를 설치합니다.Project_Name.xcworkspace
을 열어 사용합니다.
Carthage로 설치하기
Carthage를 이용하여 ChannelIO iOS SDK를 설치할 수 있습니다.
- 프로젝트의
Cartfile
에 아래와 같이ChannelIOSDK
를 추가합니다.
binary "https://mobile-static.channel.io/ios/latest/channeliosdk-ios.json"
Cartfile
이 위치한 곳에서 아래 커맨드를 이용하여 패키지를 설치합니다.
carthage update --platform iOS --use-xcframeworks
PROJECT_DIR/Carthage/build
폴더 안에 다운로드된 패키지를 Xcode로 드래그하여 추가합니다. 아래 사진을 참고합니다.
설치하고 나서
SDK를 사용하기 위해 다음과 같은 권한이 필요합니다. info.plist
에 아래 권한에 따른 설명을 추가합니다.
Key | Value |
---|---|
Privacy - Camera Usage Description | Accessing the camera to provide a better user experience |
Privacy - Photo Library Additions Usage Description | Accessing the photo library to provide a better user experience |
Privacy - Microphone Usage Description | Accessing the microphone to record voice for video |
SDK 버전이 10.0.7 미만 또는 iOS 최소 버전이 13 미만일 경우 아래의 권한을 추가합니다.
Key | Value |
---|---|
Privacy - Photo Library Usage Description | Accessing 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];
Sleep
track을 통한 이벤트 트래킹이나 푸시 알림만 사용하고자 할 때 사용할 수 있습니다. 채팅 상담이나 마케팅 팝업과 같은 기능이 작동하지 않습니다.
ChannelIO.sleep()
Shutdown
SDK의 모든 기능을 사용 중지합니다. 만약 SDK의 기능을 다시 사용하기 위해서는 다시 부트해야 합니다.
ChannelIO.shutdown()
[ChannelIO shutdown];