이 문서에서는 Android 애플리케이션에서 Headless Mobile SDK를 통합하고 맞춤설정하는 방법을 설명합니다. CCAICall를 통한 음성 통화가 포함됩니다.
음성 통화
iOS용 헤드리스 모바일 SDK는 CCAICall 모듈을 통해 음성 통화 지원을 제공합니다. 앱은 맞춤 통화 UI를 소유하고 SDK는 통화 연결, CallKit 통합, VoIP 푸시 처리, 통화 수명 주기 이벤트를 처리합니다.
SDK에서 제공하는 기능: 인스턴트 통화 시작, 음성메일 시작, 수신 전화 처리, 통화 상태 관찰을 위한 호출 서비스 API
빌드하는 항목: 사전 통화 진입점, 녹음 동의 프롬프트, 벨소리 또는 대기 상태, 통화 중 제어, 통화 후 탐색 등 시각적 통화 환경
통화 모듈 초기화
핵심 SDK를 초기화한 후 호출 모듈을 초기화합니다.
import CCAIKit
import CCAICall
try CCAI.shared.initialize(options: options)
CCAI.shared.initializeCall(CallOptions())
VoiceCallChannel 기능 검사
즉석 통화를 제공하기 전에 대기열의 VoiceCallChannel 구조체를 검사하여 노출할 진입점 (즉석 통화, 음성메일 대체, 채널 수준 전환)과 녹음 동의가 필요한지 여부를 결정합니다.
주요 VoiceCallChannel 필드
instantEnabled: Bool?- 이 대기열에 라이브 (인스턴트) 음성 통화가 허용되는지 여부입니다.nil또는false을"don't offer an instant call button"상태로 처리합니다.voiceCall != nil는 대기열에 음성 채널이 있는지 여부만 알려줍니다.preSessionSmartAction: Bool?- 통화를 시작하기 전에 이 특정 채널에 사전 세션 스마트 작업이 필요한지 여부입니다. 보완적인 대기열 수준 경로는 iOS용 헤드리스 모바일 SDK: 스마트 작업, 첨부파일, 전환을 참고하세요.scheduleEnabled: Bool?- 예약된 통화가 지원되는지 여부입니다. 보완적인 대기열 수준 경로는 예약된 통화를 참고하세요.recordingOption: RecordingOption?- 통화 녹음 동의 모델 (녹음 동의 참고)RecordingPermission.notAsked(일정 예약 관련)와는 다릅니다.voicemailReason: String?- 채널이 음성사서함으로 라우팅되도록 구성된 경우 채워집니다.phoneNumber: String?- 전환 또는 음성메일용으로 구성된 PSTN 대체 번호입니다.scheduleDeflectionType: String?/deflected: Bool?/deflectedReason: String?- 채널 수준 전환 메타데이터입니다.deflected == true인 경우 즉시 통화를 시도하는 대신 관리자가 구성한deflectedReason메시지를 표시하고 구성된 대체 (예: 다이얼할 전화번호 또는 예약 통화 진입점)를 제공합니다. 대기열 수준 전환 처리는 전환 (근무 시간 외 및 과부하)을 참고하세요.
func voiceEntryPoints(for menu: QueueMenu) {
guard let voice = menu.channels?.voiceCall else {
hideCallNowButton()
hideVoicemailButton()
return
}
// Instant call - only when explicitly enabled and not deflected
callNowButton.isHidden = (voice.instantEnabled != true) || (voice.deflected == true)
// Voicemail fallback
if let number = voice.phoneNumber, voice.voicemailReason != nil {
showVoicemailButton(number: number, reason: voice.voicemailReason)
}
// Channel-level deflection
if voice.deflected == true {
showChannelDeflection(reason: voice.deflectedReason)
}
}
레코딩 동의
SDK에서 제공하는 항목: 포털에서 관리자가 구성한 통화 녹음 동의 모델을 설명하는 VoiceCallChannel의 recordingOption: RecordingOption? 필드
빌드하는 항목: 동의 메시지 (.askUser인 경우) 및 관리자의 선택을 따르는 분기 로직
public enum RecordingOption: String, Decodable {
case always // Calls are always recorded - surface a disclosure before connecting
case never // Calls are never recorded - no disclosure needed
case askUser // Prompt the user for consent before the call connects
}
func handleRecordingConsent(
for voice: VoiceCallChannel,
completion: @escaping (Bool) -> Void
) {
switch voice.recordingOption {
case .always:
showRecordingDisclosure(message: "This call will be recorded.")
completion(true)
case .never, .none:
completion(true)
case .askUser:
presentConsentPrompt { granted in
completion(granted)
}
}
}
즉석 통화 시작하기
인스턴트 통화를 시작하기 전에 다음 사항을 확인하세요.
선택한 대기열의
VoiceCallChannel를 검사합니다.인스턴트 통화가 사용 설정되어 있고 리디렉션되지 않았는지 확인합니다.
대기열의
recordingOption에 따라 녹화 동의를 처리합니다.마이크 사용 권한을 요청합니다.
startInstantCall를 호출합니다.
func initiateInstantCall(for menu: QueueMenu) async {
guard let voice = menu.channels?.voiceCall,
voice.instantEnabled == true,
voice.deflected != true else {
return
}
let recordingPermission = await resolveRecordingPermission(for: voice)
guard await requestMicrophonePermission() else { return }
do {
try await CCAI.shared.callService?.startInstantCall(
InstantCallRequest(
menuId: menu.id,
recordingPermission: recordingPermission
)
)
} catch {
showCallStartError(error)
}
}
통화 상태 관찰
통화를 시작하거나 수락하기 전에 call-service 이벤트에 구독합니다.
CCAI.shared.callService?.stateChanged
.receive(on: DispatchQueue.main)
.sink { state in
updateCallConnectionState(state)
}
.store(in: &cancellables)
CCAI.shared.callService?.callReceived
.receive(on: DispatchQueue.main)
.sink { call in
updateCallDetails(call)
}
.store(in: &cancellables)
CCAI.shared.callService?.incomingCallEvent
.receive(on: DispatchQueue.main)
.sink { event in
handleIncomingCallEvent(event)
}
.store(in: &cancellables)
CCAI.shared.callService?.waitTimeUpdated
.receive(on: DispatchQueue.main)
.sink { waitTime in
// The platform pushed a new estimated wait time for the active call.
updateEstimatedWaitTime(waitTime)
}
.store(in: &cancellables)
CCAI.shared.callService?.participantUpdated
.receive(on: DispatchQueue.main)
.sink { participant in
// Agent assignment, transfer, or participant metadata changed.
updateParticipantInfo(participant)
}
.store(in: &cancellables)
CCAI.shared.callService?.interruptionDetected
.receive(on: DispatchQueue.main)
.sink { interruption in
// A PSTN interruption (for example, an incoming cellular call)
// has paused the active CCAI call. Surface a "call interrupted"
// banner and offer a Resume action after the interruption ends.
showInterruptionBanner(reason: interruption)
}
.store(in: &cancellables)
CCAI.shared.callService?.deflectionOffered
.receive(on: DispatchQueue.main)
.sink { deflection in
// The platform offered a wait-time deflection (for example, a
// scheduled callback or PSTN fallback). Render the prompt and
// honor the user's choice.
presentWaitTimeDeflection(deflection)
}
.store(in: &cancellables)
공급자 상태와 서버 상태 비교
stateChanged와 callReceived.status는 독립적인 신호입니다. 행이 아닌 열로 읽으세요. 제공자의 stateChanged는 로컬 VoIP 핸드셰이크를 보고하고 서버 측 callReceived.status는 플랫폼에서 통화의 수명 주기를 보고합니다. stateChanged이 .connected에 도달하는 것이 아니라 callReceived.status에서 연결됨 플립과 통화 타이머 시작을 유도합니다.
| 신호 | 보고 내용 | 어떤 항목을 가져올지 |
|---|---|---|
stateChanged (제공업체) |
로컬 VoIP 핸드셰이크 - .connecting, .connected (로컬), .disconnected, .error(...) |
서버 상태가 도착하고 오류가 표시되고 통화 종료 정리 전에 선택적 사전 상태 스피너입니다. |
callReceived.status (서버) |
서버 측 수명 주기: .waiting, .connecting, .connected, .onHold, .interrupted, .ended |
연결됨, 뒤집기, 통화 타이머 시작, 상담사 할당 UI, 트랜스퍼 또는 에스컬레이션 오버레이, 통화 종료 흐름 |
통화 상태 및 서버 측 상태
SDK 제공 사항: 각 Call 페이로드에 서버 기반 CallStatus enum을 제공하여 호출이 수명 주기에서 어디에 있는지 설명합니다 (예: connecting, waiting, connected, onHold, interrupted, ended).
빌드하는 항목: CallStatus에서 통화 화면의 고객 대상 상태 (벨소리 울림, 대기열에서 대기, 연결됨, 대기 중, 중단됨, 종료됨)로의 매핑
구현 예시
각 callReceived 방출에서 call.status를 전환하고 일치하는 UI 상태를 렌더링합니다.
func updateCallDetails(_ call: Call) {
switch call.status {
case .connecting:
renderConnectingState()
case .waiting:
renderWaitingInQueueState(estimatedWait: call.estimatedWait)
case .connected:
renderConnectedState(agent: call.agent)
case .onHold:
renderOnHoldState()
case .interrupted:
renderInterruptedState()
case .ended, .failed:
renderEndedState(reason: call.endReason)
@unknown default:
break
}
}
통화 중 제어 (음소거, 스피커, 대기)
SDK 제공 사항: 각 상태를 전환하는 작업(setMuted, setSpeakerEnabled, setOnHold)과 함께 callService~isMuted, isSpeakerEnabled, isOnHold의 읽기 전용 속성
빌드하는 항목: SDK의 작업에 연결되고 현재 상태를 반영하는 통화 UI의 음소거, 스피커, 통화 보류 버튼
구현 예시
callService에서 현재 상태를 읽어 버튼을 초기화한 다음 탭 시 전환하고 업데이트합니다.
// Read current state
muteButton.isSelected = CCAI.shared.callService?.isMuted ?? false
speakerButton.isSelected = CCAI.shared.callService?.isSpeakerEnabled ?? false
holdButton.isSelected = CCAI.shared.callService?.isOnHold ?? false
// Toggle from your UI handlers
func onMuteTapped() {
let next = !(CCAI.shared.callService?.isMuted ?? false)
CCAI.shared.callService?.setMuted(next)
muteButton.isSelected = next
}
func onSpeakerTapped() {
let next = !(CCAI.shared.callService?.isSpeakerEnabled ?? false)
CCAI.shared.callService?.setSpeakerEnabled(next)
speakerButton.isSelected = next
}
func onHoldTapped() {
let next = !(CCAI.shared.callService?.isOnHold ?? false)
CCAI.shared.callService?.setOnHold(next)
holdButton.isSelected = next
}
통화가 중단된 후 진행 중인 통화 재개
PSTN 인터럽트 (예: 수신되는 모바일 통화)로 인해 활성 CCAI 통화가 일시중지되면 SDK는 세션을 활성 상태로 유지하고 interruptionDetected를 내보냅니다.
중단이 끝나면 앱에서 통화를 재개할 수 있습니다.
SDK에서 제공하는 기능: 진행 중인 통화를 조회하는 getLastCallInProgress() (앱 다시 시작 포함) 및 통화를 포그라운드로 다시 가져오는 resumeCall(_:)
빌드하는 항목: UI의 다시 시작 어포던스 (일반적으로 배너 또는 중단이 끝난 후 자동 다시 시작) 및 통화 화면으로 돌아가는 탐색
구현 예시
getLastCallInProgress로 진행 중인 통화를 조회하고, 통화를 재개하고, 통화 화면으로 다시 이동합니다.
func resumeIfInterrupted() async {
guard let call = try? await CCAI.shared.callService?.getLastCallInProgress() else {
return
}
do {
try await CCAI.shared.callService?.resumeCall(call)
navigateToCallScreen(call)
} catch {
showCallResumeError(error)
}
}
가상 에이전트의 에스컬레이션
SDK에서 제공하는 항목: canEscalate(allowSkipVirtualAgent:)는 callService 자체가 아닌 CallResponse (callService.callReceived에서 내보낸 모델)의 메서드입니다. 현재 통화가 통화의 현재 가상 상담사 상태에 따라 실제 상담사에게 에스컬레이션될 수 있는지 여부를 보고합니다.
빌드하는 항목: 가장 최근의 callReceived 방출을 "current call" 상태로 유지한 다음 사람과 대화하기 버튼의 표시 여부를 currentCall?.canEscalate(...)에 바인딩합니다. allowSkipVirtualAgent 인수는 호출 응답 자체에서 별도로 가져오는 메뉴 구성 값입니다. 프로덕션에서 true을 하드코딩하지 마세요.
구현 예시
저장된 속성에 최신 Call를 유지한 다음 canEscalate를 호출합니다.
메뉴 구성에서 allowSkipVirtualAgent을 해결합니다.
// Held from the most recent `callReceived` emission
private var currentCall: Call?
// `allowSkipVirtualAgent` is fetched separately from menu configuration
// it is not derived from the CallResponse.
let allowSkip = menuConfiguration.allowSkipVirtualAgent
let allowed = currentCall?.canEscalate(allowSkipVirtualAgent: allowSkip) ?? false
talkToAgentButton.isHidden = !allowed
음성메시지
SDK 제공 사항: callService의 startVoicemail(_ request: VoicemailRequest)와 플랫폼에서 음성 메일을 제공한 이유를 설명하는 VoicemailReason 열거형 (예: 근무 시간 외 대체, 용량 초과 대체, 임시 리디렉션)
빌드하는 항목: UI의 음성사서함 진입점 (일반적으로 VoiceCallChannel.voicemailReason이 채워지거나 통화 수명 주기가 음성사서함 결과로 해결될 때 표시됨) 및 녹음 UI 자체
구현 예시
voicemailReason가 설정되면 음성사서함 버튼을 표시한 다음 VoicemailRequest로 startVoicemail를 호출합니다.
public enum VoicemailReason: String, Decodable {
case afterHourDeflection
case overCapacityDeflection
case temporaryRedirection
}
func offerVoicemail(for menu: QueueMenu) async {
guard let voice = menu.channels?.voiceCall,
voice.voicemailReason != nil else {
return
}
do {
try await CCAI.shared.callService?.startVoicemail(
VoicemailRequest(menuId: menu.id)
)
} catch {
showVoicemailError(error)
}
}
대기 시간 전환
대기열이 열려 있지만 대기 시간이 관리자가 구성한 기준점을 초과하는 경우 플랫폼에서 대체 경로(일반적으로 예약된 콜백 또는 PSTN 전환)를 제공할 수 있습니다.
SDK 제공 사항: 제공된 대안을 설명하는 CallDeflection 페이로드로, 활성 통화의 경우 callService에서 getCallDeflection(callId:)를 사용하여 검색할 수 있습니다. 또한 플랫폼은 대기 중에 전환이 가능해지면 deflectionOffered 게시자를 통해 동일한 페이로드를 내보냅니다. 별도의 CompanyResponse.preventDirectPstnCall 플래그는 대체 UI에서 직접 PSTN 다이얼링을 숨겨야 하는지 여부를 나타냅니다.
빌드하는 항목: 전환 프롬프트 (예: 예상 대기 시간은 12분입니다. 대신 콜백을 예약하시겠어요?) 및 사용자의 선택을 따르는 분기 로직
구현 예시
getLastCallInProgress로 진행 중인 통화를 조회하고, getCallDeflection(callId:)로 제공된 전환을 가져오고, CompanyResponse.preventDirectPstnCall와 결합하고, 프롬프트를 표시합니다.
func evaluateWaitTimeDeflection() async {
guard let currentCall = try? await CCAI.shared.callService?.getLastCallInProgress() else {
return
}
let deflection = try? await CCAI.shared.callService?.getCallDeflection(
callId: currentCall.id
)
guard let offer = deflection else { return }
let company = try? await CCAI.shared.companyService?.get()
let allowDirectPstn = company?.preventDirectPstnCall != true
presentWaitTimeDeflection(offer, allowDirectPstn: allowDirectPstn)
}
청각 메시지 (시스템 공지사항)
SDK에서 제공하는 항목: 대기열의 관리자가 구성한 청각 메시지를 해결하는 audibleMessageService (예: 모든 상담사가 통화 중입니다) 기본적으로 SDK는 통화가 해당 상태로 전환되면 이러한 메시지를 자동으로 재생합니다.
빌드할 항목: 기본 모드에서는 아무것도 없습니다. 예를 들어 자막 텍스트와 자체 오디오 플레이어로 알림을 직접 렌더링하려면 playAudibleMessages = false로 통화 모듈을 초기화하고 resolveMessages(menuId:)를 직접 호출하세요.
구현 예시
SDK 재생 경로의 기본 이니셜라이저를 사용하거나 playAudibleMessages
= false를 설정하고 메시지를 직접 해결하여 자체 UI에서 자막을 렌더링하고 오디오를 재생합니다.
// Option A default: SDK plays audible messages automatically.
CCAI.shared.initializeCall(CallOptions())
// Option B your app renders the announcements manually.
CCAI.shared.initializeCall(CallOptions(playAudibleMessages: false))
let messages = try await CCAI.shared.audibleMessageService?.resolveMessages(
menuId: menu.id
)
for message in messages ?? [] {
renderCaption(message.text)
playAudio(message.audioURL)
}
고급 CallOptions
CallOptions는 기본 통화 환경을 선택 해제해야 하는 앱을 위한 작은 전환 버튼 세트를 노출합니다.
playAudibleMessages: Bool-false인 경우 SDK가 시스템 알림을 재생하지 않습니다.audibleMessageService를 사용하여 직접 렌더링하세요.callKitEnabled: Bool-false인 경우 SDK가 수신 또는 발신 전화에 내장된 CallKit 화면을 표시하지 않습니다. 앱이 iOS 시스템 UI에 의존하는 대신 자체 인앱 수신 전화 UI를 렌더링해야 하는 경우에 사용합니다.
구현 예시
호출 모듈을 초기화할 때 전환 버튼을 CallOptions에 전달합니다.
// Fully custom in-app call experience
CCAI.shared.initializeCall(
CallOptions(
playAudibleMessages: false,
callKitEnabled: false
)
)
화면 공유
화면 공유를 통해 지원 상담사는 사용자의 화면을 보고 문제를 해결할 수 있습니다. Google Cloud 프로젝트는 두 가지 화면 공유 모드를 지원합니다.
인앱 공유: 상담사는 특정 앱 내부에서 발생하는 상황만 볼 수 있습니다.
전체 기기 공유 (선택사항): 상담사가 iOS 홈 화면 및 기타 앱을 포함한 사용자의 전체 기기를 볼 수 있습니다. 이를 위해서는 Apple의 ReplayKit을 사용하여 고급 iOS 구성이 필요합니다.
SDK에서 제공하는 기능: 세션을 생성하고 관리하며, 상태 변경을 처리하고, 동의 요청을 처리하는 화면 공유 서비스입니다.
빌드하는 항목: 초기화 구성, 사용자 동의를 위한 UI 프롬프트, (전체 기기를 지원하는 경우) 내장 iOS 브로드캐스트 확장 프로그램
화면 공유 서비스는 전체 세션 수명 주기(create, activate, end, clear(iOS만 해당)) 메서드와 구성 메서드(updateOptions, enableRemoteControl, enableFullDeviceSharing)를 제공합니다. 다음 하위 섹션에서는 핵심 통합 흐름을 안내합니다.
모든 화면 공유 메서드의 전체 메서드 서명과 파라미터 세부정보는 헤드리스 모바일 SDK - iOS API 참조를 참고하세요.
화면 공유 초기화 및 구성
상담사가 화면 공유를 요청하려면 먼저 특정 화면 공유 라이선스 키로 서비스를 초기화하고 구성해야 합니다.
import com.ccaiplatform.ccaikit.CCAI
import com.ccaiplatform.ccaikit.initializeScreenShare
import com.ccaiplatform.ccaikit.models.screenShare.ScreenShareOptions
// Minimal domain defaults to your instance's configured provider
CCAI.initializeScreenShare(
context = this,
options = ScreenShareOptions(
key = "YOUR_COMPANY_KEY"
)
)
// If your instance or provider requires an explicit domain:
// CCAI.initializeScreenShare(
// context = this,
// options = ScreenShareOptions(
// key = "YOUR_COMPANY_KEY",
// domain = "your_subdomain.ccaiplatform.com"
// )
// )
화면 공유 자격 요건 확인
화면 공유 기능을 사용 설정하기 전에 현재 채팅에서 사용할 수 있는지 확인합니다.
let isChatSupportingScreenShare = CCAI.shared.screenShareService != nil
&& chat?.isSupportingScreenShare == true
화면 공유 요청 처리
screenShareService를 사용하여 화면 공유 요청 처리를 구현합니다. ScreenShareRequest를 만들고 비동기 응답을 처리합니다.
func requestScreenShare(isFromRemote: Bool) async {
guard let chatId = currentChatId else { return }
guard let screenShareService = CCAI.shared.screenShareService else {
handleError(ScreenShareError.serviceNotAvailable, message: "Request Screen Share")
return
}
// Track whether this session is agent-initiated
screenShareInitiatedFrom = isFromRemote ? .agent : .endUser
if !isFromRemote {
await sendScreenShareMessage(event: .screenShareRequestedFromEndUser)
}
do {
let response = try await screenShareService.create(
request: ScreenShareRequest(
communicationId: chatId,
communicationType: .chat,
initiatedFrom: isFromRemote ? .agent : .endUser
)
)
await sendScreenShareMessage(event: .screenShareCodeGenerated, response: response)
} catch {
await sendScreenShareMessage(event: .screenShareFailed)
handleError(error, message: "Request screen share error")
}
}
화면 공유 상태 변경 처리
서비스 게시자를 통해 화면 공유 상태와 요청을 관찰합니다. 세션을 만들거나 활성화하기 전에 구독하여 UI가 모든 전환에 응답할 수 있도록 합니다.
CCAI.shared.screenShareService?.statePublisher
.receive(on: DispatchQueue.main)
.sink { state in
currentScreenShareSessionState = state
if state == .authorizing, screenShareInitiatedFrom == .agent {
Task {
do {
try await handleStartSession(isAccepted: true)
} catch {
handleError(error, message: "Failed to start screen share")
}
}
}
}
.store(in: &cancellables)
CCAI.shared.screenShareService?.requestPublisher
.receive(on: DispatchQueue.main)
.sink { request in
switch request {
case .session:
if screenShareInitiatedFrom == .endUser {
showScreenSharePrompt(.startSession)
}
case .remoteControl:
showScreenSharePrompt(.remoteControl)
@unknown default:
break
}
}
.store(in: &cancellables)
ScreenShareServiceState enum은 .none, .pending, .authorizing, .active, .ended을 통해 세션 진행 상황을 추적합니다. 요청 게시자는 앱이 고객 대상 동의 프롬프트로 변환해야 하는 세션 및 원격 제어 요청을 내보냅니다.
전체 기기 화면 공유 (고급)
상담사가 자체 애플리케이션 외부의 화면을 볼 수 있도록 하려면 Apple 브로드캐스트 업로드 확장 프로그램을 구현해야 합니다. 이를 통해 iOS는 시스템 전체에서 화면을 캡처하고 동영상 프레임을Google Cloud 프로젝트 SDK에 안전하게 전달할 수 있습니다.
방송 확장 프로그램 타겟 추가
Xcode 프로젝트를 엽니다.
파일 > 새로 만들기 > 타겟으로 이동합니다.
방송 업로드 확장 프로그램을 선택합니다.
타겟의 이름을 입력합니다.
UI 확장 프로그램 포함을 선택 해제합니다.
번들 ID를 기록해 두고 타겟을 만듭니다.
브로드캐스트 확장 프로그램의 타겟 SDK를 iOS 12.0 이상으로 변경합니다.
키체인 공유 설정하기
앱과 앱 확장 프로그램은 자체 키체인 그룹을 사용하여 iOS 키체인을 통해 비밀을 공유해야 합니다.
Xcode에서 두 타겟의 서명 및 기능 탭으로 이동합니다.
키체인 공유 기능을 추가합니다.
두 타겟의 키체인 그룹에
io.cobrowse를 추가합니다.
기본 앱의 Info.plist 업데이트
앱의 Info.plist (확장 프로그램의 Info.plist 아님)에 확장 프로그램 번들 ID를 추가합니다.
<key>CBIOBroadcastExtension</key>
<string>your.app.extension.bundle.ID.here</string>
브로드캐스트 확장 프로그램 타겟에 CobrowseSDK 추가
Xcode에서 브로드캐스트 확장 프로그램 타겟을 선택한 상태로 Frameworks and Libraries 아래의 + 버튼을 선택하고 확장 프로그램 타겟에 CobrowseSDK를 추가합니다.
확장 프로그램 핸들러 구현
Xcode는 이전에 만든 타겟에 SampleHandler.swift 파일을 추가합니다.
SDK의 ReplayKit 확장 프로그램 클래스에서 상속받도록 파일의 내용을 다음으로 바꿉니다.
import CobrowseSDK
class SampleHandler: CobrowseIOReplayKitExtension {
// The Google Cloud project module automatically handles ReplayKit lifecycle methods
}
빌드 및 실행
이제 앱을 빌드하고 실행할 수 있습니다. 전체 기기 기능은 실제 기기에서만 사용할 수 있으며 iOS 시뮬레이터에서는 작동하지 않습니다.
모든 항목을 올바르게 설정했다면 파란색 원형 아이콘을 선택한 후 방송 확장 프로그램을 선택하는 화면이 표시됩니다.
화면 공유의 iOS SwiftUI 제한사항
SwiftUI의 원격 상호작용에 권장되는 접근 방식
주요 상호작용 요소를 UIKit로 래핑: 원격으로 클릭해야 하는 영역의 경우
UIViewRepresentable또는UIViewControllerRepresentable를 사용하여 UIKit 컨트롤 (예:UIButton)로 래핑합니다. 이렇게 하면 Cobrowse의 UIKit 경로를 사용하여 원격 클릭이 안정적으로 작동합니다.맞춤 터치 처리로 원격 터치 전달: UIKit으로 대체할 수 없는 SwiftUI 영역의 경우 Cobrowse의 맞춤 터치 콜백을 사용하여 원격 터치 이벤트를 SwiftUI 로직으로 전달합니다. 구현에는 맞춤
UIView또는 동작 인식기를 사용하여 콜백을 처리한 다음UIViewRepresentable와Coordinator, 알림 또는 클로저를 사용하여 이벤트를 SwiftUI로 브리징하는 작업이 포함됩니다.상품 수준 안내 또는 대체 제공: SwiftUI 화면에 상담사는 보기만 가능하며 사용자가 로컬로 탭해야 함을 명확하게 표시하거나 보기 전용 액세스를 유지하면서 이러한 페이지에서 원격 제어 권한을 자동으로 제한합니다.
UIKit 래퍼 구현 예
struct RemoteControlButton: UIViewRepresentable {
let title: String
let action: () -> Void
func makeUIView(context: Context) -> UIButton {
let button = UIButton(type: .system)
button.setTitle(title, for: .normal)
button.addTarget(
context.coordinator,
action: #selector(Coordinator.buttonTapped),
for: .touchUpInside
)
return button
}
func updateUIView(_ uiView: UIButton, context: Context) {
uiView.setTitle(title, for: .normal)
}
func makeCoordinator() -> Coordinator {
Coordinator(action: action)
}
class Coordinator: NSObject {
let action: () -> Void
init(action: @escaping () -> Void) {
self.action = action
}
@objc func buttonTapped() {
action()
}
}
}
// Usage in SwiftUI
struct ContentView: View {
var body: some View {
VStack {
Text("This screen supports remote control")
RemoteControlButton(title: "Clickable Button") {
print("Button tapped remotely or locally")
}
}
}
}
예약된 통화
예약된 통화를 사용하면 최종 사용자가 즉석 통화를 위해 대기열에서 기다리는 대신 향후 음성 통화를 예약할 수 있습니다. iOS 헤드리스 SDK에서는 대기열 및 채널 메타데이터를 사용하여 앱에 예약 진입점을 표시할지 결정합니다.
기능 감지
SDK에서 제공하는 기능: 선택한 대기열에서 즉석 (라이브) 음성 통화 지원 여부와 관계없이 향후 통화 예약을 지원하는지 알려주는 VoiceCallChannel의 scheduleEnabled 플래그
빌드하는 항목: 예약 진입점을 표시하기 전에 이 플래그를 확인하는 로직
구현 예시
대기열의 음성 통화 채널에서 scheduleEnabled를 확인합니다. voiceCall != nil를 프록시로 사용하지 마세요. 대기열은 예약된 통화를 지원하지 않고 즉석 음성 통화를 지원할 수 있으며 그 반대의 경우도 마찬가지입니다.
func setupScheduledCallEntryPoint(for menu: QueueMenu) {
guard let voiceChannel = menu.channels?.voiceCall else {
// No voice channel at all hide both instant and scheduled call buttons
hideCallNowButton()
hideScheduleCallButton()
return
}
// Instant voice call always show if voiceCall channel exists
showCallNowButton()
// Scheduled call check scheduleEnabled explicitly
if voiceChannel.scheduleEnabled == true {
showScheduleCallButton()
} else {
hideScheduleCallButton()
}
}
데이터 모델 참조
// VoiceCallChannel.swift
public struct VoiceCallChannel: Decodable {
// ...
public let scheduleEnabled: Bool? // true if scheduled calls are supported
// ...
}
// ChannelType.swift
public enum ChannelType {
case scheduleCall(deflectionType: DeflectionType?)
// ...
}
QueueMenu.getEnabledChannels()에서 반환된 사용 설정된 채널 목록에서 .scheduleCall를 확인할 수도 있습니다.
사용 가능한 시간대 가져오기
헤드리스 통화 서비스는 선택한 대기열의 사용 가능한 약속 시간을 가져올 수 있습니다. 앱이 캘린더 또는 시간 선택기 UI를 소유합니다.
SDK에서 제공하는 항목: 선택한 대기열의 사용 가능한 슬롯 타임스탬프(기존 예약된 통화의 재예약 지원 옵션 포함)
빌드하는 항목: 캘린더, 시간 선택기, 시간대 표시, 빈 상태 처리, 재시도 동작
구현 예시
대기열 메뉴 ID를 사용하여 getScheduledTimeSlots를 호출합니다. 일정을 다시 예약할 때는 서비스가 적절한 가용성을 반환할 수 있도록 기존 예약 통화 ID를 전달하세요.
let slots = try await CCAI.shared.callService?.getScheduledTimeSlots(
menuId: menu.id,
callIdForRescheduling: nil
) ?? []
기존 예약 통화를 다시 예약할 때는 서비스가 적절한 사용 가능 여부를 반환할 수 있도록 기존 통화 ID를 전달하세요.
let slots = try await CCAI.shared.callService?.getScheduledTimeSlots(
menuId: menu.id,
callIdForRescheduling: existingCallId
) ?? []
예약 통화 만들기
사용자가 시간대를 선택하면 callService를 통해 예약된 통화를 만듭니다.
SDK 제공 사항: 선택한 슬롯을 예약하고 예약된 통화 기록을 반환하는 createScheduledCall API
빌드하는 항목: E.164 전화번호 유효성 검사, 확인 UI, 예약된 통화 ID의 로컬 지속성, 예약 오류 복구
구현 예시
선택한 슬롯, 전화번호, 대기열 ID, RecordingPermission.notAsked을 ScheduledCallRequest에 전달합니다.
let response = try await CCAI.shared.callService?.createScheduledCall(
ScheduledCallRequest(
menuId: menu.id,
phoneNumber: userPhoneNumber,
scheduleTime: selectedSlot,
recordingPermission: .notAsked,
callIdForRescheduling: nil,
customData: nil,
ticketId: nil
)
)
saveScheduledCallId(response?.id)
전화번호는 +14155551234와 같은 E.164 형식이어야 합니다.
예약된 상담 일정 변경
일정을 변경하려면 기존 예약 통화 ID를 callIdForRescheduling로 전달합니다.
SDK에서 제공하는 항목: 동일한 시간대 및 생성 API이며, callIdForRescheduling는 기존 예약을 식별하는 데 사용됩니다.
빌드하는 항목: "change time" UI, 저장된 예약 통화 ID의 로컬 조회, 새 예약이 생성된 후 업데이트된 확인 상태
구현 예시
사용자가 새 슬롯을 선택한 후 기존 통화 ID를 createScheduledCall에 전달합니다.
let response = try await CCAI.shared.callService?.createScheduledCall(
ScheduledCallRequest(
menuId: menu.id,
phoneNumber: userPhoneNumber,
scheduleTime: newSelectedSlot,
recordingPermission: .notAsked,
callIdForRescheduling: existingCallId,
customData: nil,
ticketId: nil
)
)
saveScheduledCallId(response?.id)
예약된 통화 취소
사용자가 예정된 통화를 취소하면 cancelScheduledCall를 호출하고 로컬에 저장된 통화 ID를 삭제합니다.
SDK에서 제공하는 항목: 예약된 호출 ID의 취소 API
빌드하는 항목: 확인 프롬프트, 취소 성공 또는 오류 UI, 로컬에 저장된 예정된 통화 상태 정리
구현 예시
저장된 ID로 cancelScheduledCall(callId:)를 호출한 다음 앱의 저장소에서 ID를 삭제합니다.
try await CCAI.shared.callService?.cancelScheduledCall(callId: existingCallId)
clearScheduledCallId()
앱이 다시 시작된 후 예정된 통화 상태를 제공하거나, 일정을 변경하거나, 환경을 취소하려면 앱에 예약된 통화 ID를 유지하세요.
이메일
SDK에서 제공하는 항목: 특정 큐에 대해 구성된 대상 이메일 주소와 관리자가 사용자에게 표시하기를 원하는 안내 (예: 계좌 번호 포함)
빌드할 항목: 이메일 작성기 화면과 완료를 추적하는 위임자 자체 맞춤 양식을 빌드하거나 Apple의 기본 제공 MFMailComposeViewController를 사용할 수 있습니다.
구현 예시
이 코드는 SDK에서 지원 이메일 주소와 안내를 가져옵니다. 기본 제공 iOS 메일 작성기를 열고 MFMailComposeViewControllerDelegate를 사용하여 사용자가 보내기 또는 취소를 선택하는 정확한 순간을 수신 대기합니다.
import UIKit
import MessageUI
class SupportViewController: UIViewController, MFMailComposeViewControllerDelegate {
// 1. Trigger the email flow
func openEmailComposer(for menu: QueueMenu) {
guard let emailChannel = menu.channels?.email else { return }
if MFMailComposeViewController.canSendMail() {
let mail = MFMailComposeViewController()
mail.mailComposeDelegate = self
// Use the metadata provided by the SDK
mail.setToRecipients([emailChannel.email].compactMap { $0 })
mail.setMessageBody(emailChannel.instructionMessage ?? "", isHTML: false)
present(mail, animated: true)
} else {
showError("Mail services are not configured on this device.")
}
}
// 2. Track the outcome using Apple's delegate
func mailComposeController(
_ controller: MFMailComposeViewController,
didFinishWith result: MFMailComposeResult,
error: Error?
) {
controller.dismiss(animated: true)
switch result {
case .sent:
print("Email successfully sent!")
case .cancelled:
print("User cancelled the email.")
case .saved:
print("Email saved as draft.")
case .failed:
print("Email failed to send: \(error?.localizedDescription ?? "Unknown error")")
@unknown default:
break
}
}
}
외부 전환 링크
SDK에서 제공하는 항목: 관리자 포털에서 구성된 대로 회사 고객센터, 환불 정책, 파트너 앱과 같은 URL과 표시 제목 목록입니다.
빌드하는 항목: 사용자가 링크를 선택할 때(내장 인앱 브라우저에서 열거나 Safari 앱으로 전송) 링크를 실행하는 로직
구현 예시
이 도우미는 URL 문자열을 가져와 Apple의 인앱 브라우저에 표시합니다.
import SafariServices
func openHelpCenterLink(_ urlString: String) {
guard let url = URL(string: urlString) else { return }
let safariViewController = SFSafariViewController(url: url)
present(safariViewController, animated: true)
}
전체 통합 예시 (사용 설정된 모든 링크 반복)
iOS에서 ExternalDeflectionLink는 최상위 url를 포함하지 않습니다. 링크는 내부 links: [ExternalDeflection]? 배열 내에 있으며 사용 설정된 각 항목은 채널 메뉴에 버튼 하나를 제공합니다. 배열을 반복하고 enabled 플래그가 true이 아닌 항목을 건너뜁니다.
func setupDeflectionLinks(for queueMenu: QueueMenu) {
// Clear any previously-rendered buttons
helpCenterStackView.arrangedSubviews.forEach { $0.removeFromSuperview() }
guard let links = queueMenu.channels?.externalDeflectionLink?.links,
!links.isEmpty else {
helpCenterStackView.isHidden = true
return
}
helpCenterStackView.isHidden = false
for link in links where link.enabled == true {
let button = UIButton(type: .system)
button.setTitle(link.displayName, for: .normal)
button.addAction(UIAction { [weak self] _ in
self?.openHelpCenterLink(link.url)
}, for: .touchUpInside)
helpCenterStackView.addArrangedSubview(button)
}
}
ExternalDeflectionLink는 enabled: Bool? 및 links:
[ExternalDeflection]?를 노출합니다. 각 ExternalDeflection는 자체 url 및 displayName를 전달합니다. QueueMenu.getEnabledChannels()를 사용하는 경우 SDK는 사용 설정된 링크당 하나의 .externalDeflection(url:displayName:) 항목을 내보내므로 links를 직접 반복하고 사용 설정된 채널 출력을 반복하면 동일한 버튼 세트가 생성됩니다.