English한국어

시작하기

빠르게 시작하기

채널톡 안드로이드 SDK(이하 SDK)는 코틀린/자바로 작성된 애플리케이션에 상담을 위한 채팅 모듈과 마케팅 기능을 쉽게 설치할 수 있도록 도와줍니다. 웹뷰 안이나 모바일 웹에 설치하고자 하는 경우는 JavaScript SDK 설치 가이드를 참고합니다.

설치하기 앞서

아래와 같은 조건을 만족했는지 확인합니다:

  • 채널톡 유료 플랜
    • 구독 및 결제 페이지에서 현재 플랜을 확인할 수 있습니다.
  • 최소 설치 가능 안드로이드 SDK ≥ 15
    • 동작에 필요한 안드로이드 API 레벨은 21로, API 레벨이 15~20인 경우 기능을 이용할 수 없습니다.
  • 권장 Android Gradle Plugin ≥ 8.0.0
  • sourceCompatibility, targetCompatibility ≥ 1.8
  • SDK가 사용하는 Kotlin 버전은 1.8.22입니다. 이보다 낮은 버전을 사용하고 있을 경우 Gradle dependency resolution과 관련한 이슈가 발생할 수 있습니다.

설치하기

채널톡 SDK를 설치하기 위해서는 아래와 같이 의존성을 추가합니다. 최신 버전은 아래의 뱃지에서 확인할 수 있습니다.
Maven Central

버전 릴리즈 이후 1년간 유지보수가 보장됩니다. 자세한 내용은 릴리즈 노트를 참고합니다.

dependencies {
	implementation 'io.channel:plugin-android:$[version]'
}

repositories {
	mavenCentral()
}

SDK가 사용 중인 의존성

SDK를 사용함에 따라서 버전 충돌이 발생하면 추가적인 Gradle 설정이 필요할 수 있습니다. 채널톡 안드로이드 SDK는 가능한 한 의존성 충돌 방지를 위해서 자체적으로 모듈의 패키지를 변경해서 사용하고 있습니다. 만약 관련한 문제가 발생한다면 새로운 상담을 열어주세요.

Proguard 설정 (선택)

10.0.0 이하 버전을 사용하고 있다면 SDK가 정상적으로 동작할 수 있도록 아래와 같이 ProGuard를 설정합니다. 10.0.1 이상 버전에서는 이미 SDK에 설정되어 있으므로 별도 설정이 필요하지 않습니다.

-keep class com.zoyi.**{ *; }
-keep class io.channel.**{ *; }
-dontwarn com.zoyi.**
-dontwarn io.channel.**

초기 설정

채널톡 SDK를 사용하기 위해서 Application#onCreate()에서 ChannelIO.initialize()를 호출해야 합니다. 앱의 Application을 별도로 작성하지 않았다면 새로 생성합니다.

class MyApplication : Application() {
	override fun onCreate() {
		super.onCreate()

		ChannelIO.initialize(this)
	}
}

안드로이드 Cleartext Traffic 설정

안드로이드 API 28 이상에서는 암호화되지 않은 HTTP 통신을 기본적으로 비허용합니다. 이에 따라 유저와의 상담에서 HTTP만을 지원하는 웹사이트 링크를 전달하면 SDK에 내장된 웹뷰가 웹사이트에 연결할 수 없습니다. 이 문제를 해결하는 가장 좋은 방법은 고객에게 HTTPS 링크만을 전달드리는 것입니다. 하지만 만약 상담을 함에 있어서 HTTP 링크를 전달해야 할 것 같다면 AndroidManifest.xml 파일의 속성을 아래와 같이 수정하여 허용할 수 있습니다.

<application
	...
	android:usesCleartextTraffic="true">

🚧

위와 같은 방식으로 모든 HTTP 요청을 허용하는 것은 보안상 문제를 일으킬 수 있으므로 주의해야 합니다. 더 자세한 내용은 네트워크 보안 설정에 관한 안드로이드 공식 문서를 확인합니다.

