Android SDK

Android 앱에 ZeroTalk 채팅 위젯을 추가하는 방법을 안내합니다. 설치를 마치면 앱 위에 채팅 오버레이가 표시되며, 사용자는 네이티브 앱 경험을 유지하면서 상담을 시작할 수 있습니다.

사전 요구사항

항목	요구사항
Android	API 26 (Android 8.0) 이상
Kotlin	1.8 이상
Plugin Key	대시보드 → 채팅 설정 → 연동 / 개발 → 연동 설정에서 발급

Plugin Key 위치

대시보드 → 채팅 설정 → 연동 / 개발 → 연동 설정 → 웹사이트 카드 → Plugin Key 관리 → + 키 생성 에서 Plugin Key (pk_live_...) 를 발급받습니다.

설치

build.gradle (앱 모듈) 의 dependencies 에 다음을 추가합니다.

Kotlin DSL (.kts)

app/build.gradle.kts

dependencies {
  implementation("ai.zeroworks:zerotalk-android-sdk:1.0.5")
}

Groovy DSL

app/build.gradle

dependencies {
  implementation 'ai.zeroworks:zerotalk-android-sdk:1.0.5'
}

Maven Central 은 기본 저장소에 포함되어 있습니다. 별도 저장소 설정 없이 바로 동기화합니다.

# Android Studio → Sync Project with Gradle Files

최신 버전 확인

Maven Central 에서 ai.zeroworks:zerotalk-android-sdk 의 최신 버전을 확인할 수 있습니다.

위젯 시작 (boot)

boot 는 앱 실행 시 한 번 호출합니다. 일반적으로 로그인 완료 후 또는 앱 홈 화면 진입 시점이 적합합니다.

import ai.zeroworks.zerotalk.BootStatus
import ai.zeroworks.zerotalk.ZeroTalk
import ai.zeroworks.zerotalk.ZeroTalkConfig

ZeroTalk.boot(
  context = this,
  config = ZeroTalkConfig(
    pluginKey = "YOUR_PLUGIN_KEY",
    apiBaseUrl = "https://api.talk.zeroworks.ai/api/v1",
    wsUrl = "wss://api.talk.zeroworks.ai/ws/sdk"
  )
) { status ->
  when (status) {
    is BootStatus.Success -> ZeroTalk.showMessenger(this)
    is BootStatus.Failed  -> Log.e("ZeroTalk", "boot 실패: ${status.error}")
  }
}

boot 완료 전에 showMessenger() 를 호출해도 완료 후 자동으로 표시됩니다.

boot 중복 호출

boot 는 한 번만 호출합니다. 사용자를 전환하거나 위젯을 재시작해야 하는 경우 shutdown() 호출 후 새 config 로 boot 를 재호출합니다.

위젯 표시·숨김

ZeroTalk.showMessenger(context)   // 위젯 열기
ZeroTalk.hideMessenger()          // 위젯 닫기
ZeroTalk.toggle(context)          // 열림 ↔ 닫힘 전환
ZeroTalk.shutdown()               // 위젯 완전 종료 및 WebView 해제

사용자 인증

로그인 사용자를 연동하면 상담 이력이 유지되고 사용자 정보가 대시보드에 표시됩니다.

ZeroTalk.boot(
  context = this,
  config = ZeroTalkConfig(
    pluginKey = "YOUR_PLUGIN_KEY",
    apiBaseUrl = "https://api.talk.zeroworks.ai/api/v1",
    wsUrl = "wss://api.talk.zeroworks.ai/ws/sdk",
    memberId = currentUser.id,
    memberHash = computedHmac
  )
)

memberHash 는 서버에서 계산합니다

memberHash 는 Secret Key 로 계산한 HMAC-SHA256 서명입니다. 계산식: HMAC-SHA256(secretKey, memberId) — hex lowercase 결과값. secretKey 와 memberId 는 모두 UTF-8 인코딩된 바이트를 사용합니다. Secret Key 를 앱 코드에 포함하면 누구든 임의의 사용자로 위장할 수 있습니다. 반드시 자사 백엔드 API 를 통해 계산하여 앱에 전달합니다.

Secret Key 는 대시보드 → 채팅 설정 → 연동 / 개발 → 연동 설정 → 웹사이트 카드 → Plugin Key 관리 에서 확인합니다. 생성 시 한 번만 표시되므로 반드시 기록해 두세요.

고급 기능

이벤트 콜백

ZeroTalkListener 를 구현하면 위젯 상태 변화를 수신할 수 있습니다.

class MainActivity : AppCompatActivity(), ZeroTalkListener {

