Headless Mobile SDK for iOS: Sprache, Bildschirmfreigabe, geplanter Anruf und E‑Mail

In diesem Dokument wird beschrieben, wie Sie das Headless Mobile SDK in Ihre Android-App einbinden und anpassen. Es umfasst Sprachanrufe über die CCAICall.

Sprachanrufe

Das Headless Mobile SDK für iOS bietet Unterstützung für Sprachanrufe über das CCAICall-Modul. Ihre App ist für die benutzerdefinierte Anrufoberfläche verantwortlich, während das SDK die Anrufverbindung, die CallKit-Integration, die Verarbeitung von VoIP-Push-Benachrichtigungen und die Ereignisse des Anruflife-Cycles übernimmt.

Funktionen des SDK: APIs für Anrufdienste zum Starten von Sofortanrufen, Starten von Voicemail, Verarbeiten eingehender Anrufe und Beobachten des Anrufstatus.

Was Sie entwickeln: Die visuelle Anrufoberfläche, einschließlich des Einstiegspunkts vor dem Anruf, der Aufforderung zur Einwilligung in die Aufzeichnung, der Klingel- oder Wartestatus, der Steuerelemente während des Anrufs und der Navigation nach dem Anruf.

Anrufmodul initialisieren

Initialisieren Sie das Anrufmodul nach der Initialisierung des Core SDK:

import CCAIKit
import CCAICall

try CCAI.shared.initialize(options: options)
CCAI.shared.initializeCall(CallOptions())

VoiceCallChannel-Funktionen prüfen

Bevor Sie einen Sofortanruf anbieten, prüfen Sie die VoiceCallChannel-Struktur der Warteschlange, um zu entscheiden, welche Einstiegspunkte verfügbar gemacht werden sollen (Sofortanruf, Voicemail-Fallback, Umleitung auf Channelebene) und ob eine Einwilligung zur Aufzeichnung erforderlich ist.

Wichtige VoiceCallChannel-Felder

  • instantEnabled: Bool? – Gibt an, ob für diese Warteschlange ein Live-Sprachanruf (sofort) zulässig ist. Behandeln Sie nil oder false als "don't offer an instant call button"-Status. Im Gegensatz zu voiceCall != nil, das nur angibt, ob die Warteschlange überhaupt einen Sprachkanal hat.

  • preSessionSmartAction: Bool? – Gibt an, ob für diesen bestimmten Channel vor Beginn eines Anrufs Smart Actions vor der Sitzung erforderlich sind. Informationen zum ergänzenden Pfad auf Warteschlangenebene finden Sie unter Headless Mobile SDK for iOS: Smart actions, attachments, and deflection.

  • scheduleEnabled: Bool? – Gibt an, ob geplante Anrufe unterstützt werden. Informationen zum ergänzenden Pfad auf Warteschlangenebene finden Sie unter Geplante Anrufe.

  • recordingOption: RecordingOption? – das Einwilligungsmodell für die Anrufaufzeichnung (siehe Einwilligung zur Aufzeichnung). Anders als RecordingPermission.notAsked, das planungsspezifisch ist.

  • voicemailReason: String?: Wird ausgefüllt, wenn der Channel so konfiguriert ist, dass Anrufe an die Voicemail weitergeleitet werden.

  • phoneNumber: String?: PSTN-Fallbacknummer, die für die Umleitung oder Voicemail konfiguriert ist.

  • scheduleDeflectionType: String? / deflected: Bool? / deflectedReason: String?: Metadaten zur Ablenkung auf Channelebene. Wenn deflected == true, wird die vom Administrator konfigurierte Meldung deflectedReason angezeigt und der konfigurierte Fallback (z. B. eine Telefonnummer zum Wählen oder ein Einstiegspunkt für einen geplanten Anruf) angeboten, anstatt einen sofortigen Anruf zu starten. Informationen zur Bearbeitung von Anfragen auf Warteschlangenebene finden Sie unter Weiterleitung (außerhalb der Geschäftszeiten und bei Überlastung).

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

Was das SDK bietet: Ein recordingOption: RecordingOption?-Feld in VoiceCallChannel, das das Einwilligungsmodell für die Anrufaufzeichnung beschreibt, das Administratoren im Portal konfiguriert haben.

Was Sie erstellen: Die Einwilligungserklärung (wenn .askUser) und die Verzweigungslogik, die die Auswahl des Administrators berücksichtigt.

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

