Headless Mobile SDK for iOS: Tindakan cerdas, lampiran, dan pengalihan

Dokumen ini menjelaskan cara mengintegrasikan dan menyesuaikan Headless Mobile SDK di aplikasi Android Anda. Fitur ini mencakup semua hal yang menambahkan informasi terstruktur yang kaya ke sesi dukungan Anda: tindakan smart pra-sesi untuk pengambilan konteks, tindakan smart dalam sesi yang dipicu oleh agen (termasuk verifikasi biometrik dengan LocalAuthentication), formulir web dan kustom, lampiran yang dimulai oleh konsumen dan agen, serta penanganan pengalihan untuk skenario di luar jam kerja dan kelebihan kapasitas.

Mengonfigurasi tindakan dan lampiran smart

Tindakan smart memungkinkan agen dan konsumen bertukar informasi terstruktur yang kaya, seperti foto, video, cuplikan teks, dan verifikasi biometrik (Face ID dan Touch ID).

Dalam arsitektur Headless, SDK bertindak secara ketat sebagai lapisan transportasi yang aman. Pemberitahuan ini memberi tahu Anda kapan tindakan diperlukan atau diminta, dan pemberitahuan ini mentransfer data secara aman ke platform project Google Cloud . Karena Anda memiliki antarmuka pengguna, aplikasi Anda sepenuhnya bertanggung jawab untuk menggambar layar kamera, pemilih foto, kotak teks, dan memicu perintah Face ID Apple.

Tindakan cerdas pra-sesi

Tindakan pra-sesi mengumpulkan konteks (seperti nomor akun atau video produk yang rusak) sebelum pengguna bergabung ke antrean, sehingga mengurangi waktu penanganan agen secara signifikan.

Yang disediakan SDK: Aturan dan persyaratan untuk antrean tertentu (misalnya, apakah verifikasi biometrik, upload foto, atau input teks bersifat opsional atau wajib sebelum bergabung).

Yang Anda bangun: Layar UI pra-sesi (kamera, input teks, dan perintah Face ID) yang muncul antara pengguna mengetuk antrean dan memasuki ruang tunggu, serta logika penyiapan cache disk untuk menyimpan media dengan aman hingga sesi terhubung.

Contoh penerapan

Kode ini memeriksa konfigurasi SDK untuk melihat apakah antrean yang dipilih memiliki persyaratan pra-sesi. Contoh ini menunjukkan cara menangani persyaratan video dengan mempertahankan referensi URL file di disk, bukan menyimpan video dalam memori.

// 1. Check requirements and collect data BEFORE joining the queue
func checkPreSessionRequirements(for menu: QueueMenu) {
    guard let smartActions = menu.settings else {
        startChat(for: menu)
        return
    }

    // Example: handle a video requirement
    presentVideoPicker { (localFileURL) in
        // IMPORTANT: localFileURL should point to NSTemporaryDirectory()
        MySessionStateManager.shared.pendingPreSessionVideo = localFileURL
        self.startChat(for: menu)
    }
}

// 2. Upload and clean up AFTER the session officially connects
func handleSessionConnected() {
    guard let pendingVideoURL = MySessionStateManager.shared.pendingPreSessionVideo else { return }

    // Upload using the standard in-session pipeline
    // then clean up the temporary file
    try? FileManager.default.removeItem(at: pendingVideoURL)
    MySessionStateManager.shared.pendingPreSessionVideo = nil
}

Membaca konfigurasi tindakan smart pra-sesi

SDK mengekspos konfigurasi tindakan smart pra-sesi melalui dua jalur pelengkap. Periksa keduanya untuk menentukan apakah pengambilan pra-sesi diperlukan untuk antrean dan saluran tertentu.

Path A - tingkat antrean (QueueMenu.settings[].sdk.preSessionSmartAction):

public struct QueueMenuSetting: Decodable {
    public let sdk: QueueMenuSDKSetting?
    // ... other fields ...
}

public struct QueueMenuSDKSetting: Decodable {
    public let preSessionSmartAction: Bool?
    // ... other fields ...
}

