SDK mobile sans interface utilisateur pour iOS : voix, partage d'écran, appel planifié et e-mail

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. Traitez nil ou false comme 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 de RecordingPermission.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. Lorsque deflected == true, affichez le message deflectedReason configuré 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)
    }
}

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é :

  1. Inspectez le VoiceCallChannel de la file d'attente sélectionnée.

  2. Vérifiez que les appels instantanés sont activés et qu'ils ne sont pas redirigés.

  3. Gérez l'autorisation d'enregistrement en fonction des recordingOption de la file d'attente.

  4. Demandez l'autorisation d'accéder au micro.

  5. 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 : lorsque false, le SDK ne lit pas les annonces système. Vous devez les afficher vous-même à l'aide de audibleMessageService.

  • callKitEnabled: Bool : lorsque la valeur est false, 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.cobrowse aux 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

  • 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 de UIViewRepresentable ou UIViewControllerRepresentable. 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 UIView ou d'un détecteur de gestes personnalisé pour gérer les rappels, puis la transmission des événements à SwiftUI (à l'aide de UIViewRepresentable plus un Coordinator, 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.

E-mail

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

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

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.