Sofortanruf starten

Bevor Sie einen Sofortanruf starten:

  1. Prüfen Sie die VoiceCallChannel der ausgewählten Warteschlange.

  2. Prüfen Sie, ob Sofortanrufe aktiviert sind und nicht umgeleitet werden.

  3. Die Einwilligung zur Aufzeichnung wird gemäß den recordingOption der Warteschlange eingeholt.

  4. Mikrofonberechtigung anfordern

  5. Rufen Sie startInstantCall an.

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

Anrufstatus beobachten

Abonnieren Sie Anrufdienstereignisse, bevor Sie einen Anruf starten oder annehmen:

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)

Anbieterstatus im Vergleich zum Serverstatus

stateChanged und callReceived.status sind unabhängige Signale. Lesen Sie sie als Spalten, nicht als Zeilen. Der stateChanged des Anbieters meldet den lokalen VoIP-Handshake, der serverseitige callReceived.status den Lebenszyklus des Anrufs auf der Plattform. Der Flip Verbunden und der Start des Anruftimers werden durch callReceived.status ausgelöst, nicht durch stateChanged, wenn .connected erreicht wird.

Signal Was wird gemeldet? Was Sie daraus ableiten können
stateChanged (Anbieter) Lokaler VoIP-Handshake: .connecting, .connected (lokal), .disconnected, .error(...). Optionaler Pre-Status-Spinner, bevor der Serverstatus eintrifft, Fehler angezeigt werden und die Bereinigung nach dem Anruf erfolgt.
callReceived.status (Server) Serverseitiger Lebenszyklus: .waiting, .connecting, .connected, .onHold, .interrupted, .ended. Verbunden-Flip, Start des Anruftimers, vom Kundenservicemitarbeiter zugewiesene Benutzeroberfläche, Überlagerungen für Weiterleitung oder Eskalierung und Ablauf zum Beenden des Anrufs.

Anrufstatus und serverseitige Status

Was das SDK bietet: Ein servergesteuertes CallStatus-Enum für jede Call-Nutzlast, das beschreibt, wo sich der Aufruf im Lebenszyklus befindet (z. B. connecting, waiting, connected, onHold, interrupted, ended).

Was Sie entwickeln: Die Zuordnung von CallStatus zu den für den Kunden sichtbaren Status in Ihrem Anrufbildschirm („Klingelt“, „Wartet in der Warteschleife“, „Verbunden“, „In der Warteschleife“, „Unterbrochen“, „Beendet“).

Implementierungsbeispiel

Schalten Sie call.status bei jeder callReceived-Ausgabe ein und rendern Sie den entsprechenden UI-Status.

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

Steuerelemente während des Anrufs (Stummschalten, Lautsprecher, Halten)

Funktionen des SDK: Nur-Lese-Attribute für callService – isMuted, isSpeakerEnabled, isOnHold – sowie die Aktionen zum Umschalten der einzelnen Status (setMuted, setSpeakerEnabled, setOnHold).

Was Sie entwickeln: Die Schaltflächen zum Stummschalten, für den Lautsprecher und zum Halten in Ihrer Anruf-Benutzeroberfläche, die mit den Aktionen des SDK verbunden sind und den aktuellen Status widerspiegeln.

Implementierungsbeispiel

Lesen Sie den aktuellen Status aus callService, um die Schaltflächen zu initialisieren, und schalten Sie dann um und aktualisieren Sie sie bei Berührung.

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

Laufenden Anruf nach einer Unterbrechung fortsetzen

Wenn ein PSTN-Unterbrechung (z. B. ein eingehender Mobilfunkanruf) den aktiven CCAI-Anruf pausiert, hält das SDK die Sitzung aktiv und gibt interruptionDetected aus. Nach dem Ende der Unterbrechung kann Ihre App den Anruf fortsetzen.

Funktionen des SDK: getLastCallInProgress() zum Suchen nach einem laufenden Anruf (auch nach Neustarts der App) und resumeCall(_:), um ihn in den Vordergrund zu holen.

Was Sie entwickeln: Die Möglichkeit zum Fortsetzen in Ihrer Benutzeroberfläche (in der Regel ein Banner oder ein automatisches Fortsetzen nach dem Ende der Unterbrechung) und die Navigation zurück zum Anrufbildschirm.

Implementierungsbeispiel