  override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    ZeroTalk.setListener(this)
  }

  override fun onMessengerShow() { }
  override fun onMessengerHide() { }
  override fun onBadgeChanged(unread: Int) { }
  override fun onLinkClicked(url: String): Boolean { return false }
  override fun onRouteRequested(path: String) { }
  override fun onConnectionStatusChanged(status: ZeroTalkConnectionStatus) { }
  override fun onError(error: ZeroTalkError) { }
  override fun onPermissionRequested(type: String) { }
}

파일 첨부

위젯 내 파일 첨부 기능을 활성화하려면 Activity.onActivityResult 결과를 SDK 에 위임합니다.

MainActivity.kt

override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
  if (ZeroTalk.onActivityResult(requestCode, resultCode, data)) return
  super.onActivityResult(requestCode, resultCode, data)
}

푸시 알림 (FCM)

FCM 토큰을 등록하면 앱이 백그라운드 상태일 때 새 메시지 알림을 받을 수 있습니다.

사전 준비 — 대시보드에 FCM 자격증명 등록 (관리자)

아래 앱 설정으로 토큰을 등록해도, 대시보드에 FCM 자격증명이 등록돼 있지 않으면 푸시가 발송되지 않습니다. 워크스페이스 관리자가 먼저 한 번 등록해야 합니다.

대시보드 → 설정(⚙) → 연동 / 개발 → 모바일 SDK 푸시 페이지의 Android FCM 카드에서 다음을 업로드합니다.

입력 항목	무엇을 / 어디서
Service Account JSON	Firebase Console → 프로젝트 설정 → 서비스 계정 → 새 비공개 키 생성 으로 다운로드한 JSON 파일 (FCM HTTP v1 방식, legacy server key 아님).

1단계: AndroidManifest.xml 에 서비스를 등록합니다.

AndroidManifest.xml

<service
  android:name=".MyFirebaseMessagingService"
  android:exported="false">
  <intent-filter>
    <action android:name="com.google.firebase.MESSAGING_EVENT" />
  </intent-filter>
</service>

2단계: 서비스에서 토큰을 SDK 에 전달합니다.

MyFirebaseMessagingService.kt

class MyFirebaseMessagingService : FirebaseMessagingService() {

  override fun onNewToken(token: String) {
    ZeroTalk.initPushToken(token)
  }
}

앱 시작 시 현재 토큰도 전달합니다.

FirebaseMessaging.getInstance().token.addOnSuccessListener { token ->
  ZeroTalk.initPushToken(token)
}

앱 내 푸시 알림 ON/OFF 토글 API 는 현재 SDK 에 노출되어 있지 않습니다. 사용자가 알림을 받지 않으려면 OS 알림 설정에서 앱 알림을 꺼야 합니다. 앱 내 토글은 향후 위젯 UI / 대시보드 설정에서 제공될 예정입니다.

Android 13 (API 33) 이상

POST_NOTIFICATIONS 권한이 필요합니다. AndroidManifest.xml 의 <manifest> 직속에 <uses-permission android:name="android.permission.POST_NOTIFICATIONS" /> 를 선언하고, 호스트 앱에서 OS 권한 다이얼로그를 호출하여 사용자 허용을 받습니다.

테마

CSS 변수 토큰으로 위젯 색상을 커스터마이징합니다.

// boot 시점에 적용
ZeroTalkConfig(
  pluginKey = "YOUR_PLUGIN_KEY",
  // ...
  theme = mapOf("--zerotalk-primary" to "#6C5CE7")
)

// 런타임에 변경
ZeroTalk.setTheme(mapOf("--zerotalk-primary" to "#6C5CE7"))

다크모드 (Appearance)

기기 OS 다크모드 설정에 따라 위젯 외관을 자동 전환합니다. 기본값은 SYSTEM 으로 OS 설정을 따릅니다.

ZeroTalkConfig(
  pluginKey = "YOUR_PLUGIN_KEY",
  // ...
  appearance = Appearance.SYSTEM  // SYSTEM | LIGHT | DARK
)

값	설명
SYSTEM	OS 다크모드 설정을 따름 (기본값)
LIGHT	항상 라이트 모드
DARK	항상 다크 모드

Activity 에서 uiMode 구성 변경을 직접 처리하는 경우, AndroidManifest.xml 에 configChanges 를 선언한 뒤 onConfigurationChanged 에서 SDK 에 변경 사항을 전달합니다.

AndroidManifest.xml

<activity
  android:name=".MainActivity"
  android:configChanges="uiMode|screenSize|orientation" />

MainActivity.kt

override fun onConfigurationChanged(newConfig: Configuration) {
  super.onConfigurationChanged(newConfig)
  ZeroTalk.onConfigurationChanged(newConfig)
}

사용자 프로필·커스텀 필드

대시보드에서 사용자 정보를 확인할 수 있도록 프로필 정보와 커스텀 속성을 전달합니다.