// Usage - "does any queue-level setting require a pre-session smart action?"
func queueRequiresPreSession(_ menu: QueueMenu) -> Bool {
    return menu.settings?.contains { $0.sdk?.preSessionSmartAction == true } ?? false
}

Jalur B - tingkat channel (VoiceCallChannel.preSessionSmartAction):

// Usage - "does the voice channel specifically require pre-session capture?"
let requiresPreSessionOnVoice =
    menu.channels?.voiceCall?.preSessionSmartAction == true

Gunakan Jalur A untuk memutuskan apakah akan menampilkan penghalang pra-sesi sebelum pengguna memilih channel. Gunakan Jalur B untuk penyempurnaan khusus saluran setelah saluran dipilih (misalnya, hanya meminta sebelum panggilan suara instan).

Tindakan cerdas dalam sesi (diprakarsai agen)

Selama panggilan suara atau chat aktif, agen dapat memilih tombol di dasbornya untuk meminta data dari pengguna (misalnya, "Kirim foto tanda pengenal Anda" atau "Lakukan autentikasi dengan Face ID").

Yang disediakan SDK: Peristiwa real-time yang memberi tahu aplikasi Anda bahwa agen telah meminta jenis tindakan smart tertentu.

Yang Anda bangun: Pemberitahuan dalam chat atau dalam panggilan yang memberi tahu pengguna tentang permintaan, meluncurkan alat bawaan yang sesuai (kamera, galeri foto, kolom teks, atau Face ID), dan meneruskan hasilnya kembali ke SDK.

Contoh penerapan

Di sini, aplikasi Anda memproses peristiwa SDK. Saat mendeteksi permintaan agen, alat ini akan menampilkan pemberitahuan, lalu membuka alat iOS yang sesuai.

// Listen for Smart Action requests from the active SDK session.
//
// `SmartActionType` exposes the following cases: `.photo`, `.video`,
// `.screenshot`, `.text`, `.verification`, `.screenShare`, `.unknown`.
// Use `.verification` (not `.biometric`) for Face ID / Touch ID flows -
// there is no `.biometric` case on the enum.
func handleSmartActionRequest(_ request: SmartActionRequest) {
    switch request.type {
    case .photo:
        promptUserForPhoto(message: "The agent requested a photo.") { capturedImage in
            // Send the image back to the agent using the SDK
            self.sendAttachment(image: capturedImage)
        }

    case .video:
        // Agent-requested video capture. Reuse the same disk-caching pattern
        // recommended for pre-session media - keep the recording on disk and
        // pass the file URL to the SDK rather than holding the raw `Data` in
        // memory.
        promptUserForVideo(message: "The agent requested a video.") { capturedVideoURL in
            self.sendAttachment(videoURL: capturedVideoURL)
        }

    case .screenshot:
        // The SDK exposes `.screenshot` as a distinct request type - the user
        // captures (or selects) a single still image of the current screen.
        // This is **not** the same as the following `.screenShare` case, which starts a
        // live co-browse session.
        promptUserForScreenshot(message: "The agent requested a screenshot.") { capturedImage in
            self.sendAttachment(image: capturedImage)
        }

    case .verification:
        // Use Face ID / Touch ID using LocalAuthentication. The SDK exposes
        // this case as `.verification`; there is no `.biometric` case on
        // `SmartActionType`.
        performAppleBiometricAuth { success in
            self.sendBiometricResult(success: success)
        }

    case .text:
        presentTextInputPrompt(message: "The agent requested text input.") { text in
            self.sendSmartActionText(text)
        }

    case .screenShare:
        // Hand off to the full screen share flow (see Headless Mobile SDK for iOS: Voice, Screen Share, Scheduled Call, and Email).
        // Don't confuse this with `.screenshot` described earlier - `.screenShare` starts a
        // live co-browse session using `CCAIScreenShare`, while `.screenshot`
        // captures a single still frame.
        startScreenShareFlow()

    case .unknown:
        // Future-proof: a smart action type the SDK doesn't recognize.
        // Log and continue - don't block the user.
        print("CCAI: received unknown smart action type")

    @unknown default:
        // Defensive: handle any cases added to `SmartActionType` in future
        // SDK releases.
        break
    }
}