Suchen Sie mit getLastCallInProgress nach dem laufenden Anruf, setzen Sie ihn fort und kehren Sie zum Anrufbildschirm zurück.

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

Eskalierung durch einen virtuellen Kundenservicemitarbeiter

Was das SDK bietet: canEscalate(allowSkipVirtualAgent:) ist eine Methode für CallResponse (das von callService.callReceived ausgegebene Modell), nicht für callService selbst. Es wird gemeldet, ob der aktuelle Anruf basierend auf dem aktuellen Status des virtuellen Kundenservicemitarbeiters für die Weiterleitung an einen menschlichen Kundenservicemitarbeiter infrage kommt.

Was Sie entwickeln: Behalten Sie die letzte callReceived-Ausgabe als "current call"-Status bei und binden Sie die Sichtbarkeit der Schaltfläche Mit einer Person sprechen an currentCall?.canEscalate(...). Das Argument allowSkipVirtualAgent ist ein Menükonfigurationswert, den Sie separat aus der Aufrufantwort abrufen. Codieren Sie true nicht fest in der Produktion.

Implementierungsbeispiel

Speichern Sie die aktuelle Call in einer gespeicherten Property und rufen Sie dann canEscalate dafür auf. Lösen Sie allowSkipVirtualAgent aus Ihrer Menükonfiguration.

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

Mailbox

Funktionen des SDK: startVoicemail(_ request: VoicemailRequest) auf callService sowie ein VoicemailReason-Enum, das beschreibt, warum die Plattform überhaupt Voicemail angeboten hat (z. B. Fallback nach Feierabend, Fallback bei Überlastung oder vorübergehende Weiterleitung).

Was Sie entwickeln: Der Einstiegspunkt für die Voicemail in Ihrer Benutzeroberfläche (wird in der Regel angezeigt, wenn VoiceCallChannel.voicemailReason ausgefüllt ist oder wenn der Anrufdurchlauf zu einem Voicemail-Ergebnis führt) und die Aufzeichnungsoberfläche selbst.

Implementierungsbeispiel

Zeige den Mailbox-Button an, wenn voicemailReason festgelegt ist, und rufe dann startVoicemail mit einem VoicemailRequest auf.

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

Verkürzung der Wartezeit

Wenn die Warteschlange geöffnet ist, die Wartezeit jedoch den vom Administrator konfigurierten Grenzwert überschreitet, kann die Plattform einen alternativen Pfad anbieten, in der Regel einen geplanten Rückruf oder eine PSTN-Umleitung.

Was das SDK bietet: Eine CallDeflection-Nutzlast, die die angebotene Alternative beschreibt und über getCallDeflection(callId:) auf callService für den aktiven Anruf abgerufen werden kann. Die Plattform gibt dieselbe Nutzlast auch über den Publisher deflectionOffered aus, wenn während des Wartens eine Umleitung verfügbar wird. Ein separates CompanyResponse.preventDirectPstnCall-Flag gibt an, ob die direkte PSTN-Wahl in Ihrer Fallback-Benutzeroberfläche ausgeblendet werden soll.

Was Sie entwickeln: Die Umleitungsaufforderung (z. B. Die geschätzte Wartezeit beträgt 12 Minuten. Möchten Sie stattdessen einen Rückruf planen?) und die Verzweigungslogik, die die Auswahl des Nutzers berücksichtigt.

Implementierungsbeispiel

Suche den aktiven Anruf mit getLastCallInProgress, rufe die angebotene Umleitung mit getCallDeflection(callId:) ab, kombiniere sie mit CompanyResponse.preventDirectPstnCall und präsentiere den Prompt.

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

Akustische Nachrichten (Systemansagen)

Was das SDK bietet: Ein audibleMessageService, das die vom Administrator konfigurierten hörbaren Nachrichten für eine Warteschlange auflöst (z. B. Alle Kundenservicemitarbeiter sind beschäftigt). Standardmäßig werden diese Nachrichten vom SDK automatisch wiedergegeben, wenn der Anruf den entsprechenden Status erreicht.

Was Sie erstellen: Im Standardmodus nichts. Wenn Sie die Ankündigung lieber selbst rendern möchten (z. B. als Untertiteltext plus eigenen Audioplayer), initialisieren Sie das Anrufmodul mit playAudibleMessages = false und rufen Sie resolveMessages(menuId:) direkt auf.

