ChannelIO iOS SDK 최소 지원 버전 조정 안내
2024년 12월 1일부터 ChannelIO iOS SDK의 최소 지원 버전이 iOS 15로 조정됩니다. 아래를 참고하여 앱의 최소 지원 버전에 맞게 SDK 버전을 조정해 주세요.
- v12.3.0 이상 : iOS 15
- v12.2.1 이하 : iOS 12
이 문서는 ChannelIO React Native SDK (이하 SDK)의 설치 과정을 설명합니다.
React Native 패키지 설치하기
SDK를 설치하기 위해 쉘에서 아래 명령을 실행합니다.
npm install react-native-channel-plugin
SDK는 모바일 SDK와 호환되는 버전 목록을 가지고 있습니다. 설치한 버전이 모바일 SDK와 호환되는지 확인하려면 이 버전 호환성 을 참조합니다.
iOS에 설치하기
이 단락은 iOS 환경에 ChannelIO SDK를 설치하는 방법을 안내합니다.
CocoaPods, Carthage를 통해서 SDK를 설치할 수 있습니다.
CocoaPods
CocoaPod을 이용하여 SDK를 설치할 수 있습니다. 요구사항은 다음과 같습니다.
- Xcode 12 이상
- CocoaPods 버전 1.10.0 이상
- 프로젝트의
Podfile에ChannelIO의존성을 추가합니다. 아래 예시를 참고합니다.
require_relative '../node_modules/react-native/scripts/react_native_pods'
require_relative '../node_modules/@react-native-community/cli-platform-ios/native_modules'
platform :ios, '11.0'
target 'testProject10' do
config = use_native_modules!
use_react_native!(:path => config["reactNativePath"])
pod 'ChannelIOSDK', podspec: 'https://mobile-static.channel.io/ios/latest/xcframework.podspec'
pod 'RNChannelIO', :path => '../node_modules/react-native-channel-plugin'
target 'YourApplicationName' do
inherit! :complete
# Pods for testing
end
# Comment out Flipper.
# Because, there is a conflict now
# use_flipper!
# post_install do |installer|
# flipper_post_install(installer)
# end
end
target 'YourApplicationName-tvOS' do
# Pods for testProject10-tvOS
target 'YourApplicationName-tvOSTests' do
inherit! :search_paths
# Pods for testing
end
end
특정 패키지 버전을 설치하는 경우는 ChannelIOSDK 스크립트 중간의 latest를 설치를 원하는 버전으로 변경합니다. 예시는 다음과 같습니다.
...
pod 'ChannelIOSDK', podspec: 'https://mobile-static.channel.io/ios/10.0.7/xcframework.podspec'
...
Podfile이 위치한 디렉토리에서pod install커맨드를 실행하여 패키지를 설치합니다.Project_Name.xcworkspace을 열어 사용합니다.
Carthage로 설치하기
Carthage를 이용하여 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로 드래그하여 추가합니다.
추가 설정
다음을 따라 iOS 프로젝트에 설정을 추가합니다.
1. Swift 버전 명시 추가
React-Native iOS 프로젝트는 순수 Objective-C 프로젝트이므로 버전 명시가 필요합니다.
- Xcode > Target > Build Setting 으로 이동합니다.
- 좌측 상단의
+> Add User-Defined Setting 을 눌러 설정을 추가합니다.
- 키 이름은 SWIFT_VERSION, 값은 5.0 으로 설정합니다.
2. SDK에서 사용하는 권한과 설명 추가
SDK를 사용하기 위해 다음과 같은 권한이 필요합니다. 프로젝트의 info.plist 에 아래 권한에 따른 설명을 추가합니다.
| Key | Value |
|---|---|
| Privacy - Camera Usage Description | Accessing to camera in order to provide better user experience |
| Privacy - Photo Library Additions Usage Description | Accessing to photo library in order to save photos |
| Privacy - Microphone Usage Description | Accessing to 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 provide better user experience |
3. Flipper 제거
현재 Flipper와 채널톡을 동시에 사용할 수 없습니다. Flipper를 주석처리하거나 제거하여 사용합니다.
Podfile을 수정합니다.
# use_flipper!
# post_install do |installer|
# flipper_post_install(installer)
# end
수정 후 pod install 커맨드를 실행합니다.
AppDelegate.m
// AppDelegate.m
// Comment out Flipper.
...
//#import <FlipperKit/FlipperClient.h>
//#import <FlipperKitLayoutPlugin/FlipperKitLayoutPlugin.h>
//#import <FlipperKitUserDefaultsPlugin/FKUserDefaultsPlugin.h>
//#import <FlipperKitNetworkPlugin/FlipperKitNetworkPlugin.h>
//#import <SKIOSNetworkPlugin/SKIOSNetworkAdapter.h>
//#import <FlipperKitReactPlugin/FlipperKitReactPlugin.h>
...
//static void InitializeFlipper(UIApplication *application) {
// FlipperClient *client = [FlipperClient sharedClient];
// SKDescriptorMapper *layoutDescriptorMapper = [[SKDescriptorMapper alloc] initWithDefaults];
// [client addPlugin:[[FlipperKitLayoutPlugin alloc] initWithRootNode:application withDescriptorMapper:layoutDescriptorMapper]];
// [client addPlugin:[[FKUserDefaultsPlugin alloc] initWithSuiteName:nil]];
// [client addPlugin:[FlipperKitReactPlugin new]];
// [client addPlugin:[[FlipperKitNetworkPlugin alloc] initWithNetworkAdapter:[SKIOSNetworkAdapter new]]];
// [client start];
//}
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
...
//#ifdef FB_SONARKIT_ENABLED
// InitializeFlipper(application);
//#endif
...
}
- iOS 프로젝트의
Build Setting으로 이동합니다. 경로는 Project > Build Settings 입니다.
Library Search Paths 를 검색하여, $(TOOLCHAIN_DIR)/usr/lib/swift-5.0/$(PLATFORM_NAME) 을 삭제합니다. 아래 사진을 참고합니다.
초기화 하기
SDK 사용을 위해 초기화가 필요합니다. AppDelegate.m 으로 이동하여 아래 코드를 추가합니다.
#import <ChannelIOFront/ChannelIOFront-swift.h>
@interface AppDelegate ()
@end
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
[ChannelIO initialize:application];
return YES;
}
만약 SceneDelegate.m 에서 window를 관리하는 경우, 아래 initializeWindow 메소드를 추가합니다.
// 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
안드로이드에 설치하기
이 단락은 안드로이드에 ChannelIO SDK를 설치하는 방법을 안내합니다.
Project - build.gradle
react-native-channel-plugin v0.9.0부터 안드로이드 설치법이 변경됩니다.
react-native-channel-plugin v0.9.0부터 안드로이드 설치법이 변경됩니다.
v0.9.0부터, channel.io의 maven repository를 추가해야합니다.
2025년 08월 01일까지는 기존처럼 Maven Central 역시 지원합니다.
하지만, 2025년 8월 1일 이후 버전부터는 Maven Central에 배포되지 않습니다.
project 레벨의 build.gradle 파일에 아래 내용처럼 ChannelTalk repository를 추가합니다.
buildscript {
...
repositories {
...
google()
mavenCentral()
maven {
url 'https://maven.channel.io/maven2'
name 'ChannelTalk'
}
...
}
...
}
만약 위 작업 이후 빌드 시 에러가 발생한다면, app 레벨의 build.gradle에 dependency를 추가해주세요.
dependencies {
implementation 'io.channel:plugin-android'
}
MultiDex
SDK 사용을 위해 multidex 설정이 필요합니다. 아래의 설정을 android/app/build.gradle 에 추가합니다.
android {
...
defaultConfig {
multiDexEnabled true
}
...
}
Link package & Initialize
ChannelIO 패키지를 링킹하고, 초기화 합니다. 아래 예시를 android/app/src/main/java/**/MainApplication.java 파일에 추가합니다.
import android.support.multidex.MultiDexApplication;
import com.zoyi.channel.plugin.android.ChannelIO;
import com.zoyi.channel.rn.RNChannelIOPackage;
public class MainApplication extends MultiDexApplication implements ReactApplication {
@Override
protected List<ReactPackage> getPackages() {
return Arrays.<ReactPackage>asList(
new MainReactPackage(),
new RNChannelIOPackage() // Add ChannelIO Package
);
}
@Override
public void onCreate() {
super.onCreate();
ChannelIO.initialize(this); // Initialize ChannelIO
}
}
SDK 사용하기
Step 1. Framework 추가하기
채널톡 사용이 필요한 곳에서 SDK를 import 합니다.
import { ChannelIO } from 'react-native-channel-plugin';
Step 2. Boot
Boot 는 SDK를 사용하기 위해 준비하는 과정입니다.
부트에는 플러그인 키가 필요합니다. 플러그인 키는 채널톡 이해하기 문서의 플러그인 키 얻기를 참고하여 준비합니다.
Boot 는 두가지 종류로, 익명의 유저로 부트 하거나, 멤버 유저로 부트 할 수 있습니다.
유저에 대한 자세한 설명은 멤버 유저를 참고합니다.
2 - 1. 익명의 유저로 부트하기
익명의 유저란, memberId가 부여되지 않은 유저입니다. 아래는 익명의 유저로 Boot 한 뒤, Boot의 결과값을 받는 예시입니다.
let settings = {
"pluginKey": YOUR_PLUGIN_KEY
};
ChannelIO.boot(settings).then((result) => {
});
Boot 의 메소드 파라미터인 settings 에는 pluginKey를 포함하여 몇가지 부트 옵션을 제공합니다.
2 - 2. 멤버 유저로 부트하기
멤버 유저란, memberId 가 부여된 유저입니다. 만약 로그인 되어있는 상태와 같이 자체적으로 유저를 구분할 수 있는 경우에는 memberId를 부여하여 멤버 유저로 부트합니다. 채널톡은 memberId를 이용하여 각 유저를 구분합니다.
Profile 모델을 이용하여, 유저에게 추가적인 정보를 주입할 수 있습니다.
보안을 위해서 멤버 해시 사용을 권장합니다
만약 아이디, 이메일과 같은 예측 가능한 값으로 memberId를 설정할 경우 인증되지 않은 제 3자가 memberId를 유추할 수 있습니다. 이 경우 제 3자가 고객의 개인 정보나 채팅 내역을 탈취할 수 있는 등 보안 위협에 노출될 수 있습니다. 보안을 위해서 멤버 해시를 설정하는 것을 권장합니다.
아래는, 특정 memberId 를 가진 멤버 유저를 부트하는 예시입니다.
let settings = {
"pluginKey": YOUR_PLUGIN_KEY,
"memberId": memberId,
"profile": {
"name": USER_NAME,
"mobileNumber": "01012345678"
}
}
ChannelIO.boot(settings).then((result) => {
});
채널 버튼 표시하기
SDK는 사용자가 메신저를 띄울 수 있도록 채널 버튼을 제공하고 있습니다. showChannelButton 과 hideChannelButton 을 호출하여 채널 버튼을 나타내거나 숨길 수 있습니다.
다른 방법으로 메신저를 띄우거나, 채널 버튼의 UI를 변경하고자 하는 경우에는 커스터마이징를 참고합니다.
ChannelIO.showChannelButton();
ChannelIO.hideChannelButton();
Shutdown
SDK의 모든 기능을 사용 중지합니다. 만약 SDK의 기능을 다시 사용하기 위해서는 다시 Boot해야 합니다.
ChannelIO.shutdown();