Ce document explique comment intégrer et personnaliser le SDK Headless Mobile dans votre application Android. Il couvre les appels vocaux via CCAICall.
Appels vocaux
Le SDK Headless Mobile pour iOS permet de passer des appels vocaux grâce au module CCAICall. Votre application possède l'UI d'appel personnalisée, tandis que le SDK gère la connexion d'appel, l'intégration CallKit, la gestion des notifications push VoIP et les événements du cycle de vie des appels.
Ce que fournit le SDK : des API de service d'appel pour lancer des appels instantanés, démarrer la messagerie vocale, gérer les appels entrants et observer l'état des appels.
Ce que vous allez créer : l'expérience d'appel visuelle, y compris le point d'entrée avant l'appel, l'invite de consentement à l'enregistrement, les états de sonnerie ou d'attente, les commandes en cours d'appel et toute navigation après l'appel.
Initialiser le module d'appel
Initialisez le module d'appel après avoir initialisé le SDK principal :
import CCAIKit
import CCAICall
try CCAI.shared.initialize(options: options)
CCAI.shared.initializeCall(CallOptions())
Inspecter les capacités de VoiceCallChannel
Avant de proposer un appel instantané, inspectez la structure VoiceCallChannel de la file d'attente pour décider quels points d'entrée exposer (appel instantané, renvoi vers la messagerie vocale, redirection au niveau du canal) et si le consentement à l'enregistrement est requis.
Champs VoiceCallChannel clés
instantEnabled: Bool?: indique si un appel vocal en direct (instantané) est autorisé pour cette file d'attente. Traitezniloufalsecomme un état"don't offer an instant call button". Contrairement àvoiceCall != nil, qui vous indique uniquement si la file d'attente comporte un canal vocal.preSessionSmartAction: Bool?: indique si des actions intelligentes de présession sont requises sur ce canal spécifique avant de démarrer un appel. Pour connaître le chemin complémentaire au niveau de la file d'attente, consultez SDK mobile headless pour iOS : actions intelligentes, pièces jointes et redirection.scheduleEnabled: Bool?: indique si les appels planifiés sont disponibles. Pour connaître le chemin complémentaire au niveau de la file d'attente, consultez Appels programmés.recordingOption: RecordingOption?: modèle de consentement pour l'enregistrement des appels (voir Consentement pour l'enregistrement). Distinct deRecordingPermission.notAsked, qui est spécifique à la planification.voicemailReason: String?: renseigné lorsque le canal est configuré pour rediriger vers la messagerie vocale.phoneNumber: String?: numéro de secours RTCP configuré pour la redirection ou la messagerie vocale.scheduleDeflectionType: String?/deflected: Bool?/deflectedReason: String?: métadonnées de déviation au niveau du canal. Lorsquedeflected == true, affichez le messagedeflectedReasonconfiguré par l'administrateur et proposez la solution de repli configurée (par exemple, un numéro de téléphone à composer ou un point d'entrée d'appel planifié) au lieu de tenter un appel instantané. Consultez Déviation (hors horaires d'ouverture et pour dépassement de capacité) pour savoir comment gérer la déviation au niveau de la file d'attente.
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)
}
}
Autorisation d'enregistrement
Ce que fournit le SDK : un champ recordingOption: RecordingOption? sur VoiceCallChannel qui décrit le modèle de consentement pour l'enregistrement des appels configuré par les administrateurs dans le portail.
Ce que vous allez créer : l'invite de consentement (lorsque .askUser) et la logique de branchement qui respecte le choix de l'administrateur.
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)
}
}
}
Démarrer un appel instantané
Avant de démarrer un appel instantané :
Inspectez le
VoiceCallChannelde la file d'attente sélectionnée.Vérifiez que les appels instantanés sont activés et qu'ils ne sont pas redirigés.
Gérez l'autorisation d'enregistrement en fonction des
recordingOptionde la file d'attente.Demandez l'autorisation d'accéder au micro.
Appelez le
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)
}
}
Observer l'état de l'appel
Abonnez-vous aux événements du service d'appel avant de démarrer ou d'accepter un appel :
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)
État du fournisseur et état du serveur
stateChanged et callReceived.status sont des signaux indépendants. Lisez-les comme des colonnes, et non comme des lignes. Le stateChanged du fournisseur indique le handshake VoIP local, tandis que le callReceived.status côté serveur indique le cycle de vie de l'appel sur la plate-forme. Le flip Connected et le minuteur d'appel démarrent à partir de callReceived.status, et non lorsque stateChanged atteint .connected.
| Signal | Informations fournies | Ce que vous pouvez en tirer |
|---|---|---|
stateChanged (fournisseur) |
Échange VoIP local : .connecting, .connected (local), .disconnected, .error(...). |
Spinner d'état facultatif avant l'arrivée de l'état du serveur, l'affichage de l'erreur et le nettoyage de fin d'appel. |
callReceived.status (serveur) |
Cycle de vie côté serveur : .waiting, .connecting, .connected, .onHold, .interrupted, .ended. |
le basculement connecté, le démarrage du minuteur d'appel, l'UI attribuée à l'agent, les calques de transfert ou d'escalade, et le flux de fin d'appel. |
État de l'appel et états côté serveur
Ce que fournit le SDK : un énumérateur CallStatus piloté par le serveur sur chaque charge utile Call qui décrit l'état de l'appel dans son cycle de vie (par exemple, connecting, waiting, connected, onHold, interrupted, ended).
Ce que vous allez créer : le mappage de CallStatus vers les états visibles par le client dans votre écran d'appel (sonnerie, attente dans la file d'attente, connecté, en attente, interrompu, terminé).
Exemple de mise en œuvre
Activez call.status à partir de chaque émission callReceived et affichez l'état d'UI correspondant.
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
}
}
Commandes en cours d'appel (couper le son, haut-parleur, mise en attente)
Ce que fournit le SDK : propriétés en lecture seule sur callService – isMuted, isSpeakerEnabled, isOnHold – ainsi que les actions permettant d'activer/désactiver chaque état (setMuted, setSpeakerEnabled, setOnHold).
Ce que vous allez créer : les boutons de désactivation du micro, du haut-parleur et de mise en attente dans votre UI d'appel, connectés aux actions du SDK et reflétant l'état actuel.
Exemple de mise en œuvre
Lisez l'état actuel à partir de callService pour initialiser vos boutons, puis activez et mettez à jour au moment de l'appui.
// 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
}
Reprendre un appel en cours après une interruption
Lorsqu'une interruption du réseau téléphonique public commuté (comme un appel mobile entrant) met en pause l'appel CCAI actif, le SDK maintient la session active et émet interruptionDetected.
Une fois l'interruption terminée, votre application peut reprendre l'appel.
Ce que fournit le SDK : getLastCallInProgress() pour rechercher un appel en cours (y compris lors des redémarrages de l'application) et resumeCall(_:) pour le ramener au premier plan.
Ce que vous allez créer : l'affordance de reprise dans votre UI (généralement une bannière ou une reprise automatique après la fin de l'interruption) et la navigation vers l'écran d'appel.
Exemple de mise en œuvre
Recherchez l'appel en cours avec getLastCallInProgress, reprenez-le et revenez à l'écran d'appel.
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)
}
}
Escalade depuis un agent virtuel
Ce que fournit le SDK : canEscalate(allowSkipVirtualAgent:) est une méthode sur CallResponse (le modèle émis par callService.callReceived), et non sur callService lui-même. Il indique si l'appel en cours peut être transféré à un agent humain en fonction de l'état actuel de l'agent virtuel de l'appel.
Ce que vous allez créer : conservez la dernière émission callReceived comme état "current call", puis associez la visibilité de votre bouton Parler à une personne à currentCall?.canEscalate(...). L'argument allowSkipVirtualAgent est une valeur de configuration de menu que vous récupérez séparément de la réponse d'appel elle-même. Ne codez pas en dur true en production.
Exemple de mise en œuvre
Conservez le dernier Call dans une propriété stockée, puis appelez canEscalate dessus.
Résolvez allowSkipVirtualAgent dans la configuration de votre menu.
// 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
Messagerie vocale
Ce que fournit le SDK : startVoicemail(_ request: VoicemailRequest) sur callService, ainsi qu'une énumération VoicemailReason qui décrit pourquoi la plate-forme a proposé la messagerie vocale en premier lieu (par exemple, un basculement après les heures d'ouverture, un basculement en cas de dépassement de la capacité ou une redirection temporaire).
Ce que vous allez créer : le point d'entrée de la messagerie vocale dans votre UI (généralement affiché lorsque VoiceCallChannel.voicemailReason est renseigné ou lorsque le cycle de vie de l'appel aboutit à un message vocal) et l'UI d'enregistrement elle-même.
Exemple de mise en œuvre
Affichez le bouton de messagerie vocale lorsque voicemailReason est défini, puis appelez startVoicemail avec un 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)
}
}
Déflection du temps d'attente
Lorsque la file d'attente est ouverte, mais que le temps d'attente dépasse le seuil configuré par l'administrateur, la plate-forme peut proposer une autre solution (généralement un rappel programmé ou une redirection vers le réseau téléphonique public commuté).
Ce que fournit le SDK : une charge utile CallDeflection décrivant l'alternative proposée, récupérable à l'aide de getCallDeflection(callId:) sur callService pour l'appel actif. La plate-forme émet également la même charge utile via l'éditeur deflectionOffered lorsqu'une déviation devient disponible en cours d'attente. Un indicateur CompanyResponse.preventDirectPstnCall distinct indique si la numérotation directe du réseau téléphonique public commuté (RTPC) doit être masquée dans votre UI de secours.
Ce que vous allez créer : l'invite de redirection (par exemple, Le temps d'attente est estimé à 12 minutes. Souhaitez-vous plutôt planifier un rappel ?) et la logique de branchement qui respecte le choix de l'utilisateur.
Exemple de mise en œuvre
Recherchez l'appel actif avec getLastCallInProgress, récupérez la déviation proposée avec getCallDeflection(callId:), combinez-la avec CompanyResponse.preventDirectPstnCall et présentez la requête.
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)
}
Messages audio (annonces système)
Ce que fournit le SDK : un audibleMessageService qui résout les messages sonores configurés par l'administrateur pour une file d'attente (par exemple, Tous les agents sont occupés). Par défaut, le SDK lit automatiquement ces messages lorsque l'appel passe à l'état correspondant.
Objectif de l'atelier : rien, en mode par défaut. Si vous préférez afficher vous-même l'annonce (par exemple, sous forme de texte de sous-titre plus votre propre lecteur audio), initialisez le module d'appel avec playAudibleMessages = false et appelez resolveMessages(menuId:) directement.
Exemple de mise en œuvre
Utilisez l'initialiseur par défaut pour le chemin de lecture du SDK ou définissez playAudibleMessages
= false et résolvez vous-même les messages pour afficher les sous-titres et lire l'audio dans votre propre UI.
// 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)
}
Avancée CallOptions
CallOptions expose un petit ensemble de boutons à bascule pour les applications qui doivent désactiver l'expérience d'appel par défaut.
playAudibleMessages: Bool: lorsquefalse, le SDK ne lit pas les annonces système. Vous devez les afficher vous-même à l'aide deaudibleMessageService.callKitEnabled: Bool: lorsque la valeur estfalse, le SDK ne présente pas l'écran CallKit intégré pour les appels entrants ou sortants. Utilisez cette option lorsque votre application doit afficher sa propre UI d'appel entrant au lieu de s'appuyer sur l'UI système iOS.
Exemple de mise en œuvre
Transmettez les boutons à CallOptions lors de l'initialisation du module d'appel.
// Fully custom in-app call experience
CCAI.shared.initializeCall(
CallOptions(
playAudibleMessages: false,
callKitEnabled: false
)
)
Partage d'écran
Le partage d'écran permet aux agents d'assistance de voir l'écran de l'utilisateur pour l'aider à résoudre les problèmes. Google Cloud project prend en charge deux modes de partage d'écran :
Partage dans l'application : l'agent ne peut voir que ce qui se passe dans votre application spécifique.
Partage complet de l'appareil (facultatif) : l'agent peut voir l'intégralité de l'appareil de l'utilisateur, y compris l'écran d'accueil iOS et d'autres applications. Cela nécessite une configuration iOS avancée à l'aide de ReplayKit d'Apple.
Ce que fournit le SDK : le service de partage d'écran qui crée et gère les sessions, gère les changements d'état et traite les demandes de consentement.
Ce que vous allez créer : la configuration d'initialisation, les invites d'interface utilisateur pour le consentement de l'utilisateur et (si vous prenez en charge l'appareil complet) l'extension de diffusion iOS intégrée.
Le service de partage d'écran fournit des méthodes pour l'ensemble du cycle de vie de la session : create, activate, end, clear (iOS uniquement), ainsi que des méthodes de configuration : updateOptions, enableRemoteControl et enableFullDeviceSharing. Les sous-sections suivantes présentent le flux d'intégration principal.
Pour obtenir les signatures de méthode complètes et les détails des paramètres de toutes les méthodes de partage d'écran, consultez la documentation de référence de l'API Headless Mobile SDK pour iOS.
Initialiser et configurer le partage d'écran
Avant qu'un agent puisse demander le partage d'écran, vous devez initialiser et configurer le service avec votre clé de licence de partage d'écran spécifique.
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"
// )
// )
Vérifier l'éligibilité au partage d'écran
Avant d'activer la fonctionnalité de partage d'écran, vérifiez si elle est disponible pour la discussion en cours :
let isChatSupportingScreenShare = CCAI.shared.screenShareService != nil
&& chat?.isSupportingScreenShare == true
Traiter les demandes de partage d'écran
Implémentez la gestion des demandes de partage d'écran à l'aide de screenShareService. Vous créez un ScreenShareRequest et gérez la réponse asynchrone :
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")
}
}
Gérer les changements d'état du partage d'écran
Observer l'état et les demandes de partage d'écran via les éditeurs de services. Abonnez-vous avant de créer ou d'activer une session afin que votre UI puisse répondre à chaque transition.
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)
L'énumération ScreenShareServiceState suit la progression de la session via .none, .pending, .authorizing, .active et .ended. L'éditeur de la requête émet des requêtes de session et de contrôle à distance que votre application doit traduire en invites de consentement destinées aux clients.
Partage d'écran complet (avancé)
Pour permettre aux agents de voir les écrans des applications autres que les vôtres, vous devez implémenter une extension Apple Broadcast Upload. Cela permet à iOS de capturer l'écran à l'échelle du système et de transmettre les frames vidéo de manière sécurisée au SDK du projetGoogle Cloud .
Ajouter une cible d'extension de diffusion
Ouvrez votre projet Xcode.
Accédez à File > New > Target… (Fichier > Nouveau > Cible…)
Sélectionnez Extension de mise en ligne de diffusions.
Saisissez un nom pour la cible.
Désélectionnez Inclure l'extension d'UI.
Créez la cible en notant son ID de bundle.
Modifiez le SDK cible de votre extension de diffusion sur iOS 12.0 ou version ultérieure.
Configurer le partage du trousseau
Votre application et l'extension d'application doivent partager des secrets à l'aide du trousseau d'accès iOS et de leur propre groupe de trousseau d'accès.
Dans Xcode, accédez à l'onglet Signing & Capabilities (Signature et capacités) pour les deux cibles.
Ajoutez la fonctionnalité Keychain Sharing (Partage de trousseau).
Ajoutez
io.cobrowseaux groupes de trousseaux pour les deux cibles.
Mettez à jour le fichier Info.plist de votre application principale
Ajoutez l'ID du bundle d'extension au fichier Info.plist de votre application (et non au fichier Info.plist de l'extension) :
<key>CBIOBroadcastExtension</key>
<string>your.app.extension.bundle.ID.here</string>
Ajouter CobrowseSDK à la cible de votre extension de diffusion
Dans Xcode, avec la cible d'extension de diffusion sélectionnée, cliquez sur le bouton + sous Frameworks and Libraries (Frameworks et bibliothèques), puis ajoutez CobrowseSDK à la cible d'extension.
Implémenter le gestionnaire d'extension
Xcode ajoute un fichier SampleHandler.swift à la cible que vous avez créée précédemment.
Remplacez le contenu du fichier par le code suivant afin qu'il hérite de la classe d'extension ReplayKit du SDK :
import CobrowseSDK
class SampleHandler: CobrowseIOReplayKitExtension {
// The Google Cloud project module automatically handles ReplayKit lifecycle methods
}
Créer et exécuter
Vous êtes maintenant prêt à créer et à exécuter votre application. La fonctionnalité d'appareil complet n'est disponible que sur les appareils physiques. Elle ne fonctionne pas dans le simulateur iOS.
Si vous avez tout configuré correctement, après avoir sélectionné l'icône circulaire bleue, vous devriez voir un écran vous permettant de sélectionner votre extension de diffusion.
Limitations de SwiftUI pour iOS concernant le partage d'écran
Approches recommandées pour l'interaction à distance dans SwiftUI
Encapsulez les principaux éléments interactifs avec UIKit : pour les zones qui doivent être cliquables à distance, encapsulez-les en tant que contrôles UIKit (par exemple,
UIButton) à l'aide deUIViewRepresentableouUIViewControllerRepresentable. Cela garantit que les clics à distance fonctionnent de manière fiable à l'aide du chemin UIKit de Cobrowse.Transférer les touches à distance avec une gestion tactile personnalisée : pour les zones SwiftUI qui ne peuvent pas être remplacées par UIKit, utilisez les rappels tactiles personnalisés de Cobrowse pour transférer les événements tactiles à distance vers votre logique SwiftUI. L'implémentation implique l'utilisation d'un
UIViewou d'un détecteur de gestes personnalisé pour gérer les rappels, puis la transmission des événements à SwiftUI (à l'aide deUIViewRepresentableplus unCoordinator, des notifications ou des fermetures).Fournissez des conseils ou des solutions de secours au niveau du produit : indiquez clairement sur les écrans SwiftUI que les agents ne peuvent que voir, l'utilisateur doit appuyer localement, ou restreignez automatiquement les autorisations de contrôle à distance sur ces pages tout en conservant l'accès en lecture seule.
Exemple d'implémentation du 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")
}
}
}
}
Appels programmés
Les appels programmés permettent aux utilisateurs finaux de réserver un appel vocal à une date ultérieure au lieu d'attendre dans la file d'attente pour un appel instantané. Dans le SDK headless iOS, utilisez les métadonnées de file d'attente et de chaîne pour déterminer s'il faut afficher un point d'entrée de programmation dans votre application.
Détection des fonctionnalités
Ce que fournit le SDK : un indicateur scheduleEnabled sur VoiceCallChannel qui vous indique si la file d'attente sélectionnée permet de planifier des appels futurs, indépendamment de la disponibilité des appels vocaux instantanés (en direct).
Ce que vous allez créer : la logique permettant de vérifier ce flag avant d'afficher votre point d'entrée de planification.
Exemple de mise en œuvre
Cochez scheduleEnabled sur le canal d'appel vocal de la file d'attente. N'utilisez pas voiceCall != nil comme proxy. Une file d'attente peut prendre en charge les appels vocaux instantanés sans prendre en charge les appels planifiés, et inversement.
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()
}
}
Référence du modèle de données
// 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?)
// ...
}
Vous pouvez également rechercher .scheduleCall dans la liste des chaînes activées renvoyée par QueueMenu.getEnabledChannels().
Récupérer les créneaux horaires disponibles
Le service d'appel sans interface utilisateur peut récupérer les créneaux disponibles pour la file d'attente sélectionnée. Votre application possède l'UI de l'agenda ou du sélecteur d'heure.
Ce que fournit le SDK : les codes temporels des créneaux disponibles pour la file d'attente sélectionnée, avec une option permettant de reprogrammer un appel déjà planifié.
Ce que vous allez créer : le calendrier, le sélecteur d'heure, la présentation du fuseau horaire, la gestion de l'état vide et le comportement de nouvelle tentative.
Exemple de mise en œuvre
Appelez getScheduledTimeSlots avec l'ID du menu de file d'attente. Lorsque vous reprogrammez un appel, transmettez l'ID de l'appel programmé existant afin que le service puisse renvoyer les disponibilités appropriées.
let slots = try await CCAI.shared.callService?.getScheduledTimeSlots(
menuId: menu.id,
callIdForRescheduling: nil
) ?? []
Lorsque vous reprogrammez un appel planifié existant, transmettez l'ID de l'appel existant afin que le service puisse renvoyer la disponibilité appropriée :
let slots = try await CCAI.shared.callService?.getScheduledTimeSlots(
menuId: menu.id,
callIdForRescheduling: existingCallId
) ?? []
Planifier un appel
Une fois que l'utilisateur a sélectionné un créneau horaire, créez l'appel programmé via callService.
Ce que fournit le SDK : une API createScheduledCall qui réserve le créneau sélectionné et renvoie l'enregistrement de l'appel programmé.
Ce que vous allez créer : validation du numéro de téléphone au format E.164, UI de confirmation, persistance locale de l'ID de l'appel planifié et récupération en cas d'erreurs de planification.
Exemple de mise en œuvre
Transmettez le créneau sélectionné, le numéro de téléphone, l'ID de file d'attente et RecordingPermission.notAsked dans un 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)
Le numéro de téléphone doit être au format E.164, par exemple +14155551234.
Reprogrammer un appel planifié
Pour reprogrammer un appel, transmettez l'ID de l'appel planifié existant sous la forme callIdForRescheduling.
Ce que fournit le SDK : les mêmes API de création et de créneaux horaires, avec callIdForRescheduling utilisé pour identifier la réservation existante.
Ce que vous allez créer : l'UI "change time", la recherche locale de l'ID d'appel planifié stocké et l'état de confirmation mis à jour après la création de la nouvelle réservation.
Exemple de mise en œuvre
Transmettez l'ID d'appel existant à createScheduledCall une fois que l'utilisateur a sélectionné un nouveau créneau.
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)
Annuler un appel programmé
Lorsque l'utilisateur annule un appel à venir, appelez cancelScheduledCall et effacez l'ID d'appel stocké localement.
Ce que fournit le SDK : une API d'annulation pour un ID d'appel programmé.
Ce que vous allez créer : l'invite de confirmation, l'UI de réussite ou d'erreur d'annulation, et le nettoyage de tout état d'appel à venir stocké localement.
Exemple de mise en œuvre
Appelez cancelScheduledCall(callId:) avec l'ID stocké, puis supprimez l'ID de l'espace de stockage de votre application.
try await CCAI.shared.callService?.cancelScheduledCall(callId: existingCallId)
clearScheduledCallId()
Conservez l'ID de l'appel programmé dans votre application si vous souhaitez proposer un état d'appel à venir, ou des expériences de reprogrammation ou d'annulation après le redémarrage de l'application.
Ce que fournit le SDK : l'adresse e-mail de destination configurée pour cette file d'attente spécifique, ainsi que toutes les instructions que l'administrateur souhaite que l'utilisateur voie (par exemple, Indiquez votre numéro de compte).
Ce que vous allez créer : l'écran de rédaction d'e-mails et le délégué pour suivre son achèvement. Vous pouvez créer votre propre formulaire personnalisé ou utiliser le MFMailComposeViewController intégré d'Apple.
Exemple de mise en œuvre
Ce code extrait l'adresse e-mail d'assistance et les instructions du SDK. Il ouvre le compositeur de messagerie iOS intégré et utilise MFMailComposeViewControllerDelegate pour écouter le moment exact où l'utilisateur sélectionne Envoyer ou Annuler.
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
}
}
}
Liens de déviation externe
Ce que fournit le SDK : une liste d'URL (par exemple, le centre d'aide de votre entreprise, les conditions de remboursement ou une application partenaire) et leurs titres à afficher, exactement tels qu'ils sont configurés dans le portail d'administration.
Ce que vous allez créer : la logique permettant d'exécuter ces liens lorsqu'un utilisateur les sélectionne, soit en les ouvrant dans un navigateur intégré à l'application, soit en les envoyant vers l'application Safari.
Exemple de mise en œuvre
Cet utilitaire prend une chaîne d'URL et la présente dans le navigateur intégré dans l'application d'Apple.
import SafariServices
func openHelpCenterLink(_ urlString: String) {
guard let url = URL(string: urlString) else { return }
let safariViewController = SFSafariViewController(url: url)
present(safariViewController, animated: true)
}
Exemple d'intégration complète (itérer sur tous les liens activés)
Sur iOS, ExternalDeflectionLink ne comporte pas de url de premier niveau. Les liens se trouvent dans un tableau links: [ExternalDeflection]? interne, et chaque entrée activée ajoute un bouton au menu de la chaîne. Itérez le tableau et ignorez toutes les entrées dont l'indicateur enabled n'est pas 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 expose enabled: Bool? et links:
[ExternalDeflection]?. Chaque ExternalDeflection comporte son propre url et displayName. Si QueueMenu.getEnabledChannels() est utilisé, le SDK émet une entrée .externalDeflection(url:displayName:) par lien activé. Par conséquent, l'itération links directement et l'itération de la sortie des canaux activés produisent le même ensemble de boutons.