Implementierungsbeispiel

Verwenden Sie den Standard-Initializer für den SDK-Wiedergabepfad oder legen Sie playAudibleMessages = false fest und lösen Sie Nachrichten selbst auf, um Untertitel zu rendern und Audio in Ihrer eigenen Benutzeroberfläche wiederzugeben.

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

Erweitert CallOptions

CallOptions bietet eine kleine Anzahl von Ein/Aus-Schaltern für Apps, die die Standardanruferfahrung deaktivieren müssen.

  • playAudibleMessages: Bool: Wenn false, gibt das SDK keine Systembenachrichtigungen aus. Rendern Sie sie selbst mit audibleMessageService.

  • callKitEnabled: Bool: Wenn false, wird im SDK nicht der integrierte CallKit-Bildschirm für eingehende oder ausgehende Anrufe angezeigt. Verwenden Sie diese Option, wenn Ihre App ihre eigene In-App-Benutzeroberfläche für eingehende Anrufe rendern muss, anstatt sich auf die iOS-System-Benutzeroberfläche zu verlassen.

Implementierungsbeispiel

Übergeben Sie die Ein/Aus-Schalter an CallOptions, wenn Sie das Anrufmodul initialisieren.

// Fully custom in-app call experience
CCAI.shared.initializeCall(
    CallOptions(
        playAudibleMessages: false,
        callKitEnabled: false
    )
)

Bildschirm freigeben

Durch die Bildschirmfreigabe können Support-Mitarbeiter den Bildschirm des Nutzers sehen, um Probleme zu beheben. Google Cloud project unterstützt zwei Modi der Bildschirmfreigabe:

  • In-App-Freigabe: Der KI-Agent kann nur sehen, was in Ihrer jeweiligen App passiert.

  • Freigabe des gesamten Geräts (optional): Der Kundenservicemitarbeiter kann das gesamte Gerät des Nutzers sehen, einschließlich des iOS-Startbildschirms und anderer Apps. Dazu ist eine erweiterte iOS-Konfiguration mit dem ReplayKit von Apple erforderlich.

Funktionen des SDK: Der Bildschirmfreigabedienst, der Sitzungen erstellt und verwaltet, Statusänderungen verarbeitet und Einwilligungsanfragen bearbeitet.

Was Sie entwickeln: Die Initialisierungskonfiguration, die UI-Aufforderungen für die Einwilligung des Nutzers und (bei Unterstützung des gesamten Geräts) die integrierte iOS-Broadcast-Erweiterung.

Der Bildschirmfreigabedienst bietet Methoden für den gesamten Sitzungslebenszyklus – create, activate, end, clear (nur iOS) – sowie Konfigurationsmethoden updateOptions, enableRemoteControl und enableFullDeviceSharing. In den nächsten Unterabschnitten wird der grundlegende Integrationsablauf beschrieben.

Vollständige Methodensignaturen und Parameterdetails für alle Methoden zur Bildschirmfreigabe finden Sie in der Headless Mobile SDK – iOS API Reference.

Bildschirmfreigabe initialisieren und konfigurieren

Bevor ein Kundenservicemitarbeiter eine Bildschirmfreigabe anfordern kann, müssen Sie den Dienst mit Ihrem spezifischen Lizenzschlüssel für die Bildschirmfreigabe initialisieren und konfigurieren.

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"
//     )
// )

Voraussetzungen für die Bildschirmfreigabe prüfen

Bevor Sie die Bildschirmfreigabe aktivieren, prüfen Sie, ob sie für den aktuellen Chat verfügbar ist:

let isChatSupportingScreenShare = CCAI.shared.screenShareService != nil
    && chat?.isSupportingScreenShare == true

Anfragen zur Bildschirmfreigabe bearbeiten

Implementieren Sie die Verarbeitung von Bildschirmfreigabeanfragen mit der screenShareService. Sie erstellen ein ScreenShareRequest und verarbeiten die asynchrone Antwort:

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

Änderungen des Bildschirmfreigabestatus verarbeiten

Den Status der Bildschirmfreigabe und Anfragen über die Dienst-Publisher beobachten. Abonnieren Sie die Ereignisse, bevor Sie eine Sitzung erstellen oder aktivieren, damit Ihre Benutzeroberfläche auf jede Übergang reagieren kann.

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)

