Headless Mobile SDK for iOS: Suara, berbagi layar, panggilan terjadwal, dan email

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. Perlakukan nil atau false sebagai status "don't offer an instant call button". Berbeda dengan voiceCall != 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 dengan RecordingPermission.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. Jika deflected == true, tampilkan pesan deflectedReason yang 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)
    }
}

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:

  1. Periksa VoiceCallChannel antrean yang dipilih.

  2. Pastikan panggilan instan diaktifkan dan tidak dialihkan.

  3. Tangani izin perekaman sesuai dengan recordingOption antrean.

  4. Minta izin mikrofon.

  5. 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 — saat false, SDK tidak memutar pengumuman sistem; render sendiri menggunakan audibleMessageService.

  • callKitEnabled: Bool — saat false, 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.cobrowse ke 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

  • Bungkus elemen interaktif utama dengan UIKit - untuk area yang perlu dapat diklik dari jarak jauh, bungkus sebagai kontrol UIKit (misalnya, UIButton) menggunakan UIViewRepresentable atau UIViewControllerRepresentable. 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 UIView atau pengenal gestur kustom untuk menangani callback, lalu menjembatani peristiwa ke SwiftUI (menggunakan UIViewRepresentable plus Coordinator, 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.

Email

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
        }
    }
}

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)
}

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.