Memberi tahu dan melacak tindakan smart

Gunakan smartActionService untuk mengonfirmasi dan memperbarui tindakan smart saat pengguna melakukan tindakan tersebut.

let router = CommunicationRouter(id: chatId, type: .chat)

// Notify the server that a smart action has been received
do {
    try await CCAI.shared.smartActionService?.notifySmartActionReceived(
        router: router,
        smartActionId: smartActionId
    )
    print("Smart action notification sent successfully")
} catch {
    print("Failed to notify smart action: \(error)")
}

// Update the smart action status as the user completes it
do {
    try await CCAI.shared.smartActionService?.updateSmartActionStatus(
        router: router,
        smartActionId: smartActionId,
        status: .finished
    )
    print("Smart action status updated successfully")
} catch {
    print("Failed to update smart action status: \(error)")
}

Jika tindakan meminta input teks, kumpulkan teks di UI Anda dan kirimkan melalui layanan tindakan smart sebelum menandai tindakan sebagai selesai.

Formulir web

Yang disediakan SDK: API untuk mengambil, menampilkan, dan memvalidasi formulir web yang dipicu oleh agen selama sesi chat.

Yang Anda buat: UI rendering formulir web dan alur pengiriman yang mengemas respons pengguna.

Contoh penerapan

Kode ini mengambil formulir web berdasarkan ID tindakan smart dan ID formulir eksternalnya, lalu memvalidasi respons sebelum pengiriman.

// Fetch a web form - WebFormRequest has no `signature` parameter on iOS
let webFormRequest = WebFormRequest(
    smartActionId: 123,
    externalFormId: "form123"
)

do {
    let webFormResponse = try await CCAI.shared.chatService?.fetchWebForm(webFormRequest)
    if let response = webFormResponse {
        print("Web form received: \(response)")
    }
} catch {
    print("Failed to fetch web form: \(error)")
}

// Validate a web form response
do {
    let isValid = try await CCAI.shared.chatService?.validateWebForm(webFormResponse)
    if isValid == true {
        print("Web form is valid")
    } else {
        print("Web form validation failed")
    }
} catch {
    print("Failed to validate web form: \(error)")
}

Untuk definisi struktur WebFormResponse, FormPayload, dan WebFormData lengkap, lihat Headless Mobile SDK - Referensi API iOS.

Formulir kustom

Yang disediakan SDK: API untuk mengambil definisi formulir yang dapat dikonfigurasi (dengan beberapa jenis pertanyaan) dan mengirimkan jawaban pengguna.

Yang akan Anda bangun: UI formulir dinamis yang merender setiap jenis pertanyaan (seperti kolom teks dan dropdown), memvalidasi input, dan mengumpulkan respons untuk pengiriman.

Contoh penerapan

Kode ini mengambil definisi pertanyaan formulir kustom, lalu mengemas dan mengirimkan jawaban pengguna.

// Retrieve custom form details
do {
    let form = CustomForm(
        id: 123,
        name: nil,
        title: nil,
        subtitle: nil,
        smartActionId: nil,
        image: nil,
        header: nil,
        footer: nil
    )
    let formDetails = try await CCAI.shared.chatService?.getCustomFormDetails(form)
    if let details = formDetails {
        print("Form Title: \(details.title ?? "No title")")
        print("Questions: \(details.questions.count)")
    }
} catch {
    print("Failed to get custom form details: \(error)")
}

// Submit a custom form
let request = SubmitCustomFormRequest(
    smartActionId: 123,
    formResponse: [
        SubmitCustomFormRequest.Answer(questionId: 1, value: "John Doe"),
        SubmitCustomFormRequest.Answer(questionId: 2, value: "john@example.com")
    ]
)

do {
    try await CCAI.shared.chatService?.submitCustomForm(request: request)
    print("Form submitted successfully")
} catch {
    print("Failed to submit form: \(error)")
}