Das Enum ScreenShareServiceState verfolgt den Sitzungsfortschritt über .none, .pending, .authorizing, .active und .ended. Der Request Publisher gibt Sitzungs- und Fernbedienungsanfragen aus, die Ihre App in Einwilligungsaufforderungen für Kunden umwandeln sollte.

Freigabe des gesamten Gerätebildschirms (erweitert)

Damit Kundenservicemitarbeiter Bildschirme von Anwendungen außerhalb Ihrer eigenen sehen können, müssen Sie eine Apple Broadcast Upload Extension implementieren. So kann iOS den Bildschirm systemweit erfassen und die Videoframes sicher an dasGoogle Cloud -Projekt-SDK übergeben.

Ziel für Broadcast-Erweiterung hinzufügen

  • Öffnen Sie Ihr Xcode-Projekt.

  • Klicken Sie auf Datei > Neu > Ziel…

  • Wähle Broadcast Upload Extension (Erweiterung für Broadcast-Uploads) aus.

  • Geben Sie einen Namen für das Ziel ein.

  • Entfernen Sie das Häkchen von UI-Erweiterung einbeziehen.

  • Erstellen Sie das Ziel und notieren Sie sich die Paket-ID.

  • Ändere das Ziel-SDK deiner Broadcast-Erweiterung auf iOS 12.0 oder höher.

Schlüsselbundfreigabe einrichten

Ihre App und die App-Erweiterung müssen sich Geheimnisse über den iOS-Schlüsselbund mit ihrer eigenen Schlüsselbundgruppe teilen.

  • Rufen Sie in Xcode für beide Ziele den Tab Signing & Capabilities auf.

  • Fügen Sie die Funktion Schlüsselbundfreigabe hinzu.

  • Fügen Sie io.cobrowse für beide Ziele den Schlüsselbundgruppen hinzu.

Info.plist der Haupt-App aktualisieren

Fügen Sie die ID des Erweiterungs-Bundles der Info.plist Ihrer App hinzu (nicht der Info.plist der Erweiterung):

<key>CBIOBroadcastExtension</key>
<string>your.app.extension.bundle.ID.here</string>

CobrowseSDK zum Ziel Ihrer Broadcast-Erweiterung hinzufügen

Wählen Sie in Xcode das Ziel der Broadcast-Erweiterung aus und klicken Sie unter Frameworks and Libraries (Frameworks und Bibliotheken) auf das +-Symbol, um CobrowseSDK zum Ziel der Erweiterung hinzuzufügen.

Erweiterungshandler implementieren

Xcode fügt dem zuvor erstellten Ziel eine SampleHandler.swift-Datei hinzu. Ersetzen Sie den Inhalt der Datei durch Folgendes, damit sie von der ReplayKit-Erweiterungsklasse des SDK abgeleitet wird:

import CobrowseSDK

class SampleHandler: CobrowseIOReplayKitExtension {
    // The Google Cloud project module automatically handles ReplayKit lifecycle methods
}

Erstellen und ausführen

Sie können Ihre App jetzt erstellen und ausführen. Die Funktion für das gesamte Gerät ist nur auf physischen Geräten verfügbar und funktioniert nicht im iOS-Simulator.

Wenn du alles richtig eingerichtet hast, solltest du nach dem Auswählen des blauen Kreissymbols einen Bildschirm sehen, auf dem du deine Broadcast-Erweiterung auswählen kannst.

Einschränkungen für die Bildschirmfreigabe unter iOS SwiftUI

  • Wichtige interaktive Elemente mit UIKit umschließen: Bereiche, die per Fernbedienung angeklickt werden müssen, sollten als UIKit-Steuerelemente (z. B. UIButton) mit UIViewRepresentable oder UIViewControllerRepresentable umschlossen werden. So wird sichergestellt, dass Remote-Klicks über den UIKit-Pfad von Cobrowse zuverlässig funktionieren.

  • Weiterleiten von Remote-Berührungen mit benutzerdefinierter Touch-Verarbeitung: Für SwiftUI-Bereiche, die nicht durch UIKit ersetzt werden können, verwenden Sie die benutzerdefinierten Touch-Callbacks von Cobrowse, um Remote-Touch-Ereignisse an Ihre SwiftUI-Logik weiterzuleiten. Bei der Implementierung werden Callbacks mit einem benutzerdefinierten UIView oder einem Gestenerkennungsmodul verarbeitet und Ereignisse dann mit UIViewRepresentable sowie einem Coordinator, Benachrichtigungen oder Closures an SwiftUI übergeben.

  • Geben Sie Anleitungen oder Fallback-Optionen auf Produktebene an. Geben Sie auf SwiftUI-Bildschirmen deutlich an, dass Kundenservicemitarbeiter nur sehen können; Nutzer müssen lokal tippen, oder schränken Sie die Berechtigungen für die Fernbedienung auf diesen Seiten automatisch ein, während der Nur-Lesezugriff beibehalten wird.

