iOS SDK

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

사전 요구사항

항목	요구사항
iOS	15.0 이상
Swift	5.7 이상
Plugin Key	대시보드 → 채팅 설정 → 연동 / 개발 → 연동 설정에서 발급

Plugin Key 위치

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

설치

CocoaPods
Swift Package Manager

Podfile 에 다음을 추가합니다.

Podfile
pod 'ZeroTalkSDK', '0.1.15'

pod install

이후 .xcworkspace 파일로 프로젝트를 엽니다.

최신 버전 확인

CocoaPods — ZeroTalkSDK 에서 최신 버전을 확인할 수 있습니다.

Xcode → File → Add Package Dependencies 에서 다음 URL을 입력합니다.

https://github.com/generativelab-develop/zerotalk-ios-sdk

버전 규칙은 Exact Version (0.1.15) 으로 설정합니다.

최신 버전 확인

GitHub Releases — zerotalk-ios-sdk 에서 최신 버전을 확인할 수 있습니다.

위젯 시작 (boot)

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

import ZeroTalkSDK

ZeroTalk.boot(ZeroTalkConfig(
  pluginKey: "YOUR_PLUGIN_KEY",
  apiBaseUrl: "https://api.talk.zeroworks.ai/api/v1",
  wsUrl: "wss://api.talk.zeroworks.ai/ws/sdk"
)) { status in
  switch status {
  case .success:
    ZeroTalk.showMessenger()
  case .failed(let error):
    print("[ZeroTalk] boot 실패: \(error)")
  }
}

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

boot 중복 호출

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

위젯 표시·숨김

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

사용자 인증

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

ZeroTalk.boot(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
)) { _ in }

memberHash 는 서버에서 계산합니다

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

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

고급 기능

이벤트 콜백

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

class MyViewController: UIViewController {

  override func viewDidLoad() {
    super.viewDidLoad()
    ZeroTalk.setDelegate(self)
  }
}

extension MyViewController: ZeroTalkDelegate {
  func onMessengerShow() { }
  func onMessengerHide() { }
  func onBadgeChanged(unread: Int) { }
  func onLinkClicked(url: String) -> Bool { return false }
  func onRouteRequested(path: String) { }
  func onConnectionStatusChanged(_ status: ZeroTalkConnectionStatus) { }
  func onError(_ error: ZeroTalkError) { }
  func onPermissionRequested(type: String) { }
}

푸시 알림 (APNs)

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

사전 준비 — 대시보드에 APNs 인증 키 등록 (관리자)

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

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

입력 항목	무엇을 / 어디서
.p8 키 파일	Apple Developer → Certificates, Identifiers & Profiles → Keys 에서 Apple Push Notifications service (APNs) 를 체크해 키를 생성하고 `.p8` 파일을 다운로드합니다 (생성 시 1회만 다운로드 가능).
Key ID	키 생성 시 표시되는 10자리 식별자 (Keys 목록에서도 확인).
Team ID	Apple Developer → Membership 탭의 10자리 Team ID.
Bundle ID	앱 번들 식별자 (Xcode → Target → General → Bundle Identifier). 예: `com.company.app`
환경	Production (App Store·TestFlight 빌드) 또는 Sandbox (개발용) (Xcode 로 직접 설치한 개발 빌드). 앱이 디바이스 토큰을 발급받은 환경과 일치해야 푸시가 도착합니다.

1단계: Xcode 에서 Push Notifications Capability 를 추가합니다.

Xcode → 프로젝트 선택 → Target → Signing & Capabilities → + Capability → Push Notifications

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

AppDelegate.swift
func application(
  _ application: UIApplication,
  didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data
) {
  ZeroTalk.initPushToken(deviceToken)
}

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

테마

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

// boot 시점에 적용
ZeroTalkConfig(
  pluginKey: "YOUR_PLUGIN_KEY",
  // ...
  theme: ["--zerotalk-primary": "#6C5CE7"]
)

// 런타임에 변경
ZeroTalk.setTheme(["--zerotalk-primary": "#6C5CE7"])

다크모드 (Appearance)

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

ZeroTalkConfig(
  pluginKey: "YOUR_PLUGIN_KEY",
  // ...
  appearance: .system   // .system | .light | .dark
)

값	설명
`.system`	OS 다크모드 설정을 따름 (기본값)
`.light`	항상 라이트 모드
`.dark`	항상 다크 모드

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

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

ZeroTalkConfig(
  pluginKey: "YOUR_PLUGIN_KEY",
  // ...
  profile: [
    "name": "홍길동",
    "email": "hong@example.com",
    "phone": "010-1234-5678"
  ],
  customFields: [
    "plan": "premium",
    "company_id": "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`	`[String: Any]?`	선택	사용자 이름·이메일 등 프로필 정보
`customFields`	`[String: Any]?`	선택	커스텀 속성 (플랜, 회사 ID 등)
`theme`	`[String: String]?`	선택	CSS 변수 토큰 (색상 커스터마이징)
`appearance`	`ZeroTalkAppearance`	선택	위젯 외관 모드. 기본값 `.system`

ZeroTalkAppearance

값	설명
`.system`	OS 다크모드 설정을 따름 (기본값)
`.light`	항상 라이트 모드
`.dark`	항상 다크 모드

ZeroTalkDelegate

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

ZeroTalkConnectionStatus

케이스	설명
`.connected`	WebSocket 연결됨
`.disconnected`	WebSocket 연결 끊김
`.connecting`	연결 시도 중

정적 메서드

메서드	설명
`boot(_:completion:)`	위젯 초기화
`showMessenger()`	위젯 열기
`hideMessenger()`	위젯 닫기
`toggle()`	열림 ↔ 닫힘 전환
`shutdown()`	위젯 종료 및 WebView 해제
`setDelegate(_:)`	이벤트 콜백 수신 객체 설정
`initPushToken(_:)`	APNs 디바이스 토큰 등록
`notifyPermission(type:granted:)`	OS 권한 응답 통보 (`"camera"` 등). `"push"` 토글 용도로는 사용하지 않습니다.
`setTheme(_:)`	런타임 테마 변경

ZeroTalkError

케이스	설명
`notBootedYet`	`boot` 호출 전에 다른 메서드를 호출했을 때
`bootInProgress`	`boot` 가 아직 진행 중일 때 중복 호출
`invalidConfig`	`pluginKey` 등 필수 설정값이 유효하지 않을 때
`loadFailed`	위젯 리소스 로드 실패
`noActiveScene`	활성 UIWindowScene 이 없을 때
`bootTimeout`	boot 완료 타임아웃
`bridgeError(code: Int, message: String)`	위젯 내부 오류

다음 단계

Android SDK — Kotlin / Maven Central 설치 가이드
회원 인증 — HMAC-SHA256 memberHash 계산 방법
웹 위젯 커스터마이징 — 색상, 위치, 인사 메시지 설정

사전 요구사항​

설치​

위젯 시작 (boot)​

위젯 표시·숨김​

사용자 인증​

고급 기능​

이벤트 콜백​

푸시 알림 (APNs)​

테마​

다크모드 (Appearance)​

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

API 레퍼런스​

ZeroTalkConfig​

ZeroTalkAppearance​

ZeroTalkDelegate​

ZeroTalkConnectionStatus​

정적 메서드​

ZeroTalkError​

다음 단계​