Ce document explique comment intégrer et personnaliser le SDK Headless Mobile dans votre application Android. Il couvre tout ce qui ajoute des informations riches et structurées à vos sessions d'assistance : actions intelligentes avant session pour la capture de contexte, actions intelligentes en session déclenchées par les agents (y compris la vérification biométrique avec LocalAuthentication), formulaires Web et personnalisés, pièces jointes initiées par les clients et les agents, et gestion de la redirection pour les scénarios hors horaires d'ouverture et de capacité maximale.
Configurer les actions intelligentes et les pièces jointes
Les actions intelligentes permettent aux agents et aux consommateurs d'échanger des informations riches et structurées, telles que des photos, des vidéos, des extraits de texte et la validation biométrique (Face ID et Touch ID).
Dans l'architecture headless, le SDK agit strictement en tant que couche de transport sécurisée. Il vous indique quand une action est requise ou demandée, et il transfère les données de manière sécurisée vers la plate-forme du projet Google Cloud . Comme vous êtes propriétaire de l'interface utilisateur, votre application est entièrement responsable du dessin des écrans de l'appareil photo, des sélecteurs de photos, des zones de texte et du déclenchement des invites Face ID d'Apple.
Actions intelligentes de présession
Les actions avant session permettent de recueillir du contexte (comme un numéro de compte ou une vidéo d'un produit défectueux) avant que l'utilisateur ne rejoigne la file d'attente, ce qui réduit considérablement le temps de traitement des agents.
Ce que fournit le SDK : les règles et les exigences pour une file d'attente spécifique (par exemple, si la validation biométrique, l'importation de photos ou la saisie de texte sont facultatives ou obligatoires avant de rejoindre la file d'attente).
Ce que vous allez créer : les écrans de l'UI de pré-session (invites de l'appareil photo, de saisie de texte et de Face ID) qui s'affichent entre le moment où l'utilisateur appuie sur une file d'attente et celui où il entre dans la salle d'attente, ainsi que la logique de mise en cache sur disque pour conserver les contenus multimédias de manière sécurisée jusqu'à ce que la session se connecte.
Exemple de mise en œuvre
Ce code vérifie la configuration du SDK pour déterminer si la file d'attente choisie présente des exigences de pré-session. Il montre comment gérer une exigence vidéo en conservant une référence d'URL de fichier sur le disque au lieu de conserver la vidéo en mémoire.
// 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
}
Lecture de la configuration des actions intelligentes de présession
Le SDK expose la configuration des actions intelligentes de présession via deux chemins complémentaires. Vérifiez les deux pour déterminer si la capture avant session est requise pour une file d'attente et un canal donnés.
Chemin A : au niveau de la file d'attente (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
}
Chemin B : au niveau de la chaîne (VoiceCallChannel.preSessionSmartAction) :
// Usage - "does the voice channel specifically require pre-session capture?"
let requiresPreSessionOnVoice =
menu.channels?.voiceCall?.preSessionSmartAction == true
Utilisez le chemin A pour déterminer s'il faut afficher une porte de pré-session avant que l'utilisateur choisisse une chaîne. Utilisez le chemin B pour affiner les canaux après en avoir sélectionné un (par exemple, en n'invitant l'utilisateur qu'avant un appel vocal instantané).
Actions intelligentes en cours de session (initiées par l'agent)
Lors d'une conversation active par chat ou par appel vocal, un agent peut sélectionner un bouton sur son tableau de bord pour demander des données à l'utilisateur (par exemple, "Envoyez une photo de votre pièce d'identité" ou "Authentifiez-vous avec Face ID").
Ce que fournit le SDK : des événements en temps réel qui alertent votre application lorsque l'agent a demandé un type spécifique d'action intelligente.
Ce que vous allez créer : une alerte dans le chat ou lors d'un appel informant l'utilisateur de la demande, lançant l'outil intégré approprié (appareil photo, bibliothèque de photos, champ de texte ou Face ID) et renvoyant le résultat au SDK.
Exemple de mise en œuvre
Ici, votre application écoute les événements du SDK. Lorsqu'il détecte une demande d'agent, il affiche une alerte, puis ouvre l'outil iOS approprié.
// 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
}
}
Notifications et suivi des actions intelligentes
Utilisez smartActionService pour confirmer et mettre à jour les actions intelligentes au fur et à mesure que l'utilisateur les effectue.
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)")
}
Si l'action demande une saisie de texte, collectez le texte dans votre UI et envoyez-le via le service d'actions intelligentes avant de marquer l'action comme terminée.
Formulaires Web
Ce que fournit le SDK : des API permettant de récupérer, d'afficher et de valider les formulaires Web déclenchés par les agents lors d'une session de chat.
Ce que vous allez créer : l'UI de rendu du formulaire Web et le flux d'envoi qui regroupe les réponses de l'utilisateur.
Exemple de mise en œuvre
Ce code récupère un formulaire Web par son ID d'action intelligente et son ID de formulaire externe, puis valide la réponse avant l'envoi.
// 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)")
}
Pour obtenir les définitions complètes des structures WebFormResponse, FormPayload et WebFormData, consultez la documentation de référence de l'API du SDK Mobile sans interface utilisateur pour iOS.
Formulaires personnalisés
Ce que fournit le SDK : des API permettant de récupérer des définitions de formulaires configurables (avec plusieurs types de questions) et d'envoyer les réponses des utilisateurs.
Ce que vous allez créer : une UI de formulaire dynamique qui affiche chaque type de question (comme les champs de texte et les menus déroulants), valide les entrées et collecte les réponses à envoyer.
Exemple de mise en œuvre
Ce code récupère les définitions des questions d'un formulaire personnalisé, puis regroupe et envoie les réponses de l'utilisateur.
// 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)")
}
Pour obtenir la définition complète des énumérations CustomFormDetailsResponse, CustomFormQuestion,
CustomFormQuestionOption et CustomFormQuestionType, consultez la documentation de référence de l'API du SDK Headless Mobile pour iOS.
Pièces jointes initiées par le consommateur (chat)
Les utilisateurs n'ont pas besoin d'attendre qu'un agent le leur demande. Ils peuvent envoyer des images et des vidéos de manière proactive pendant une discussion. Le SDK applique des limites strictes à la taille des fichiers et tente automatiquement de les compresser avant de les transmettre.
Limites de taille des pièces jointes
Images : ≤ 2 Mo
Vidéos : ≤ 20 Mo
Ce que fournit le SDK : un pipeline d'importation sécurisé qui gère la transmission réseau et compresse automatiquement les fichiers pour respecter les limites du projet Google Cloud .
Ce que vous allez créer : le bouton en forme de trombone / pièce jointe dans l'UI de votre chat, le sélecteur de photos/vidéos et la bulle de chat visuelle indiquant l'état de l'importation (en cours, envoyée ou échec).
Exemple de mise en œuvre
Lorsqu'un utilisateur sélectionne une photo ou une vidéo dans sa galerie, convertissez-la au format Data (pour les images) ou obtenez l'URL du fichier local (pour les vidéos), puis transmettez-la au SDK à l'aide de la même API sendMessage que celle utilisée pour tous les messages sortants (consultez la section Envoi de messages dans SDK mobile sans interface utilisateur pour iOS : files d'attente, canaux et chat). Le SDK gère la compression et l'importation.
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)")
}
}
}
Pièces jointes initiées par l'agent (chat)
Les agents peuvent renvoyer des fichiers à l'utilisateur, y compris des images, des vidéos, des extraits audio et des documents (PDF, CSV, etc.).
Types de fichiers compatibles
La plate-forme de projet Google Cloud accepte 19 types de fichiers répartis dans quatre catégories. Votre UI personnalisée doit gérer chaque catégorie de manière appropriée (aperçu d'image, lecteur vidéo, lecteur audio, téléchargement de document).
| Catégorie | Types compatibles |
|---|---|
| Images | JPEG, PNG, GIF et WebP |
| Vidéo | MP4, MOV, AVI, WMV et WebM. |
| Audio | MP3, WAV, M4A et WEBA. |
| Documents | PDF, DOC, XLS, PPT, CSV et TXT. |
Ce que fournit le SDK : charges utiles des messages de chat entrants (fournies à l'aide de l'éditeur messagesReceived Combine – consultez la section Modèles réactifs avec Combine dans SDK mobile sans interface utilisateur pour iOS : sujets avancés et post-session) qui incluent les métadonnées des pièces jointes. Le service de chat fournit également downloadMedia pour récupérer les contenus multimédias envoyés par l'agent de manière sécurisée.
Ce que vous allez créer : l'UI pour afficher ces pièces jointes dans le flux de chat. Votre application décide d'afficher ou non des aperçus d'images, des miniatures de vidéos, des commandes de lecture audio ou des boutons de téléchargement de documents.
Exemple de mise en œuvre
Abonnez-vous aux messages entrants à l'aide de messagesReceived. Lorsqu'un nouveau message inclut des métadonnées multimédias, appelez downloadMedia avant de rendre ou d'ouvrir le fichier.
downloadMedia renvoie DownloadMediaResponse { data: Data, fileName: String?
}, c'est-à-dire les octets entièrement téléchargés, ainsi qu'un nom de fichier à afficher (facultatif). Le SDK ne met pas en cache les téléchargements. Si votre UI revient à une ancienne bulle ou réintègre la vue de chat, votre application est responsable de la mise en cache de l'image décodée ou de la persistance des octets. L'appel de downloadMedia déclenche une autre récupération réseau.
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)
}
}
}
}
Pour connaître les types exacts de métadonnées de messages de chat et de contenus multimédias, consultez la documentation de référence de l'API Headless Mobile SDK pour iOS.
Déviation (hors horaires d'ouverture et pour dépassement de capacité)
La redirection est une fonctionnalité essentielle des centres de contact. Elle redirige les utilisateurs lorsque votre équipe d'assistance n'est pas disponible. Cela se produit généralement dans deux cas de figure :
En dehors des heures d'ouverture : l'utilisateur tente de contacter l'assistance en dehors de vos heures d'ouverture configurées.
Capacité dépassée : la file d'attente est ouverte, mais le temps d'attente dépasse le seuil maximal défini par vos administrateurs.
Dans une architecture headless, le SDK ne bloque pas automatiquement l'utilisateur ni n'affiche un écran d'erreur. Au lieu de cela, il transmet discrètement l'état de la redirection et les options de remplacement configurées par l'administrateur à votre application. Votre application doit vérifier cet état avant de tenter de démarrer une session.
Gérer les états de déviation
Ce que fournit le SDK : un deflectionFrom: [QueueMenuDeflection]? sur QueueMenu qui liste les règles de déviation entrantes qui redirigent d'autres files d'attente vers celle-ci. Chaque QueueMenuDeflection ne comporte que deux champs :
deflectionType: DeflectionType?: catégorie de la déviation (par exemple, hors des heures de travail ou en dépassement de capacité).menuId: Int?: ID de la file d'attente source qui redirige les demandes vers celle-ci.
QueueMenuDeflection ne comporte pas de message à afficher ni de libellé lisible par un humain.
Pour les textes destinés aux utilisateurs, parcourez vous-même le tableau settings (ou revenez à vos propres chaînes configurées par l'administrateur). Pour le nom à afficher de la file d'attente source résolue, utilisez l'extension findMenu(byId:) sur [QueueMenu] pour la rechercher dans l'arborescence de menu que vous avez déjà récupérée.
Ce que vous allez créer : la logique permettant de vérifier ces états d'évitement avant de placer un utilisateur dans une file d'attente, ainsi que l'UI personnalisée (par exemple, une alerte en plein écran ou une bannière) qui affiche le message approprié et les boutons de redirection alternatifs.
Exemple de mise en œuvre
Le code suivant intercepte la tentative d'un utilisateur de démarrer une discussion. Il vérifie les métadonnées de déviation du SDK sur QueueMenu et, si une règle est active, résout le message hors horaires d'ouverture à partir des paramètres de la file d'attente et présente un écran de déviation.
// 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)
}
}
}
Options de redirection du rendu
Lorsqu'une règle de déviation est active, vos administrateurs configurent probablement d'autres moyens pour l'utilisateur d'obtenir de l'aide. Il s'agit généralement de l'orienter vers une autre file d'attente (que vous pouvez résoudre à l'aide de menuId) ou d'afficher le texte de la file d'attente actuelle en dehors des heures d'ouverture.
Ce que fournit le SDK : liste des entrées QueueMenuDeflection sur deflectionFrom, chacune avec un deflectionType et un menuId.
Ce que vous allez créer : un menu dynamique qui parcourt ces entrées, résout chaque menuId par rapport à l'arborescence de menu déjà récupérée pour obtenir un nom à afficher et génère les boutons appropriés.
Exemple de mise en œuvre
Ce code prend les entrées de déviation et crée un écran de manière dynamique. Il résout le nom de la file d'attente source à l'aide de l'extension findMenu(byId:) fournie par le SDK sur [QueueMenu], en revenant au nom deflectionType lorsqu'un nom de file d'attente n'est pas disponible.
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 correspond à la liste des règles de redirection qui redirigent vers ce menu. Le menuId de chaque entrée identifie une file d'attente source qui redirige vers celle en cours. Votre application décide de la manière de les présenter : certaines intégrations présentent la file d'attente de destination comme "voici où nous vous enverrons à la place", tandis que d'autres utilisent la présence d'une règle comme porte d'entrée pour afficher un écran générique "réessayez plus tard".