Beispiel für die Implementierung eines UIKit-Wrappers

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

Geplante Anrufe

Mit geplanten Anrufen können Endnutzer einen zukünftigen Sprachanruf buchen, anstatt in der Warteschleife für einen sofortigen Anruf zu warten. Im monitorlosen iOS-SDK können Sie anhand von Metadaten zu Warteschlange und Kanal entscheiden, ob in Ihrer App ein Planungseinstiegspunkt angezeigt werden soll.

Funktionserkennung

Was das SDK bietet: Ein scheduleEnabled-Flag für VoiceCallChannel, das angibt, ob die ausgewählte Warteschlange die Buchung zukünftiger Anrufe unterstützt – unabhängig davon, ob sofortige (Live-)Sprachanrufe verfügbar sind.

Was Sie entwickeln müssen: Die Logik zum Prüfen dieses Flags, bevor der Einstiegspunkt für die Terminplanung angezeigt wird.

Implementierungsbeispiel

Prüfen Sie scheduleEnabled im Sprachanruf-Channel der Warteschlange. Verwenden Sie nicht voiceCall != nil als Proxy. Eine Warteschlange kann sofortige Audioanrufe unterstützen, ohne geplante Anrufe zu unterstützen, und umgekehrt.

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

Referenz zum Datenmodell

// 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?)
    // ...
}

Sie können auch in der Liste der aktivierten Channels, die von QueueMenu.getEnabledChannels() zurückgegeben wird, nach .scheduleCall suchen.

Verfügbare Zeitblöcke abrufen

Der monitorlose Anrufdienst kann verfügbare Terminzeiten für die ausgewählte Warteschlange abrufen. Ihre App ist für die Kalender- oder Zeitpicker-Benutzeroberfläche verantwortlich.

Was das SDK bietet: Verfügbare Zeitstempel für Slots für die ausgewählte Warteschlange mit optionaler Unterstützung für das Verschieben eines vorhandenen geplanten Anrufs.

Was Sie entwickeln: Kalender, Zeitauswahl, Zeitzonendarstellung, Verarbeitung von leeren Status und Wiederholungsverhalten.

Implementierungsbeispiel

Rufen Sie getScheduledTimeSlots mit der ID des Warteschlangenmenüs auf. Geben Sie beim Umplanen die vorhandene ID des geplanten Anrufs an, damit der Dienst die entsprechende Verfügbarkeit zurückgeben kann.

let slots = try await CCAI.shared.callService?.getScheduledTimeSlots(
    menuId: menu.id,
    callIdForRescheduling: nil
) ?? []

Wenn Sie einen vorhandenen geplanten Anruf verschieben, übergeben Sie die vorhandene Anruf-ID, damit der Dienst die entsprechende Verfügbarkeit zurückgeben kann:

let slots = try await CCAI.shared.callService?.getScheduledTimeSlots(
    menuId: menu.id,
    callIdForRescheduling: existingCallId
) ?? []

Geplanten Anruf erstellen

Nachdem der Nutzer einen Zeitraum ausgewählt hat, erstellen Sie den geplanten Anruf über callService.

Funktionen des SDK: Eine createScheduledCall-API, mit der der ausgewählte Termin gebucht und der Datensatz für den geplanten Anruf zurückgegeben wird.

Was Sie entwickeln: E.164-Telefonnummernvalidierung, Bestätigungs-UI, lokale Persistenz der geplanten Anruf-ID und Wiederherstellung bei Planungsfehlern.

Implementierungsbeispiel

Übergeben Sie den ausgewählten Slot, die Telefonnummer, die Warteschlangen-ID und RecordingPermission.notAsked in einem 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)

Die Telefonnummer muss im E.164-Format angegeben werden, z. B. +14155551234.

Geplantes Gespräch verschieben

Wenn Sie einen Termin verschieben möchten, übergeben Sie die vorhandene ID des geplanten Anrufs als callIdForRescheduling.