Untuk definisi enum CustomFormDetailsResponse, CustomFormQuestion, CustomFormQuestionOption, dan CustomFormQuestionType lengkap, lihat Headless Mobile SDK - Referensi API iOS.

Lampiran yang dimulai konsumen (chat)

Pengguna tidak perlu menunggu agen bertanya; mereka dapat secara proaktif mengirim gambar dan video selama percakapan. SDK menerapkan batas ukuran file yang ketat dan secara otomatis mencoba kompresi sebelum transmisi.

Batas ukuran lampiran

  • Gambar: ≤ 2 MB

  • Video: ≤ 20 MB

Yang disediakan SDK: Pipeline upload yang aman yang menangani transmisi jaringan dan otomatis mengompresi file untuk memenuhi batas project Google Cloud .

Yang Anda bangun: Tombol klip kertas / lampiran di UI chat Anda, pemilih foto/video, dan balon chat visual yang menampilkan status upload (memuat, terkirim, atau gagal).

Contoh penerapan

Saat pengguna memilih foto atau video dari rol kamera mereka, konversikan ke Data (untuk gambar) atau dapatkan URL file lokal (untuk video), lalu teruskan ke SDK menggunakan sendMessage API yang sama yang digunakan untuk semua pesan keluar (lihat bagian Mengirim pesan di Headless Mobile SDK for iOS: Queues, channels, and chat). SDK menangani kompresi dan upload.

import PhotosUI

// Called when the user picks an image from their photo library
func userDidSelectImage(_ image: UIImage) {
    guard let imageData = image.jpegData(compressionQuality: 0.8) else { return }

    // Show a loading bubble in your custom chat UI
    let messageBubble = myChatUI.addLoadingImageBubble()

    Task {
        do {
            // Wrap the raw data in an UploadableImage
            let uploadableImage = UploadableImage(data: imageData, mimeType: "image/jpeg")

            // Pass to the SDK - compression and upload are handled automatically
            try await CCAI.shared.chatService?.sendMessage(
                .images(images: [uploadableImage], smartAction: nil)
            )
            messageBubble.markAsSent()
        } catch {
            // The SDK returns an error if the file exceeds limits even after compression
            messageBubble.showError("Failed to send: \(error.localizedDescription)")
        }
    }
}

// Called when the user picks a video from their photo library
func userDidSelectVideo(at localURL: URL) {
    let messageBubble = myChatUI.addLoadingVideoBubble()

    Task {
        do {
            let uploadableVideo = UploadableVideo(url: localURL, mimeType: "video/mp4")
            try await CCAI.shared.chatService?.sendMessage(
                .videos(videos: [uploadableVideo], smartAction: nil)
            )
            messageBubble.markAsSent()
        } catch {
            messageBubble.showError("Failed to send: \(error.localizedDescription)")
        }
    }
}

Lampiran yang dimulai agen (chat)

Agen dapat mengirim file kembali kepada pengguna, termasuk gambar, video, klip audio, dan dokumen (PDF, CSV, dll.).

Jenis file yang didukung

Platform project Google Cloud menerima 19 jenis file dalam empat kategori. UI kustom Anda harus menangani setiap kategori dengan baik (pratinjau gambar, pemutar video, pemutar audio, download dokumen).

Kategori Jenis yang didukung
Gambar JPEG, PNG, GIF, dan WebP.
Video MP4, MOV, AVI, WMV, dan WebM.
Audio MP3, WAV, M4A, dan WEBA.
Dokumen PDF, DOC, XLS, PPT, CSV, dan TXT.

Yang disediakan SDK: Payload pesan chat masuk (dikirim menggunakan messagesReceived Combine publisher - lihat bagian Pola reaktif dengan Combine di Headless Mobile SDK for iOS: Post-session and advanced topics yang menyertakan metadata lampiran. Layanan chat juga menyediakan downloadMedia untuk mengambil media yang dikirim agen secara aman.)

Yang Anda bangun: UI untuk merender lampiran ini di feed chat. Aplikasi Anda memutuskan apakah akan menampilkan pratinjau gambar, thumbnail video, kontrol pemutaran audio, atau tombol download dokumen.

