Dokumen ini menjelaskan cara mengintegrasikan dan menyesuaikan Headless Mobile SDK
di aplikasi Android Anda. Fitur ini mencakup panggilan suara melalui CCAICall
Panggilan suara
Headless Mobile SDK for iOS menyediakan dukungan panggilan suara melalui
modul CCAICall. Aplikasi Anda memiliki UI panggilan kustom, sementara SDK menangani
koneksi panggilan, integrasi CallKit, penanganan push VoIP, dan peristiwa
siklus proses panggilan.
Yang disediakan SDK: API layanan panggilan untuk memulai panggilan instan, memulai pesan suara, menangani panggilan masuk, dan mengamati status panggilan.
Yang Anda bangun: Pengalaman panggilan visual, termasuk titik masuk pra-panggilan, perintah izin perekaman, status berdering atau menunggu, kontrol dalam panggilan, dan navigasi pasca-panggilan.
Melakukan inisialisasi modul panggilan
Lakukan inisialisasi modul panggilan setelah melakukan inisialisasi SDK inti:
import CCAIKit
import CCAICall
try CCAI.shared.initialize(options: options)
CCAI.shared.initializeCall(CallOptions())
Memeriksa kemampuan VoiceCallChannel
Sebelum menawarkan panggilan instan, periksa struct VoiceCallChannel antrean
untuk memutuskan titik entri mana yang akan diekspos (panggilan instan, penggantian pesan suara,
pengalihan tingkat saluran) dan apakah izin perekaman diperlukan.
Kolom VoiceCallChannel utama
instantEnabled: Bool?- apakah panggilan suara live (instan) diizinkan untuk antrean ini. Perlakukannilataufalsesebagai status"don't offer an instant call button". Berbeda denganvoiceCall != nil, yang hanya memberi tahu Anda bahwa antrean memiliki saluran suara.preSessionSmartAction: Bool?- apakah tindakan smart pra-sesi diperlukan di saluran tertentu ini sebelum memulai panggilan. Lihat Headless Mobile SDK for iOS: Smart actions, attachments, and deflection untuk jalur tingkat antrean pelengkap.scheduleEnabled: Bool?- apakah panggilan terjadwal didukung. Lihat Panggilan terjadwal untuk jalur tingkat antrean pelengkap.recordingOption: RecordingOption?- model izin perekaman panggilan (lihat Izin perekaman). Berbeda denganRecordingPermission.notAsked, yang khusus untuk penjadwalan.voicemailReason: String?- diisi saat saluran dikonfigurasi untuk dialihkan ke pesan suara.phoneNumber: String?- Nomor pengganti PSTN yang dikonfigurasi untuk pengalihan atau pesan suara.scheduleDeflectionType: String?/deflected: Bool?/deflectedReason: String?- metadata pengalihan tingkat saluran. Jikadeflected == true, tampilkan pesandeflectedReasonyang dikonfigurasi admin dan tawarkan penggantian yang dikonfigurasi (misalnya, nomor telepon yang akan dihubungi atau titik entri panggilan terjadwal) daripada mencoba melakukan panggilan instan. Lihat Pengalihan (di luar jam kerja dan saat kapasitas penuh) untuk penanganan pengalihan tingkat antrean.
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)
}
}
Izin perekaman
Yang disediakan SDK: Kolom recordingOption: RecordingOption? di
VoiceCallChannel yang menjelaskan model izin perekaman panggilan yang dikonfigurasi admin
di portal.
Yang Anda bangun: Dialog izin (saat .askUser) dan logika percabangan
yang mematuhi pilihan admin.
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)
}
}
}
Memulai panggilan instan
Sebelum memulai panggilan instan:
Periksa
VoiceCallChannelantrean yang dipilih.Pastikan panggilan instan diaktifkan dan tidak dialihkan.
Tangani izin perekaman sesuai dengan
recordingOptionantrean.Minta izin mikrofon.
Panggil
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)
}
}
Mengamati status panggilan
Berlangganan ke peristiwa call-service sebelum memulai atau menerima panggilan:
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)
Status penyedia vs. status server
stateChanged dan callReceived.status adalah sinyal independen — baca sebagai kolom, bukan baris. stateChanged penyedia melaporkan handshake VoIP lokal; callReceived.status sisi server melaporkan siklus proses panggilan di platform. Dorong flip Terhubung dan mulai timer panggilan dari
callReceived.status — bukan dari stateChanged yang mencapai .connected.
| Sinyal | Yang dilaporkan | Yang dapat disimpulkan dari hal tersebut |
|---|---|---|
stateChanged (penyedia) |
Handshake VoIP lokal — .connecting, .connected (lokal), .disconnected, .error(...). |
Spinner pra-status opsional sebelum status server tiba, error muncul, dan pembersihan akhir panggilan. |
callReceived.status (server) |
Siklus proses sisi server — .waiting, .connecting, .connected, .onHold, .interrupted, .ended. |
Connected flip, mulai timer panggilan, UI yang ditetapkan agen, overlay transfer atau eskalasi, dan alur mengakhiri panggilan. |
Status panggilan dan status sisi server
Yang disediakan SDK: Enumerasi CallStatus yang didorong server pada setiap payload Call
yang menjelaskan posisi panggilan dalam siklus prosesnya (misalnya,
connecting, waiting, connected, onHold, interrupted, ended).
Yang Anda buat: Pemetaan dari CallStatus ke status yang ditampilkan kepada pelanggan
di layar panggilan Anda (berdering, menunggu dalam antrean, terhubung, ditahan, terganggu,
berakhir).
Contoh penerapan
Aktifkan call.status dari setiap emisi callReceived dan render status UI yang cocok.
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
}
}
Kontrol dalam panggilan (bisukan audio, speaker, tunggu)
Yang disediakan SDK: Properti hanya baca di callService — isMuted,
isSpeakerEnabled, isOnHold — beserta tindakan untuk mengubah setiap status
(setMuted, setSpeakerEnabled, setOnHold).
Yang Anda bangun: Tombol bisu, speaker, dan tunggu di UI dalam panggilan Anda, terhubung ke tindakan SDK dan mencerminkan status saat ini.
Contoh penerapan
Baca status saat ini dari callService untuk menginisialisasi tombol, lalu
alih dan perbarui saat diketuk.
// 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
}
Melanjutkan panggilan yang sedang berlangsung setelah terganggu
Saat gangguan PSTN (seperti panggilan seluler masuk) menjeda panggilan CCAI aktif, SDK akan mempertahankan sesi tetap aktif dan memancarkan interruptionDetected.
Setelah gangguan berakhir, aplikasi Anda dapat melanjutkan panggilan.
Yang disediakan SDK: getLastCallInProgress() untuk mencari panggilan yang sedang berlangsung (termasuk di seluruh proses mulai ulang aplikasi) dan resumeCall(_:) untuk membawanya kembali ke latar depan.
Yang Anda bangun: Kemampuan melanjutkan di UI Anda (biasanya banner atau melanjutkan otomatis setelah gangguan berakhir) dan navigasi kembali ke layar panggilan Anda.
Contoh penerapan
Cari panggilan yang sedang berlangsung dengan getLastCallInProgress, lanjutkan, dan
kembali ke layar panggilan Anda.
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)
}
}
Eskalasi dari agen virtual
Yang disediakan SDK: canEscalate(allowSkipVirtualAgent:) adalah metode di
CallResponse (model yang dikeluarkan oleh callService.callReceived), bukan di
callService itu sendiri. API ini melaporkan apakah panggilan saat ini memenuhi syarat untuk
eskalasi ke agen manusia berdasarkan status agen virtual panggilan saat ini.
Yang Anda bangun: Pertahankan emisi callReceived terbaru sebagai status
"current call" Anda, lalu ikat visibilitas tombol Bicara dengan orang
ke currentCall?.canEscalate(...). Argumen allowSkipVirtualAgent
adalah nilai konfigurasi menu yang Anda ambil secara terpisah dari respons panggilan
itu sendiri — jangan meng-hardcode true dalam produksi.
Contoh penerapan
Simpan Call terbaru dalam properti yang disimpan, lalu panggil canEscalate di dalamnya.
Selesaikan allowSkipVirtualAgent dari konfigurasi menu Anda.
// 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
Pesan suara
Yang disediakan SDK: startVoicemail(_ request: VoicemailRequest) di
callService, ditambah enum VoicemailReason yang menjelaskan alasan platform
menawarkan pesan suara sejak awal (misalnya, penggantian saat di luar jam kerja,
penggantian saat kapasitas berlebih, atau pengalihan sementara).
Yang Anda bangun: Titik entri pesan suara di UI Anda (biasanya ditampilkan saat
VoiceCallChannel.voicemailReason diisi, atau saat siklus proses panggilan
diselesaikan ke hasil pesan suara) dan UI perekaman itu sendiri.
Contoh penerapan
Tampilkan tombol pesan suara saat voicemailReason disetel, lalu panggil
startVoicemail dengan VoicemailRequest.
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)
}
}
Pengalihan waktu tunggu
Jika antrean terbuka, tetapi waktu tunggu melebihi batas yang dikonfigurasi admin, platform dapat menawarkan jalur alternatif, biasanya berupa panggilan balik terjadwal atau pengalihan PSTN.
Yang disediakan SDK: Payload CallDeflection yang menjelaskan alternatif yang ditawarkan, yang dapat diambil menggunakan getCallDeflection(callId:) di callService untuk panggilan aktif. Platform juga memancarkan payload yang sama melalui
deflectionOffered penayang saat pengalihan tersedia di tengah penantian. Tanda CompanyResponse.preventDirectPstnCall terpisah menunjukkan apakah panggilan PSTN langsung harus disembunyikan di UI penggantian Anda.
Yang Anda buat: Perintah pengalihan (misalnya, Perkiraan waktu tunggu adalah 12 menit — jadwalkan panggilan balik saja?) dan logika percabangan yang mematuhi pilihan pengguna.
Contoh penerapan
Cari panggilan aktif dengan getLastCallInProgress, ambil pengalihan
yang ditawarkan dengan getCallDeflection(callId:), gabungkan dengan
CompanyResponse.preventDirectPstnCall, dan tampilkan perintah.
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)
}
Pesan suara (pengumuman sistem)
Yang disediakan SDK: audibleMessageService yang menyelesaikan pesan audio yang dikonfigurasi admin untuk antrean (misalnya, Semua agen sedang sibuk). Secara default, SDK memutar pesan ini secara otomatis saat panggilan
memasuki status yang sesuai.
Yang Anda bangun: Tidak ada, dalam mode default. Jika Anda lebih suka merender pengumuman sendiri (misalnya, sebagai teks teks plus pemutar audio Anda sendiri), inisialisasi modul panggilan dengan playAudibleMessages = false dan panggil resolveMessages(menuId:) secara langsung.
Contoh penerapan
Gunakan penginisialisasi default untuk jalur yang diputar SDK, atau tetapkan playAudibleMessages
= false dan selesaikan pesan sendiri untuk merender teks dan memutar audio di UI Anda sendiri.
// 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)
}
Lanjutan CallOptions
CallOptions mengekspos sejumlah kecil tombol untuk aplikasi yang perlu menonaktifkan
pengalaman panggilan default.
playAudibleMessages: Bool— saatfalse, SDK tidak memutar pengumuman sistem; render sendiri menggunakanaudibleMessageService.callKitEnabled: Bool— saatfalse, SDK tidak menampilkan layar CallKit bawaan untuk panggilan masuk atau keluar. Gunakan ini saat aplikasi Anda perlu merender UI panggilan masuk dalam aplikasi sendiri, bukan mengandalkan UI sistem iOS.
Contoh penerapan
Teruskan tombol ke CallOptions saat menginisialisasi modul panggilan.
// Fully custom in-app call experience
CCAI.shared.initializeCall(
CallOptions(
playAudibleMessages: false,
callKitEnabled: false
)
)
Berbagi layar
Berbagi layar memungkinkan agen dukungan melihat layar pengguna untuk membantu memecahkan masalah. Google Cloud Project ini mendukung dua mode berbagi layar:
Berbagi dalam aplikasi: agen hanya dapat melihat apa yang terjadi di dalam aplikasi spesifik Anda.
Berbagi seluruh perangkat (opsional): agen dapat melihat seluruh perangkat pengguna, termasuk layar utama iOS dan aplikasi lainnya. Hal ini memerlukan konfigurasi iOS lanjutan menggunakan ReplayKit Apple.
Yang disediakan SDK: Layanan berbagi layar yang membuat dan mengelola sesi, menangani perubahan status, dan memproses permintaan izin.
Yang Anda bangun: Konfigurasi inisialisasi, dialog UI untuk izin pengguna, dan (jika mendukung perangkat lengkap) Ekstensi Siaran iOS bawaan.
Layanan berbagi layar menyediakan metode untuk siklus proses sesi penuh -
create, activate, end, clear (khusus iOS) - ditambah metode konfigurasi
updateOptions, enableRemoteControl, dan enableFullDeviceSharing. Subbagian
berikut akan membahas alur integrasi inti.
Untuk mengetahui tanda tangan metode dan detail parameter lengkap untuk semua metode berbagi layar, lihat Headless Mobile SDK - iOS API Reference.
Melakukan inisialisasi dan mengonfigurasi berbagi layar
Sebelum agen dapat meminta berbagi layar, Anda harus menginisialisasi dan mengonfigurasi layanan dengan kunci lisensi berbagi layar spesifik Anda.
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"
// )
// )
Memeriksa kelayakan berbagi layar
Sebelum mengaktifkan fungsi berbagi layar, periksa apakah fungsi tersebut tersedia untuk chat saat ini:
let isChatSupportingScreenShare = CCAI.shared.screenShareService != nil
&& chat?.isSupportingScreenShare == true
Menangani permintaan berbagi layar
Terapkan penanganan permintaan berbagi layar menggunakan screenShareService. Anda
membuat ScreenShareRequest dan menangani respons asinkron:
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")
}
}
Menangani perubahan status berbagi layar
Amati status dan permintaan berbagi layar melalui penayang layanan. Berlangganan sebelum membuat atau mengaktifkan sesi agar UI Anda dapat merespons setiap transisi.
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)
Enum ScreenShareServiceState melacak progres sesi melalui .none,
.pending, .authorizing, .active, dan .ended. Penerbit permintaan memancarkan
permintaan sesi dan kontrol jarak jauh yang harus diterjemahkan aplikasi Anda menjadi
dialog izin yang ditampilkan kepada pelanggan.
Berbagi layar seluruh perangkat (lanjutan)
Untuk mengizinkan agen melihat layar dari aplikasi di luar aplikasi Anda sendiri, Anda harus menerapkan Ekstensi Upload Siaran Apple. Hal ini memungkinkan iOS merekam layar di seluruh sistem dan menyerahkan frame video dengan aman ke SDK projectGoogle Cloud .
Menambahkan target ekstensi siaran
Buka project Xcode Anda.
Buka File > New > Target…
Pilih Ekstensi Upload Siaran.
Masukkan nama untuk target.
Hapus opsi Sertakan Ekstensi UI.
Buat target, dengan mencatat ID paketnya.
Ubah target SDK ekstensi siaran Anda ke iOS 12.0 atau yang lebih tinggi.
Menyiapkan berbagi keychain
Aplikasi dan ekstensi aplikasi Anda harus berbagi rahasia menggunakan iOS Keychain menggunakan grup Keychain mereka sendiri.
Di Xcode, buka tab Signing & Capabilities untuk kedua target.
Tambahkan kemampuan Keychain Sharing.
Tambahkan
io.cobrowseke Grup Keychain untuk kedua target.
Perbarui Info.plist aplikasi utama Anda
Tambahkan ID paket ekstensi ke Info.plist aplikasi Anda (bukan Info.plist
ekstensi):
<key>CBIOBroadcastExtension</key>
<string>your.app.extension.bundle.ID.here</string>
Menambahkan CobrowseSDK ke target ekstensi siaran Anda
Di Xcode, dengan target ekstensi siaran yang dipilih, pilih tombol +
di bagian Frameworks and Libraries, lalu tambahkan CobrowseSDK ke target
ekstensi Anda.
Menerapkan pengendali ekstensi
Xcode menambahkan file SampleHandler.swift ke target yang Anda buat sebelumnya.
Ganti konten file dengan kode berikut sehingga file mewarisi dari
class ekstensi ReplayKit SDK:
import CobrowseSDK
class SampleHandler: CobrowseIOReplayKitExtension {
// The Google Cloud project module automatically handles ReplayKit lifecycle methods
}
Mem-build dan menjalankan
Sekarang Anda siap untuk membangun dan menjalankan aplikasi. Kemampuan perangkat penuh hanya tersedia di perangkat fisik - tidak berfungsi di Simulator iOS.
Jika telah menyiapkan semuanya dengan benar, setelah memilih ikon lingkaran biru, Anda akan melihat layar untuk memilih ekstensi siaran.
Batasan SwiftUI iOS untuk berbagi layar
Pendekatan yang direkomendasikan untuk interaksi jarak jauh di SwiftUI
Bungkus elemen interaktif utama dengan UIKit - untuk area yang perlu dapat diklik dari jarak jauh, bungkus sebagai kontrol UIKit (misalnya,
UIButton) menggunakanUIViewRepresentableatauUIViewControllerRepresentable. Hal ini memastikan klik jarak jauh berfungsi dengan andal menggunakan jalur UIKit Cobrowse.Teruskan sentuhan jarak jauh dengan penanganan sentuhan kustom - untuk area SwiftUI yang tidak dapat diganti dengan UIKit, gunakan callback sentuhan kustom Cobrowse untuk meneruskan peristiwa sentuhan jarak jauh ke logika SwiftUI Anda. Penerapan melibatkan penggunaan
UIViewatau pengenal gestur kustom untuk menangani callback, lalu menjembatani peristiwa ke SwiftUI (menggunakanUIViewRepresentableplusCoordinator, notifikasi, atau penutupan).Memberikan panduan atau penggantian tingkat produk - tunjukkan dengan jelas di layar SwiftUI bahwa Agen hanya dapat melihat; pengguna harus mengetuk secara lokal, atau membatasi izin kontrol jarak jauh secara otomatis di halaman ini sambil mempertahankan akses hanya lihat.
Contoh penerapan wrapper 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")
}
}
}
}
Panggilan terjadwal
Panggilan terjadwal memungkinkan pengguna akhir memesan panggilan suara di masa mendatang, bukan menunggu dalam antrean untuk panggilan instan. Di iOS headless SDK, gunakan metadata antrean dan channel untuk memutuskan apakah akan menampilkan titik entri penjadwalan di aplikasi Anda.
Deteksi kemampuan
Yang disediakan SDK: Flag scheduleEnabled di VoiceCallChannel yang memberi tahu Anda apakah antrean yang dipilih mendukung penjadwalan panggilan mendatang — terlepas dari apakah panggilan suara instan (live) tersedia.
Yang Anda buat: Logika untuk memeriksa tanda ini sebelum menampilkan titik entri penjadwalan Anda.
Contoh penerapan
Periksa scheduleEnabled di saluran panggilan suara antrean. Jangan gunakan
voiceCall != nil sebagai proxy — antrean dapat mendukung panggilan suara instan tanpa
mendukung panggilan terjadwal, dan sebaliknya.
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()
}
}
Referensi model data
// 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?)
// ...
}
Anda juga dapat memeriksa .scheduleCall dalam daftar channel yang diaktifkan yang ditampilkan oleh
QueueMenu.getEnabledChannels().
Mengambil slot waktu yang tersedia
Layanan panggilan headless dapat mengambil waktu janji temu yang tersedia untuk antrean yang dipilih. Aplikasi Anda memiliki UI kalender atau pemilih waktu.
Yang disediakan SDK: Stempel waktu slot yang tersedia untuk antrean yang dipilih, dengan dukungan opsional untuk menjadwalkan ulang panggilan terjadwal yang ada.
Yang akan Anda bangun: Kalender, pemilih waktu, presentasi zona waktu, penanganan status kosong, dan perilaku percobaan ulang.
Contoh penerapan
Panggil getScheduledTimeSlots dengan ID menu antrean. Saat menjadwalkan ulang, teruskan
ID panggilan terjadwal yang ada sehingga layanan dapat menampilkan ketersediaan
yang sesuai.
let slots = try await CCAI.shared.callService?.getScheduledTimeSlots(
menuId: menu.id,
callIdForRescheduling: nil
) ?? []
Saat menjadwalkan ulang panggilan terjadwal yang ada, teruskan ID panggilan yang ada agar layanan dapat menampilkan ketersediaan yang sesuai:
let slots = try await CCAI.shared.callService?.getScheduledTimeSlots(
menuId: menu.id,
callIdForRescheduling: existingCallId
) ?? []
Membuat panggilan terjadwal
Setelah pengguna memilih slot waktu, buat panggilan terjadwal melalui
callService.
Yang disediakan SDK: API createScheduledCall yang memesan slot
yang dipilih dan menampilkan catatan panggilan terjadwal.
Yang Anda bangun: Validasi nomor telepon E.164, UI konfirmasi, persistensi lokal ID panggilan terjadwal, dan pemulihan untuk kesalahan penjadwalan.
Contoh penerapan
Teruskan slot yang dipilih, nomor telepon, ID antrean, dan
RecordingPermission.notAsked dalam 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)
Nomor telepon harus dalam format E.164, seperti +14155551234.
Menjadwalkan ulang panggilan terjadwal
Untuk menjadwalkan ulang, teruskan ID panggilan terjadwal yang ada sebagai callIdForRescheduling.
Yang disediakan SDK: API slot waktu dan pembuatan yang sama, dengan
callIdForRescheduling digunakan untuk mengidentifikasi pemesanan yang ada.
Yang Anda bangun: UI "change time", pencarian lokal ID panggilan terjadwal yang disimpan, dan status konfirmasi yang diperbarui setelah pemesanan baru dibuat.
Contoh penerapan
Teruskan ID panggilan yang ada ke createScheduledCall setelah pengguna memilih slot
baru.
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)
Membatalkan panggilan terjadwal
Saat pengguna membatalkan panggilan mendatang, panggil cancelScheduledCall dan hapus ID panggilan yang disimpan secara lokal.
Yang disediakan SDK: API pembatalan untuk ID panggilan terjadwal.
Yang Anda bangun: Prompt konfirmasi, UI keberhasilan atau error pembatalan, dan pembersihan status panggilan mendatang yang disimpan secara lokal.
Contoh penerapan
Panggil cancelScheduledCall(callId:) dengan ID yang disimpan, lalu hapus ID dari
penyimpanan aplikasi Anda.
try await CCAI.shared.callService?.cancelScheduledCall(callId: existingCallId)
clearScheduledCallId()
Pertahankan ID panggilan terjadwal di aplikasi Anda jika Anda ingin menawarkan status panggilan mendatang, menjadwalkan ulang, atau membatalkan pengalaman setelah aplikasi dimulai ulang.
Yang disediakan SDK: Alamat email tujuan yang dikonfigurasi untuk antrean tertentu tersebut, beserta petunjuk apa pun yang ingin dilihat pengguna oleh administrator (misalnya, Sertakan nomor akun Anda).
Yang akan Anda buat: Layar penyusun email dan delegasi untuk melacak penyelesaiannya. Anda dapat membuat formulir kustom Anda sendiri, atau menggunakan
MFMailComposeViewController bawaan Apple.
Contoh penerapan
Kode ini menarik alamat email dan petunjuk dukungan dari SDK. Tindakan ini akan membuka komposer email iOS bawaan dan menggunakan
MFMailComposeViewControllerDelegate untuk memantau saat pengguna
memilih Kirim atau Batal.
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
}
}
}
Link pengalihan eksternal
Yang disediakan SDK: Daftar URL (seperti Pusat Bantuan perusahaan Anda, kebijakan pengembalian dana, atau aplikasi partner) dan judul tampilannya, persis seperti yang dikonfigurasi di portal administrator.
Yang Anda buat: Logika untuk mengeksekusi link tersebut saat pengguna memilihnya - baik dengan membukanya di browser dalam aplikasi bawaan atau mengirimkannya ke aplikasi Safari.
Contoh penerapan
Helper ini mengambil string URL dan menampilkannya di browser dalam aplikasi Apple.
import SafariServices
func openHelpCenterLink(_ urlString: String) {
guard let url = URL(string: urlString) else { return }
let safariViewController = SFSafariViewController(url: url)
present(safariViewController, animated: true)
}
Contoh integrasi penuh (mengulangi semua link yang diaktifkan)
Di iOS, ExternalDeflectionLink tidak memiliki url tingkat teratas - link berada di dalam array links: [ExternalDeflection]? dalam, dan setiap entri yang diaktifkan menyumbangkan satu tombol ke menu channel. Lakukan iterasi pada array dan lewati entri
yang flag enabled-nya bukan 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 menampilkan enabled: Bool? dan links:
[ExternalDeflection]?. Setiap ExternalDeflection memiliki url dan
displayName-nya sendiri. Jika QueueMenu.getEnabledChannels() digunakan, SDK akan memancarkan satu entri
.externalDeflection(url:displayName:) per link yang diaktifkan - sehingga mengulangi
links secara langsung dan mengulangi output saluran yang diaktifkan akan menghasilkan set
tombol yang sama.