Was das SDK bietet: Die gleichen APIs für Zeitfenster und Erstellung, wobei callIdForRescheduling zur Identifizierung der vorhandenen Buchung verwendet wird.

Was Sie entwickeln: Die "change time"-Benutzeroberfläche, die lokale Suche nach der gespeicherten ID für geplante Anrufe und der aktualisierte Bestätigungsstatus nach der Erstellung der neuen Buchung.

Implementierungsbeispiel

Übergeben Sie die vorhandene Anruf-ID an createScheduledCall, nachdem der Nutzer einen neuen Termin ausgewählt hat.

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)

Geplanten Anruf abbrechen

Wenn der Nutzer einen anstehenden Anruf abbricht, rufen Sie cancelScheduledCall auf und löschen Sie die lokal gespeicherte Anruf-ID.

Was das SDK bietet: Eine API zum Abbrechen einer geplanten Anruf-ID.

Was Sie entwickeln: Die Bestätigungsaufforderung, die Benutzeroberfläche für den Erfolg oder Fehler bei der Stornierung und das Bereinigen aller lokal gespeicherten Zustände für anstehende Anrufe.

Implementierungsbeispiel

Rufen Sie cancelScheduledCall(callId:) mit der gespeicherten ID auf und entfernen Sie die ID dann aus dem Speicher Ihrer App.

try await CCAI.shared.callService?.cancelScheduledCall(callId: existingCallId)
clearScheduledCallId()

Speichern Sie die ID des geplanten Anrufs in Ihrer App, wenn Sie nach dem Neustart der App den Status eines anstehenden Anrufs, die Möglichkeit zum Verschieben oder zum Abbrechen anbieten möchten.

E-Mail

Was das SDK bietet: Die für diese bestimmte Warteschlange konfigurierte Ziel-E-Mail-Adresse sowie alle Anleitungen, die der Administrator dem Nutzer anzeigen möchte (z. B. Geben Sie Ihre Kontonummer an).

Was Sie erstellen: Den Bildschirm für das Verfassen von E‑Mails und den Delegaten, um den Abschluss zu verfolgen. Sie können ein eigenes benutzerdefiniertes Formular erstellen oder das integrierte MFMailComposeViewController von Apple verwenden.

Implementierungsbeispiel

Mit diesem Code werden die Support-E‑Mail-Adresse und die Anleitung aus dem SDK abgerufen. Dadurch wird die integrierte iOS-E‑Mail-Erstellung geöffnet und MFMailComposeViewControllerDelegate wird verwendet, um den genauen Moment zu erfassen, in dem der Nutzer Senden oder Abbrechen auswählt.

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

Was das SDK bietet: Eine Liste von URLs (z. B. die Hilfe Ihres Unternehmens, die Erstattungsrichtlinie oder eine Partner-App) und deren Anzeigetitel, genau wie im Administratorportal konfiguriert.

Was Sie entwickeln: Die Logik zum Ausführen dieser Links, wenn ein Nutzer sie auswählt, entweder durch Öffnen in einem integrierten In-App-Browser oder durch Senden an die Safari App.

Implementierungsbeispiel

Dieser Helfer nimmt einen URL-String entgegen und präsentiert ihn im In‑App-Browser von Apple.

import SafariServices

func openHelpCenterLink(_ urlString: String) {
    guard let url = URL(string: urlString) else { return }
    let safariViewController = SFSafariViewController(url: url)
    present(safariViewController, animated: true)
}

Unter iOS enthält ExternalDeflectionLink kein url auf oberster Ebene. Die Links befinden sich in einem inneren links: [ExternalDeflection]?-Array und jeder aktivierte Eintrag trägt einen Button zum Kanalmenü bei. Durchlaufen Sie das Array und überspringen Sie alle Einträge, deren Flag enabled nicht true ist.

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 macht enabled: Bool? und links: [ExternalDeflection]? verfügbar. Jedes ExternalDeflection hat ein eigenes url und displayName. Wenn QueueMenu.getEnabledChannels() verwendet wird, gibt das SDK einen .externalDeflection(url:displayName:)-Eintrag pro aktiviertem Link aus. Wenn Sie also links direkt durchlaufen und die Ausgabe der aktivierten Channels durchlaufen, erhalten Sie dieselbe Gruppe von Schaltflächen.