Contoh penerapan

Berlangganan ke pesan masuk menggunakan messagesReceived. Saat pesan baru mencakup metadata media, panggil downloadMedia sebelum merender atau membuka file.

downloadMedia menampilkan DownloadMediaResponse { data: Data, fileName: String? } — byte yang didownload sepenuhnya ditambah nama file tampilan opsional. SDK tidak menyimpan cache download. Jika UI Anda men-scroll kembali ke balon lama atau masuk kembali ke tampilan chat, aplikasi Anda bertanggung jawab untuk meng-cache gambar yang didekode atau mempertahankan byte; memanggil downloadMedia lagi akan memicu pengambilan jaringan lain.

import Combine

private var cancellables = Set<AnyCancellable>()

CCAI.shared.chatService?.messagesReceived
    .receive(on: DispatchQueue.main)
    .sink { [weak self] messages in
        for message in messages {
            self?.renderIncomingMessage(message)
        }
    }
    .store(in: &cancellables)

func renderIncomingMessage(_ message: ChatMessage) {
    guard let media = message.media else {
        myChatUI.insertTextBubble(text: message.text)
        return
    }

    Task {
        do {
            // `downloadMedia` returns the raw bytes plus an optional filename.
            // First arg is unlabeled.
            let response = try await CCAI.shared.chatService?.downloadMedia(
                media.id,
                mediaType: media.type
            )
            guard let response else { return }

            await MainActor.run {
                switch media.type {
                case .photo:
                    // Decode in-memory - no disk write needed.
                    if let image = UIImage(data: response.data) {
                        myChatUI.insertImageBubble(
                            image: image,
                            fileName: response.fileName
                        )
                    }
                case .video, .audio, .document:
                    // Larger media usually needs an on-disk URL for AVPlayer
                    // or QLPreviewController. Write to the temp directory
                    // yourself and hand the resulting URL to your UI helper.
                    let url = FileManager.default
                        .temporaryDirectory
                        .appendingPathComponent(response.fileName ?? "attachment")
                    try? response.data.write(to: url)
                    myChatUI.insertAttachmentBubble(
                        fileURL: url,
                        mediaType: media.type
                    )
                }
            }
        } catch {
            await MainActor.run {
                myChatUI.insertAttachmentErrorBubble(fileName: message.media?.name)
            }
        }
    }
}

Untuk mengetahui jenis metadata media dan pesan chat yang tepat, lihat Headless Mobile SDK — Referensi API iOS.

Pengalihan (di luar jam kerja dan kelebihan kapasitas)

Pengalihan adalah fitur penting pusat kontak yang mengalihkan pengguna saat tim dukungan Anda tidak tersedia. Hal ini biasanya terjadi dalam dua skenario:

  • Di luar jam kerja: pengguna mencoba menghubungi dukungan di luar jam kerja yang Anda konfigurasi.

  • Kapasitas berlebih: antrean terbuka, tetapi waktu tunggu melebihi batas maksimum yang ditetapkan oleh admin Anda.

Dalam arsitektur headless, SDK tidak otomatis memblokir pengguna atau memunculkan layar error. Sebagai gantinya, aplikasi ini secara diam-diam meneruskan status pengalihan dan opsi penggantian yang dikonfigurasi admin ke aplikasi Anda. Aplikasi Anda harus memeriksa status ini sebelum mencoba memulai sesi.

Menangani status pengalihan

Yang disediakan SDK: deflectionFrom: [QueueMenuDeflection]? pada QueueMenu yang mencantumkan aturan pengalihan masuk yang merutekan antrean lain ke antrean ini. Setiap QueueMenuDeflection hanya memiliki dua kolom:

  • deflectionType: DeflectionType? - kategori pengalihan (misalnya, di luar jam kerja atau kelebihan kapasitas).

  • menuId: Int? - ID antrean sumber yang dialihkan ke antrean ini.