ZeroTalkConfig(
  pluginKey = "YOUR_PLUGIN_KEY",
  // ...
  profile = mapOf(
    "name" to "홍길동",
    "email" to "hong@example.com",
    "phone" to "010-1234-5678"
  ),
  customFields = mapOf(
    "plan" to "premium",
    "company_id" to "company_123"
  )
)

:::info customFields 키 명명 규칙

대시보드에 미리 등록된 커스텀 필드만 저장됩니다. 키는 정규식 ^[a-z][a-z0-9_]{0,99}$ 을 만족해야 합니다 — 소문자로 시작하고, 영문 소문자·숫자·_ 만 허용, 길이 1–100자.

• ✅ plan, company_id, nested_plan
• ❌ Plan (대문자 시작), companyId (camelCase), company.id (점 포함), 1plan (숫자 시작)

규칙 위반 키 또는 대시보드 미등록 키는 무시되거나 422 VALIDATION_FAILED 응답을 받을 수 있습니다.

:::

:::tip profile.phone 형식

profile.phone 은 E.164 정규화(예: +821012345678) 후 저장됩니다. 010-1234-5678 처럼 한국식으로 보내도 무방합니다. 이전 키 mobileNumber 는 서버에서 인식하지 않으므로 phone 으로 사용하세요.

:::

API 레퍼런스

ZeroTalkConfig

파라미터	타입	필수	설명
pluginKey	String	필수	대시보드에서 발급한 Plugin Key
apiBaseUrl	String	필수	https://api.talk.zeroworks.ai/api/v1
wsUrl	String	필수	wss://api.talk.zeroworks.ai/ws/sdk
memberId	String?	선택	로그인 사용자 ID. 비회원이면 생략
memberHash	String?	선택	HMAC-SHA256 서명. 회원 인증 시 필수
profile	Map<String, Any>?	선택	사용자 이름·이메일 등 프로필 정보
customFields	Map<String, Any>?	선택	커스텀 속성 (플랜, 회사 ID 등)
theme	Map<String, String>?	선택	CSS 변수 토큰 (색상 커스터마이징)
appearance	Appearance	선택	위젯 외관 모드. 기본값 SYSTEM

Appearance

값	설명
SYSTEM	OS 다크모드 설정을 따름 (기본값)
LIGHT	항상 라이트 모드
DARK	항상 다크 모드

ZeroTalkListener

메서드	설명
onMessengerShow()	위젯이 열렸을 때
onMessengerHide()	위젯이 닫혔을 때
onBadgeChanged(unread: Int)	읽지 않은 메시지 수 변경
onLinkClicked(url: String): Boolean	링크 클릭. false (기본) — SDK 가 확인 다이얼로그 후 앱 내 브라우저로 열기. true — SDK 는 열지 않고 호스트 앱이 자체 처리
onRouteRequested(path: String)	앱 내 화면 이동 요청
onConnectionStatusChanged(status: ZeroTalkConnectionStatus)	WebSocket 연결 상태 변경
onError(error: ZeroTalkError)	오류 발생
onPermissionRequested(type: String)	카메라 등 권한 요청

ZeroTalkConnectionStatus

값	설명
CONNECTED	WebSocket 연결됨
DISCONNECTED	WebSocket 연결 끊김
CONNECTING	연결 시도 중

정적 메서드

메서드	설명
boot(context, config) { status -> }	위젯 초기화
showMessenger(context)	위젯 열기
hideMessenger()	위젯 닫기
toggle(context)	열림 ↔ 닫힘 전환
shutdown()	위젯 종료 및 WebView 해제
setListener(listener)	이벤트 콜백 수신 객체 설정
initPushToken(token: String)	FCM 토큰 등록
notifyPermission(type: String, granted: Boolean)	OS 권한 응답 통보 ("camera" 등). "push" 토글 용도로는 사용하지 않습니다.
setTheme(tokens: Map<String, String>)	런타임 테마 변경
onActivityResult(requestCode, resultCode, data): Boolean	파일 첨부용 Activity 결과 위임. true 반환 시 SDK 가 처리
onConfigurationChanged(newConfig: Configuration)	다크모드 즉시 반영

ZeroTalkError

케이스	설명
NotBootedYet	boot 호출 전에 다른 메서드를 호출했을 때
BootInProgress	boot 가 아직 진행 중일 때 중복 호출
InvalidConfig	pluginKey 등 필수 설정값이 유효하지 않을 때
LoadFailed	위젯 리소스 로드 실패
BootTimeout	boot 완료 타임아웃
BridgeError(code, message)	위젯 내부 오류

다음 단계

• iOS SDK — Swift / CocoaPods · SPM 설치 가이드
• 회원 인증 — HMAC-SHA256 memberHash 계산 방법
• 웹 위젯 커스터마이징 — 색상, 위치, 인사 메시지 설정