Questo documento spiega come integrare e personalizzare l'SDK Headless Mobile nella tua app per Android. Copre tutto ciò che aggiunge informazioni strutturate e avanzate alle tue sessioni di assistenza: azioni rapide pre-sessione per l'acquisizione del contesto, azioni rapide in sessione attivate dagli agenti (inclusa la verifica biometrica con LocalAuthentication), moduli web e personalizzati, allegati avviati da consumatori e agenti e gestione della deviazione per scenari dopo l'orario di lavoro e con capacità eccessiva.
Configurare le azioni intelligenti e gli allegati
Le azioni intelligenti consentono ad agenti e consumatori di scambiarsi informazioni ricche e strutturate come foto, video, snippet di testo e verifica biometrica (Face ID e Touch ID).
Nell'architettura headless, l'SDK funge esclusivamente da livello di trasporto sicuro. Ti informa quando è richiesta o necessaria un'azione e trasferisce in modo sicuro i dati alla piattaforma del progetto Google Cloud . Poiché possiedi l'interfaccia utente, la tua app è completamente responsabile del disegno delle schermate della fotocamera, dei selettori di foto, delle caselle di testo e dell'attivazione dei prompt di Face ID di Apple.
Azioni rapide pre-sessione
Le azioni pre-sessione raccolgono il contesto (ad esempio un numero di conto bancario o un video di un prodotto rotto) prima che l'utente entri in coda, riducendo significativamente il tempo di gestione dell'agente.
Cosa fornisce l'SDK: le regole e i requisiti per una coda specifica (ad esempio, se la verifica biometrica, il caricamento di foto o l'inserimento di testo sono facoltativi o obbligatori prima di partecipare).
Cosa crei: le schermate della UI pre-sessione (fotocamera, inserimento di testo e prompt di Face ID) che vengono visualizzate tra il momento in cui l'utente tocca una coda e quello in cui entra nella sala d'attesa, nonché la logica di memorizzazione nella cache su disco per conservare in modo sicuro i contenuti multimediali fino a quando la sessione non si connette.
Esempio di implementazione
Questo codice controlla la configurazione dell'SDK per verificare se la coda scelta ha requisiti pre-sessione. Mostra come gestire un requisito video mantenendo un riferimento all'URL di un file su disco anziché memorizzare il video.
// 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
}
Lettura della configurazione dell'azione intelligente pre-sessione
L'SDK espone la configurazione delle azioni intelligenti pre-sessione tramite due percorsi complementari. Controlla entrambi per determinare se l'acquisizione pre-sessione è necessaria per una determinata coda e un determinato canale.
Percorso A - a livello di coda (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
}
Percorso B - a livello di canale (VoiceCallChannel.preSessionSmartAction):
// Usage - "does the voice channel specifically require pre-session capture?"
let requiresPreSessionOnVoice =
menu.channels?.voiceCall?.preSessionSmartAction == true
Utilizza Percorso A per decidere se mostrare un gate pre-sessione prima che l'utente scelga un canale. Utilizza il percorso B per perfezionamenti specifici per canale dopo la selezione di un canale (ad esempio, la richiesta solo prima di una chiamata vocale istantanea).
Azioni rapide in sessione (avviate dall'agente)
Durante una chat o una chiamata vocale attiva, un agente può selezionare un pulsante nella dashboard per richiedere dati all'utente (ad esempio "Invia una foto del tuo documento di identità" o "Autenticati con Face ID").
Cosa fornisce l'SDK: eventi in tempo reale che avvisano l'app che l'agente ha richiesto un tipo specifico di azione intelligente.
Cosa crei: un avviso in chat o in chiamata che notifica all'utente la richiesta, avvia lo strumento integrato appropriato (fotocamera, raccolta fotografica, campo di testo o Face ID) e restituisce il risultato all'SDK.
Esempio di implementazione
Qui, la tua app ascolta gli eventi SDK. Quando rileva una richiesta dell'agente, mostra un avviso e poi apre lo strumento iOS appropriato.
// 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
}
}
Notifiche e monitoraggio delle azioni rapide
Utilizza smartActionService per confermare e aggiornare le azioni intelligenti man mano che l'utente
le completa.
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)")
}
Se l'azione richiede l'inserimento di testo, raccogli il testo nella tua UI e invialo tramite il servizio di azioni intelligenti prima di contrassegnare l'azione come completata.
Moduli web
Cosa fornisce l'SDK: API per recuperare, visualizzare e convalidare i moduli web attivati dagli agenti durante una sessione di chat.
Cosa crei: la UI di rendering del modulo web e il flusso di invio che raggruppa le risposte dell'utente.
Esempio di implementazione
Questo codice recupera un modulo web in base al suo ID azione intelligente e all'ID modulo esterno, quindi convalida la risposta prima dell'invio.
// 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)")
}
Per le definizioni complete delle struct WebFormResponse, FormPayload e WebFormData,
consulta il riferimento API dell'SDK mobile headless per iOS.
Moduli personalizzati
Cosa fornisce l'SDK: API per recuperare definizioni di moduli configurabili (con più tipi di domande) e inviare le risposte dell'utente.
Cosa crei: un'interfaccia utente del modulo dinamica che esegue il rendering di ogni tipo di domanda (ad esempio campi di testo ed elenchi a discesa), convalida l'input e raccoglie le risposte per l'invio.
Esempio di implementazione
Questo codice recupera le definizioni delle domande di un modulo personalizzato, quindi impacchetta e invia le risposte dell'utente.
// 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)")
}
Per le definizioni complete degli enum CustomFormDetailsResponse, CustomFormQuestion,
CustomFormQuestionOption e CustomFormQuestionType, consulta
il riferimento API dell'SDK mobile headless per iOS.
Allegati avviati dai consumatori (chat)
Gli utenti non devono aspettare che un agente lo chieda, ma possono inviare in modo proattivo immagini e video durante una chat. L'SDK applica limiti rigorosi alle dimensioni dei file e tenta automaticamente la compressione prima della trasmissione.
Limiti di dimensione degli allegati
Immagini: ≤ 2 MB
Video: ≤ 20 MB
Cosa fornisce l'SDK: una pipeline di caricamento sicura che gestisce la trasmissione di rete e comprime automaticamente i file per rispettare i limiti del progetto Google Cloud .
Cosa crei: il pulsante a forma di graffetta / allegato nell'interfaccia utente della chat, il selettore di foto/video e la bolla di chat visiva che mostra lo stato del caricamento (caricamento, invio o errore).
Esempio di implementazione
Quando un utente seleziona una foto o un video dal rullino, convertilo in
Data (per le immagini) o recupera l'URL del file locale (per i video), quindi passalo all'SDK utilizzando la stessa API sendMessage utilizzata per tutti i messaggi in uscita (vedi la sezione
Invio di messaggi in SDK headless per dispositivi mobili per iOS: code, canali e chat). L'SDK gestisce la compressione e il caricamento.
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)")
}
}
}
Allegati avviati dall'agente (chat)
Gli agenti possono inviare file all'utente, tra cui immagini, video, clip audio e documenti (PDF, CSV e così via).
Tipi di file supportati
La piattaforma Google Cloud del progetto accetta 19 tipi di file in quattro categorie. La tua UI personalizzata deve gestire ogni categoria in modo appropriato (anteprima dell'immagine, video player, audio player, download di documenti).
| Categoria | Tipi supportati |
|---|---|
| Immagini | JPEG, PNG, GIF e WebP. |
| Video | MP4, MOV, AVI, WMV e WebM. |
| Audio | MP3, WAV, M4A e WEBA. |
| Documenti | PDF, DOC, XLS, PPT, CSV e TXT. |
Cosa fornisce l'SDK: payload dei messaggi di chat in arrivo (forniti utilizzando
messagesReceived Combine publisher: consulta la sezione Reactive patterns with Combine in
Headless Mobile SDK for iOS: Post-session and advanced topics
che include i metadati degli allegati. Il servizio di chat fornisce anche downloadMedia
per recuperare in modo sicuro i contenuti multimediali inviati dall'agente.
Cosa crei: la UI per il rendering di questi allegati nel feed della chat. La tua app decide se mostrare anteprime di immagini, miniature di video, controlli di riproduzione audio o pulsanti di download di documenti.
Esempio di implementazione
Iscriviti ai messaggi in arrivo utilizzando messagesReceived. Quando un nuovo messaggio
include metadati multimediali, chiama downloadMedia prima di eseguire il rendering o aprire il
file.
downloadMedia restituisce DownloadMediaResponse { data: Data, fileName: String?
}: i byte scaricati completamente più un nome file visualizzato facoltativo. L'SDK
non memorizza nella cache i download. Se la UI scorre di nuovo a una bolla precedente o rientra
nella visualizzazione della chat, la tua app è responsabile della memorizzazione nella cache dell'immagine decodificata o
della persistenza dei byte; la chiamata di downloadMedia attiva un altro recupero
di rete.
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)
}
}
}
}
Per i tipi esatti di metadati di messaggi chat e contenuti multimediali, consulta il Riferimento API dell'SDK Headless Mobile per iOS.
Deviazione (dopo la chiusura e in caso di capacità eccessiva)
La deviazione è una funzionalità fondamentale del contact center che reindirizza gli utenti quando il tuo team di assistenza non è disponibile. Di solito, questo accade in due scenari:
Al di fuori dell'orario di apertura: l'utente tenta di contattare l'assistenza al di fuori dell'orario di apertura configurato.
Capacità eccessiva: la coda è aperta, ma il tempo di attesa supera la soglia massima impostata dagli amministratori.
In un'architettura headless, l'SDK non blocca automaticamente l'utente né visualizza una schermata di errore. Invece, passa in modo invisibile lo stato di deviazione e le opzioni di fallback configurate dall'amministratore alla tua app. La tua app deve controllare questo stato prima di tentare di avviare una sessione.
Gestire gli stati di deviazione
Cosa fornisce l'SDK: un deflectionFrom: [QueueMenuDeflection]? su
QueueMenu che elenca le regole di deviazione in entrata che indirizzano altre code
a questa. Ogni QueueMenuDeflection contiene solo due campi:
deflectionType: DeflectionType?: la categoria di deviazione (ad esempio, fuori orario o capacità eccessiva).menuId: Int?: l'ID della coda di origine che viene deviata in questa.
QueueMenuDeflection non contiene un messaggio visualizzato o un'etichetta leggibile.
Per il testo rivolto agli utenti, esamina l'array settings (o ripristina le stringhe configurate dall'amministratore). Per il nome visualizzato della coda dell'origine risolta, utilizza
l'estensione findMenu(byId:) su [QueueMenu] per cercarlo nell'albero
del menu già recuperato.
Cosa crei: la logica per verificare questi stati di deviazione prima di inserire un utente in una coda e la UI personalizzata (ad esempio un avviso a schermo intero o un banner) che mostra il messaggio appropriato e i pulsanti di routing alternativi.
Esempio di implementazione
Il seguente codice intercetta il tentativo di un utente di avviare una chat. Controlla i
metadati di deviazione dell'SDK su QueueMenu e, se una regola è attiva, risolve
il messaggio al di fuori dell'orario di lavoro dalle impostazioni della coda e presenta una schermata di deviazione.
// 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)
}
}
}
Opzioni di deviazione del rendering
Quando una regola di deviazione è attiva, gli amministratori configureranno probabilmente modi alternativi per l'utente di ricevere assistenza, in genere indirizzandolo a un'altra coda (che puoi risolvere utilizzando menuId) o visualizzando il testo della coda attuale al di fuori dell'orario di lavoro.
Cosa fornisce l'SDK: l'elenco delle voci QueueMenuDeflection su
deflectionFrom, ciascuna con un deflectionType e un menuId.
Cosa crei: un menu dinamico che scorre queste voci, risolve
ogni menuId rispetto alla struttura del menu già recuperata per ottenere un nome visualizzato e
genera i pulsanti appropriati.
Esempio di implementazione
Questo codice prende le voci di deviazione e crea dinamicamente una schermata. Risolve il nome della coda di origine utilizzando l'estensione findMenu(byId:) fornita dall'SDK su [QueueMenu], per poi ripristinare il nome deflectionType quando un nome di coda non è disponibile.
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 è l'elenco delle regole di deviazione che indirizzano a questo menu. menuId di ogni voce identifica una coda di origine che devia alla coda corrente. La tua app decide come presentarli: alcune integrazioni presentano
la coda di destinazione come "ecco dove ti invieremo invece", mentre altre utilizzano
la presenza di qualsiasi regola come porta per mostrare una schermata generica "riprova più tardi".