QueueMenuDeflection tidak membawa pesan tampilan atau label yang dapat dibaca manusia. Untuk salinan yang ditampilkan kepada pengguna, telusuri sendiri array settings (atau kembali ke string yang dikonfigurasi admin Anda sendiri). Untuk nama tampilan antrean sumber yang di-resolve, gunakan ekstensi findMenu(byId:) pada [QueueMenu] untuk mencarinya di struktur menu yang sudah diambil.

Yang Anda bangun: Logika untuk memeriksa status pengalihan ini sebelum menempatkan pengguna dalam antrean, dan UI kustom (seperti pemberitahuan layar penuh atau banner) yang menampilkan pesan yang sesuai dan tombol perutean alternatif.

Contoh penerapan

Kode berikut mencegat upaya pengguna untuk memulai percakapan. SDK akan memeriksa metadata pengalihan di QueueMenu dan, jika ada aturan yang aktif, SDK akan menyelesaikan pesan di luar jam kerja dari setelan antrean dan menampilkan layar pengalihan.

// Helper - pull the first after-hours message text out of the queue's settings
func afterHoursMessageText(for menu: QueueMenu) -> String? {
    return menu.settings?
        .compactMap { $0.afterHours?.message?.text }
        .first
}

// Called when the user taps "Start Chat" in your app
func attemptToStartChat(for menu: QueueMenu) {
    // 1. Check if any deflection rules route into this queue
    if let deflections = menu.deflectionFrom, !deflections.isEmpty {
        let message = afterHoursMessageText(for: menu)
            ?? "Support is currently unavailable."
        showDeflectionScreen(message: message, deflections: deflections)
    } else {
        // No deflection rules apply. Safe to start the chat.
        Task {
            await startChat(for: menu)
        }
    }
}

Opsi pembelokan render

Saat aturan pengalihan aktif, admin Anda kemungkinan akan mengonfigurasi cara alternatif bagi pengguna untuk mendapatkan bantuan - biasanya dengan mengarahkan ke antrean lain (yang dapat Anda selesaikan menggunakan menuId) atau dengan menampilkan teks di luar jam kerja antrean saat ini.

Yang disediakan SDK: Daftar entri QueueMenuDeflection di deflectionFrom, masing-masing dengan deflectionType dan menuId.

Yang Anda bangun: Menu dinamis yang mengulang entri ini, menyelesaikan setiap menuId terhadap struktur menu yang sudah diambil untuk mendapatkan nama tampilan, dan membuat tombol yang sesuai.

Contoh penerapan

Kode ini mengambil entri pembelokan dan membangun layar secara dinamis. Objek ini menyelesaikan nama antrean sumber menggunakan ekstensi findMenu(byId:) yang disediakan SDK di [QueueMenu], dan kembali ke nama deflectionType jika nama antrean tidak tersedia.

func showDeflectionScreen(
    message: String,
    deflections: [QueueMenuDeflection],
    cachedRootMenus: [QueueMenu]
) {
    // 1. Update your UI with the resolved message (or your fallback)
    deflectionTitleLabel.text = message

    // 2. Loop through the incoming deflection rules and generate buttons
    for deflection in deflections {
        let sourceMenu = deflection.menuId.flatMap { cachedRootMenus.findMenu(byId: $0) }
        let label = sourceMenu?.name
            ?? deflection.deflectionType.map { String(describing: $0) }
            ?? "Alternative option"

        let button = createButton(title: label) {
            self.handleDeflectionAction(deflection)
        }
        menuStackView.addArrangedSubview(button)
    }

    // 3. Present the compiled screen to the user
    present(deflectionViewController, animated: true)
}

deflectionFrom adalah daftar aturan pengalihan yang dirutekan ke menu ini - menuId setiap entri mengidentifikasi antrean sumber yang dialihkan ke antrean saat ini. Aplikasi Anda memutuskan cara menampilkannya: beberapa integrasi menampilkan tujuan antrean sebagai "di sinilah kami akan mengirim Anda", sementara yang lain menggunakan keberadaan aturan apa pun sebagai gerbang untuk menampilkan layar "coba lagi nanti" generik.