채널톡 사용하기

초기화를 한 이후 SDK를 특정 채널과 연결하기 위해서는 SDK를 부트(boot)해야 합니다. 부트에 필요한 정보는 채널 플러그인 키이며, 선택적으로 유저 정보 혹은 여러 설정을 입력할 수도 있습니다. 데스크에서 플러그인 키를 얻는 방법을 참고합니다.

익명 유저로 부트하기

익명 유저는 채널톡이 신원을 확인할 수 없는 유저로, 같은 유저가 다른 기기에서 상담을 한다면 과거 채팅 기록을 확인할 수 없습니다. 로그인 하지 않은 상태와 같이 유저를 특정할 수 없는 환경에서 아래와 같이 부트할 수 있습니다.

val bootConfig = BootConfig.create(YOUR_PLUGIN_KEY)

멤버 유저로 부트하기

만약 로그인 되어 있는 상태와 같이 유저를 구분할 수 있는 기준이 있는 경우, 그 기준을 memberId로써 사용해 부트할 수 있습니다. 채널톡은 memberId가 부여된 유저를 멤버 유저로 분류하며, 각 유저를 구분하는 기준이 됩니다. BootConfig#setMemberId()를 사용하면 memberId를 설정할 수 있습니다.

❗️

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

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

val profile = Profile.create()
	.setName(userName)
	.setEmail(userEmail)
	.setProperty("homepageUrl", "channel.io")

val bootConfig = BootConfig.create(YOUR_PLUGIN_KEY)
	.setMemberId(memberId)
	.setProfile(profile)

ChannelIO.boot(bootConfig)

📘

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

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

부트 결과 전달 받기

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

ChannelIO.boot(bootConfig) { bootStatus: BootStatus, user: User? ->
	// ...
}

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

채널 버튼 표시하기

채널톡 안드로이드 SDK는 사용자가 쉽게 메신저를 띄울 수 있도록 채널 버튼을 제공하고 있습니다. ChannelIO.showChannelButton()을 호출하면 채널 버튼이 사용자가 보고 있는 모든 액티비티에 표시됩니다. 채널 버튼을 숨기고자 하는 경우에는 ChannelIO.hideChannelButton()을 호출합니다. 더 자세한 내용은 ChannelIO.showChannelButton()과 ChannelIO.hideChannelButton()의 레퍼런스를 참고합니다.

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

일부 액티비티에서만 채널톡 UI 숨기기

만약 일부 액티비티에서 채널 버튼과 팝업을 표시하고 싶지 않은 경우 @SkipAttachChannelView 어노테이션을 액티비티 클래스에 붙일 수 있습니다. 어노테이션을 붙이면 ChannelIO.showChannelButton()을 호출하거나, BootConfig#setHidePopup(Boolean)의 값에 관계 없이 마케팅 메시지나 메시지가 와도 채널톡의 UI가 표시되지 않습니다.

@SkipAttachChannelView
class SkipButtonActivity : AppCompatActivity() {
	// ...
}

sleep

track을 통한 이벤트 트래킹이나 푸시 알림만 사용하고자 할 때 사용할 수 있습니다. 채팅 상담이나 마케팅 팝업과 같은 기능이 작동하지 않습니다.

ChannelIO.sleep()

shutdown

SDK의 모든 기능을 사용 중지합니다. 채팅 상담, 마케팅, 이벤트 트래킹과 푸시 알림이 모두 작동을 멈추게 됩니다. SDK의 기능을 사용하기 위해서는 다시 부트해야 합니다.

예를 들어 로그인 한 상태에서만 SDK 기능을 사용하는 서비스에서 사용자가 로그아웃 하는 경우 답변이나 마케팅 푸시 알림을 받을 필요가 없어지므로 ChannelIO.shutdown()을 사용할 수 있습니다.

ChannelIO.shutdown()