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 Sieniloderfalseals"don't offer an instant call button"-Status. Im Gegensatz zuvoiceCall != 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 alsRecordingPermission.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. Wenndeflected == true, wird die vom Administrator konfigurierte MeldungdeflectedReasonangezeigt 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)
}
}
Einwilligung zur Aufzeichnung
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:
Prüfen Sie die
VoiceCallChannelder ausgewählten Warteschlange.Prüfen Sie, ob Sofortanrufe aktiviert sind und nicht umgeleitet werden.
Die Einwilligung zur Aufzeichnung wird gemäß den
recordingOptionder Warteschlange eingeholt.Mikrofonberechtigung anfordern
Rufen Sie
startInstantCallan.
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: Wennfalse, gibt das SDK keine Systembenachrichtigungen aus. Rendern Sie sie selbst mitaudibleMessageService.callKitEnabled: Bool: Wennfalse, 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.cobrowsefü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
Empfohlene Ansätze für die Remote-Interaktion in SwiftUI
Wichtige interaktive Elemente mit UIKit umschließen: Bereiche, die per Fernbedienung angeklickt werden müssen, sollten als UIKit-Steuerelemente (z. B.
UIButton) mitUIViewRepresentableoderUIViewControllerRepresentableumschlossen 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
UIViewoder einem Gestenerkennungsmodul verarbeitet und Ereignisse dann mitUIViewRepresentablesowie einemCoordinator, 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.
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
}
}
}
Externe Umleitungslinks
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)
}
Beispiel für eine vollständige Integration (alle aktivierten Links durchlaufen)
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.