Headless Mobile SDK für iOS: Erweiterte Themen, Lokalisierung und Abläufe nach der Sitzung

In diesem Dokument wird beschrieben, wie Sie das Headless Mobile SDK in Ihre Android-App einbinden und anpassen. Es deckt alles ab, was nach dem Ende einer Sitzung passiert, einschließlich Lokalisierung, Fehlerbehandlung und Sitzungsverwaltung, Endnutzerdienste, benutzerdefinierte Daten, externe Chatübertragung, reaktive Combine-Muster, Threading-Überlegungen, Speicherverwaltung und Fehlerbehebung.

Abläufe nach der Sitzung (VA nach der Sitzung, Umfragen und CSAT)

Wenn ein Live-Chat oder Sprachanruf endet, möchten Contact Center oft Feedback einholen oder automatisierte Follow-ups anbieten. Die Contact Center AI Platform unterstützt drei Arten von Aktivitäten nach einer Sitzung:

  1. Virtueller Agent nach der Sitzung (virtueller Agent): Ein automatisierter Chatbot, der die Unterhaltung fortsetzt, nachdem der menschliche Agent die Verbindung getrennt hat.

  2. Umfragen: Ein Formular mit mehreren Fragen, das auf die jeweilige Warteschlange zugeschnitten ist.

  3. CSAT (Kundenzufriedenheit): Eine Bewertung (z. B. 1–5 Sterne) und optionales Textfeedback.

Hierarchie erzwingen

Es ist üblich, dass Administratoren im Portal sich überschneidende Regeln konfigurieren (z. B. die globale Aktivierung von CSAT, aber auch die Aktivierung eines virtuellen Agenten nach der Sitzung für die Warteschlange „Abrechnung“).

Was das SDK bietet: Eine strikte Konfliktlösungs-Engine. Das SDK wertet die Portalregeln aus und sorgt dafür, dass pro Sitzung nur ein Ablauf nach der Sitzung ausgelöst wird. Dabei wird die folgende Hierarchie strikt eingehalten:

  • Priorität nach der Sitzung: virtueller Kundenservicemitarbeiter nach der Sitzung > Umfragen > Kundenzufriedenheit.

    • Beispiel: Wenn sowohl die Kundenzufriedenheit als auch der virtuelle Agent nach der Sitzung für eine Warteschlange aktiviert sind, sieht der Nutzer nur den virtuellen Agenten nach der Sitzung.

Was Sie erstellen: Einen Listener, der auf das Ende der Sitzung wartet, das SDK fragt, welcher Ablauf die Hierarchiebewertung gewonnen hat, und den entsprechenden Bildschirm zeichnet. Sie müssen keine komplexe if-else-Logik schreiben, um herauszufinden, welche Variante gewinnt. Das SDK übernimmt diese Berechnung für Sie.

Implementierungsbeispiel: In diesem Snippet wird gezeigt, wie Ihre App das Ende einer Sitzung erfassen und das SDK fragen sollte, was als Nächstes zu tun ist.

// Called when the active chat or call ends
func handleSessionEnded(postSessionFlow: PostSessionFlow?) {
    // 1. Check if there is a required post-session flow.
    //    The SDK has already calculated the hierarchy (virtual agent > Survey > CSAT).
    guard let flow = postSessionFlow else {
        // No feedback required. Safely close the support UI.
        closeSupportExperience()
        return
    }
    // 2. Route to the winning flow returned by the SDK.
    switch flow.type {
    case .virtualAgent:
        transitionToPostSessionVA()
    case .survey:
        showSurveyScreen(flow)
    case .csat:
        showCSATScreen(flow)
    }
}

Übergang zur Phase nach der Session

Unabhängig davon, welcher Ablauf die Hierarchie gewinnt, müssen Sie zwei freigegebene Lebenszyklusmethoden für chatService aufrufen, um der CCAI Platform-Plattform zu signalisieren, dass die Phase nach der Sitzung begonnen hat.

Was das SDK bietet: Lebenszyklusmethoden, um die Sitzung in die Phase nach der Sitzung zu überführen und durch diese Phase zu leiten (startPostSession, readyPostSession).

Was du erstellst: Die Orchestrierungslogik, die diese Methoden an den richtigen Stellen im UI-Ablauf nach der Sitzung aufruft.

Implementierungsbeispiel: Mit diesem Code wird die Sitzung durch die beiden Lebenszyklusphasen nach der Sitzung geführt.

// Step 1: Start the post-session process (updates status to "in_progress")
do {
    let postSessionResponse = try await CCAI.shared.chatService?.startPostSession()
    if let response = postSessionResponse {
        print("Post-session started successfully: \\(response.id)")
    }
} catch {
    print("Failed to start post-session: \\(error)")
}

// Step 2: Signal that post-session is ready (updates status to "ready")
do {
    let readyResponse = try await CCAI.shared.chatService?.readyPostSession()
    if let response = readyResponse {
        print("Post-session ready: \\(response.id)")
    }
} catch {
    print("Failed to prepare post-session: \\(error)")
}

Nachdem die Plattform den Übergang bestätigt hat, fahren Sie mit dem spezifischen Ablauf fort.

Felder für den Status nach der Sitzung in „ChatResponse“

Zwei Orchestrierungsfelder nach der Sitzung in ChatResponse steuern die Übergangslogik:

  • postSessionTransferStatus: String?: Der aktuelle Status der Übertragung nach der Sitzung (z. B. "in_progress", "ready", "completed"). Die Plattform steuert die Orchestrierungs-Zustandsmaschine über dieses Feld: startPostSession() verschiebt sie zu "in_progress", readyPostSession() verschiebt sie zu "ready" und Sie sehen diesen Wert in nachfolgenden ChatResponse-Nutzlasten (über chatReceived), um den Übergang auf der Plattformseite zu bestätigen.

  • postSessionOptInRequired: Bool?: Gibt an, ob der Nutzer den Ablauf nach der Sitzung explizit aktivieren muss, bevor er ausgeführt wird. Wenn true, zeige in deiner Benutzeroberfläche eine Aufforderung zur Einwilligung an und rufe startPostSession() erst auf, nachdem der Nutzer zugestimmt hat. Wenn false oder nil, ist die Opt-in-Prüfung nicht erforderlich und Sie können direkt zum Ablauf nach der Sitzung übergehen.

func orchestratePostSession(from chat: ChatResponse) async {
    // 1. Honor opt-in gating if required
    if chat.postSessionOptInRequired == true {
        let consented = await presentPostSessionOptIn()
        guard consented else {
            closeSupportExperience()
            return
        }
    }
    // 2. Drive the state machine
    _ = try? await CCAI.shared.chatService?.startPostSession()   // → "in_progress"
    _ = try? await CCAI.shared.chatService?.readyPostSession()   // → "ready"
    // 3. Observe postSessionTransferStatus on subsequent chatReceived
    //    emissions to confirm the transfer completed before rendering the
    //    winning flow.
}
  • postSessionRequired gibt an, ob für die Sitzung ein Post-Session-Flow konfiguriert ist.

  • postSessionOptInRequired gibt an, ob vor der Ausführung die ausdrückliche Nutzereinwilligung erforderlich ist.

  • postSessionTransferStatus gibt an, wo sich die Plattform im Übergangslebenszyklus befindet.

Alle drei sind unabhängig voneinander – prüfen Sie immer alle drei.

Virtueller Kundenservicemitarbeiter nach der Sitzung (höchste Priorität)

Was das SDK bietet: Den Übergangszustand, um die Sitzung von einem menschlichen Kundenservicemitarbeiter zurück zu einem automatisierten Bot zu verschieben, und das Routing der Nachrichten des Bots.

Was Sie erstellen: Nichts völlig Neues. Da der virtuelle Agent nach der Sitzung als Chat fungiert, lassen Sie Ihre vorhandene benutzerdefinierte Chat-UI geöffnet und die eingehenden automatisierten Nachrichten genauso verarbeiten wie die Nachrichten des menschlichen Kundenservicemitarbeiters.

Beispiel für die Implementierung: Wenn das SDK einen Übergang zu einem VA nach der Sitzung signalisiert, aktualisieren Sie die Chat-UI, um die Änderung widerzuspiegeln.

func transitionToPostSessionVA() {
    // Keep your Chat UI open, but update the visual context
    myChatUI.insertSystemDivider("You are now speaking with our Virtual Assistant")
    myChatUI.updateAgentAvatar(to: .botIcon)
    // The SDK will automatically start piping the VA's messages into
    // your standard chat message listeners.
}

Umfragen (mittlere Priorität)

Was das SDK bietet: Das rateService stellt Methoden bereit, um Umfragefragen abzurufen und Antworten für eine Kommunikationssitzung zu senden. Die Umfragefragen werden vom Administrator für jede Warteschlange konfiguriert und können mehrere Fragetypen enthalten (CSAT, Sternebewertung, Freiformtext, Aufzählung, numerische Skala). In den Beispielen in diesem Abschnitt wird ein Chat (communicationType: "chats") bewertet. Übergeben Sie für einen Anruf die ID des Anrufs und "calls".

Was Sie erstellen: Ein dynamisches Formular, das die Umfrage abruft, die Fragen durchläuft, die entsprechende Benutzeroberfläche (z. B. Optionsfelder, Sternebewertungen oder Textfelder) für jede Frage rendert, prüft, ob die erforderlichen Felder ausgefüllt sind, und die Antworten für die Rücksendung verpackt.

Schlüsseltypen:

// Survey response from getSurvey()
public struct Survey {
    public let id: Int?
    public let lang: String?
    public let questions: [SurveyQuestion]
    public let signOffDisplayText: String?  // "Thank you" message to show after submission
}

// Request payload for submitSurvey()
public struct SurveyRequest {
    public let answers: [Int: String]  // Maps question IDs to answer values
}

Implementierungsbeispiel: Mit diesem Code werden Umfragefragen aus dem rateService abgerufen, in einem benutzerdefinierten View Controller gerendert und die Antworten gesendet.

func showSurveyScreen(communicationId: Int64) async {
    guard let rateService = CCAI.shared.rateService else { return }
    do {
        // 1. Fetch the survey questions for this session
        let survey = try await rateService.getSurvey(
            communicationId: communicationId,
            communicationType: "chats"
        )
        // 2. Present your custom survey UI
        //    Note: survey.questions is non-optional ([SurveyQuestion]) on iOS -
        //    no need to use .orEmpty() / ?? [] safeguards.
        let surveyVC = MyCustomSurveyViewController(questions: survey.questions)
        surveyVC.onSubmit = { answersDict in
            Task {
                do {
                    // 3. Submit the answers
                    let request = SurveyRequest(answers: answersDict)
                    try await rateService.submitSurvey(
                        communicationId: communicationId,
                        communicationType: "chats",
                        answers: request
                    )
                    rateService.clearRateTarget()
                    self.closeSupportExperience()
                } catch {
                    print("Failed to submit survey: \\(error)")
                }
            }
        }
        present(surveyVC, animated: true)
    } catch {
        print("Failed to load survey: \\(error)")
        closeSupportExperience()
    }
}

CSAT – Kundenzufriedenheit (niedrigste Priorität)

Was das SDK bietet: Das rateService stellt eine rate()-Methode bereit, mit der ein CSAT-Wert und optionales Feedback für eine Kommunikationssitzung gesendet werden können. Die Bewertung ist in der Regel ein ganzzahliger Wert von 1 bis 5.

Was Sie erstellen: Den visuellen Bewertungsbildschirm (z. B. eine Reihe von Sternen, auf die getippt werden kann, oder eine Skala von 1 bis 5), ein Feld, wenn Feedback erlaubt ist, und einen Button Senden.

Schlüsseltypen:

// Request payload for rate()
public struct RatingRequest {
    public let rating: Int?       // Typically 1-5
    public let feedback: String?  // Optional qualitative feedback
}

Beispiel für die Implementierung: Nachdem der Nutzer auf eine Sternebewertung getippt und sein Feedback geschrieben hat, übergibst du diese Werte an die rateService.

func submitCSATFeedback(communicationId: Int64, rating: Int, comment: String?) {
    guard let rateService = CCAI.shared.rateService else { return }
    submitButton.startLoading()
    Task {
        do {
            let request = RatingRequest(rating: rating, feedback: comment)
            try await rateService.rate(
                communicationId: communicationId,
                communicationType: "chats",
                request: request
            )
            rateService.clearRateTarget()
            showThankYouScreen()
        } catch {
            showError("Failed to submit feedback. Please try again.")
        }
    }
}

Chattranskripte herunterladen

Was das SDK bietet: Methoden zum Herunterladen des Chatprotokolls als PDF – entweder als Datei-URL oder als Roh-Data im Arbeitsspeicher (nur iOS).

Was Sie erstellen: Den Download-Button in Ihrer Benutzeroberfläche und die Logik für die Dateiverwaltung (Speichern, Freigeben oder Vorschau).

Implementierungsbeispiel: Dieser Code zeigt beide Ansätze zum Herunterladen von Transkripten: das Speichern in einer Datei-URL und das Abrufen von PDF-Rohdaten im Arbeitsspeicher.

// Option 1: Download to a file destination
let documentsPath = FileManager.default.urls(for: .documentDirectory, in: .userDomainMask)[0]
let transcriptURL = documentsPath.appendingPathComponent("chat_transcript.pdf")
do {
    try await CCAI.shared.chatService?.downloadChatTranscript(to: transcriptURL)
    print("Transcript downloaded to: \\(transcriptURL.path)")
} catch {
    print("Failed to download transcript: \\(error)")
}

// Option 2: Get the PDF data directly (iOS only)
do {
    let transcriptData = try await CCAI.shared.chatService?.downloadChatTranscriptData()
    if let data = transcriptData {
        // Use the PDF data directly (for example, display in a preview, email it)
        print("Transcript data size: \\(data.count) bytes")
    }
} catch {
    print("Failed to download transcript data: \\(error)")
}

Die Methode downloadChatTranscriptData() ist nur für iOS verfügbar und gibt die Roh-PDF-Datei Data direkt zurück, sodass Sie sie verwenden können, ohne sie zuerst auf dem Laufwerk zu speichern. Die Methode downloadChatTranscript(to:) lädt die Datei in eine angegebene Datei-URL mit integrierter Wiederholungslogik herunter.

Sprachen und Lokalisierung

Da Sie mit dem Headless Mobile SDK eine benutzerdefinierte Benutzeroberfläche erstellen, sind Sie für die Übersetzung der Schaltflächen, Menüs und benutzerdefinierten Benachrichtigungen Ihrer App verantwortlich.

Warum muss das CCAI Platform SDK die Sprache des Nutzers kennen?

  1. Warteschlangen-Routing: Die CCAI Platform verwendet den Sprachcode, um den Nutzer an einen Agenten weiterzuleiten, der diese Sprache spricht.

  2. Systemnachrichten: Automatische Nachrichten, die vom CCAI Platform-Backend generiert werden (z. B. „Ein Kundenservicemitarbeiter wird sich in Kürze bei Ihnen melden“), werden in der aktiven Sprache zugestellt.

Language Service APIs

Was das SDK bietet: Ein Lese- und Schreibattribut languageCode für die aktive SDK-Sprache (Standard "en") und getPortalAvailableLanguageCodes(), eine asynchrone Methode, die die Sprachen zurückgibt, die Ihre Administratoren im CCAI Platform-Portal aktiviert haben.

Sie erstellen: eine Benutzeroberfläche für die Sprachauswahl (wenn Nutzer die Sprache manuell auswählen sollen) und die Logik, um die Sprache vor Beginn einer Sitzung festzulegen.

// Read the active language
let currentLanguage = CCAI.shared.languageService?.languageCode

// Set the active language before the user starts a support session
CCAI.shared.languageService?.languageCode = "es"
// Languages your admins enabled in the UJET Portal (from an async context)
let enabledLanguages = await CCAI.shared.languageService?.getPortalAvailableLanguageCodes() ?? []

Das SDK stellt keine feste Liste der unterstützten Sprachen bereit. Verwenden Sie zum Erstellen einer Sprachauswahl getPortalAvailableLanguageCodes() oder die Sprachenliste aus companyService.get().

SDK-Sprache festlegen (Regel vor der Sitzung)

Was das SDK bietet: Ein languageService, das die von Ihnen angeforderte Sprache mit den Sprachen vergleicht, die Ihre Administratoren im CCAI Platform-Portal aktiviert haben.

Was du erstellen musst: Wenn du Nutzern erlauben möchtest, die Sprache manuell zu überschreiben (anstatt sich auf die Standardeinstellungen ihres Geräts zu verlassen), musst du die Benutzeroberfläche für die Auswahl (z. B. ein Drop-down-Menü) erstellen und dafür sorgen, dass sie nur zugänglich ist, bevor sie auf einen Supportkanal tippen.

Implementierungsbeispiel: Dieser Code zeigt, wie Sie die Sprache des SDK mithilfe von ISO 639-Standard-Sprachcodes explizit überschreiben, z. B. "es" für Spanisch oder "fr" für Französisch. Die bevorzugte Sprache wird während der SDK-Initialisierung in der Struktur InitOptions mit dem Parameter languageCode festgelegt. Sie können sie auch beim erneuten Initialisieren des SDK festlegen:

// Set language during initialization
let options = InitOptions(
    key: "YOUR_COMPANY_KEY",
    urlHost: "your_subdomain.ccaiplatform.com",
    delegate: self,
    languageCode: "es"  // for example, "es" for Spanish, "fr" for French
)
do {
    try CCAI.shared.initialize(options: options)
} catch {
    print("Failed to initialize CCAI: \\(error)")
}

Sie können die Sprache auch beim Abrufen von Warteschlangenmenüs übergeben:

let (menus, isDirectAccess) = try await CCAI.shared.queueMenuService?.get(
    key: nil,
    language: "es"  // Request menus in Spanish
)

Wie die CCAI Platform die endgültige Sprache bestimmt

Wenn Sie keine Sprache explizit festlegen, benötigt das SDK trotzdem einen Sprachcode für das Routing und für Systemnachrichten. Für ein möglichst vorhersehbares Verhalten sollten Sie es selbst festlegen, bevor der Nutzer eine Supportsitzung startet.

Verwenden Sie diese Prioritätsreihenfolge:

  1. Explizite Sprache (empfohlen): Wenn Sie eine Sprache in InitOptions.languageCode festlegen, wird diese vom SDK verwendet.

  2. Gerätesprache (falls verfügbar): Wenn Sie keine Sprache explizit festlegen, verwendet das SDK die in den iOS-Einstellungen des Nutzers ausgewählte Sprache (Einstellungen > Allgemein > Sprache & Region), sofern diese Sprache für Ihre Instanz im CCAI Platform-Portal aktiviert ist.

  3. Fallback auf übergeordneten Dialekt: Wenn das Gerät auf einen regionalen Dialekt eingestellt ist, der nicht aktiviert ist (z. B. es-CU), die Basissprache aber aktiviert ist (es), greift das SDK auf die übergeordnete Sprache zurück.

  4. Englisch als Fallback: Wenn keine der vorherigen Optionen verfügbar ist, wird das SDK auf Englisch zurückgesetzt.

Fehlerbehandlung, Fallback und Sitzungsverwaltung

Selbst bei den robustesten Anwendungen kann es zu Verbindungsabbrüchen, fehlenden Abhängigkeiten oder Authentifizierungsproblemen kommen. Das Headless Mobile SDK ist so konzipiert, dass es diese zugrunde liegenden Plattformprobleme erkennt und an Ihre App weiterleitet. So können Sie sie in Ihrer benutzerdefinierten Benutzeroberfläche ordnungsgemäß verarbeiten oder sich auf die automatisierten Fallbacks der CCAI Platform verlassen.

Umgang mit SDK-Fehlern

Alle asynchronen Methoden im Headless Mobile SDK für iOS können Fehler auslösen.

Was das SDK bietet: Asynchrone Dienstmethoden wie chatService, queueMenuService und authService, die Swift-Error-Werte ausgeben, wenn ein Vorgang fehlschlägt. Das iOS SDK definiert keinen einzelnen vereinheitlichenden CCAIError-Typ. Spezifische Fehlermodi werden neben den Standardfehlern der Foundation durch fokussierte Fehlertypen (z. B. NetworkError, ScreenShareError, ChatProviderError) ausgedrückt. Bei den meisten Integrationen reicht es aus, den allgemeinen Error abzufangen und error.localizedDescription zu lesen.

Was Sie erstellen: do/catch-Fehlerbehandlung für jeden SDK-Dienstaufruf, wobei eine für Nutzer sichtbare Nachricht angezeigt und gegebenenfalls eine Wiederherstellungslogik ausgelöst wird (z. B. erneute Authentifizierung bei authService-Fehlern).

Implementierungsbeispiel: In diesem Code wird ein SDK-Aufruf in einen Standard-Swift-do/catch eingeschlossen. Die lokalisierte Beschreibung des Fehlers wird für die Anzeige und das Logging gelesen.

do {
    let result = try await someAsyncMethod()
    // Handle success
} catch {
    // Handle any error thrown by the SDK (examples: auth failure, network, invalid config)
    print("SDK error: \\(error.localizedDescription)")
    showErrorToUser(error.localizedDescription)
}

Best Practices:

  • Verpacken Sie jeden SDK-Dienstaufruf in do/catch. Häufige Fehlerursachen sind abgelaufene Authentifizierungstokens (ccaiShouldAuthenticate() noch einmal auslösen), ungültige menuId-Werte, fehlende Modulabhängigkeiten (z. B. Aufruf von chatService vor initializeChat()) sowie Netzwerk- oder Systemprobleme.

  • Wenn Sie nach bestimmten Fehlertypen verzweigen müssen, führen Sie einen Musterabgleich mit den konkreten Typen durch, die vom relevanten Subsystem ausgegeben werden (z. B. ScreenShareError vom Dienst für die Bildschirmfreigabe).

  • Wenn Sie die Fehlerdetails während der Entwicklung protokollieren, können Sie die Ursachen schnell ermitteln.

Sitzungen prüfen und löschen

Da der Lebenszyklus Ihrer App vom Support-Lebenszyklus der CCAI Platform getrennt ist, müssen Sie den Sitzungsstatus verwalten, insbesondere bei Nutzerabmeldungen.

Was das SDK bietet: Dienstprogramm-APIs, mit denen geprüft werden kann, ob eine Support-Sitzung noch läuft (auch nach einem Neustart oder erzwungenen Beenden der App), und eine sichere Methode, um alle im Cache gespeicherten SDK-Status zu löschen, die mit einem bestimmten Endnutzer verknüpft sind – vor allem das im Cache gespeicherte Authentifizierungstoken, das im iOS-Schlüsselbund gespeichert ist.

Was Sie erstellen: Preflight-Prüfungen, bevor Sie versuchen, neue Sitzungen zu starten, und Bereinigungsroutinen, die ausgelöst werden, wenn sich ein Nutzer von Ihrer Haupt-App abmeldet.

Implementierungsbeispiel (Bereinigung bei Abmeldung): Beendet alle aktiven Sitzungen, löscht das im Cache gespeicherte Authentifizierungstoken und den Endnutzerdatensatz aus dem SDK, löscht lokale App-Daten und ruft den Anmeldebildschirm auf. So wird verhindert, dass der nächste angemeldete Nutzer die SDK-Sitzung des vorherigen Nutzers übernimmt.

func handleUserLogout() {
    Task {
        // 1. Check for an in-progress session and end it cleanly
        if let activeChat = try? await CCAI.shared.chatService?.getLastChatInProgress() {
            try? await CCAI.shared.chatService?.endChat()
            print("Ended active chat \\(activeChat.id) before logout.")
        }
        // 2. Clear the cached auth token from the iOS Keychain
        //    (prevents the next user from inheriting the previous session)
        CCAI.shared.authService?.updateAuthToken(nil)
        // 3. Clear the end user record
        CCAI.shared.endUserService?.updateEndUser(nil)
        // 4. Wipe your own app's user data
        MyAuthManager.shared.clearLocalData()
        // 5. Navigate back to the login screen
        await MainActor.run {
            transitionToLoginScreen()
        }
    }
}

Endnutzerdienste (nur iOS)

Was das SDK bietet: Einen Lese- und Schreibdienst (endUserService) für den Zugriff auf und die Aktualisierung der Profilinformationen des authentifizierten Endnutzers (Name, E-Mail-Adresse, Telefonnummer, Kennung). Dieser Dienst ist nur für iOS verfügbar.

Was Sie erstellen: Die Integration zwischen dem Nutzer- und Authentifizierungssystem Ihrer App und dem Endnutzerdatensatz des SDK, einschließlich Aktualisierungen bei der Anmeldung und Bereinigung bei der Abmeldung (siehe Sitzungen prüfen und löschen weiter oben in diesem Artikel).

EndUser-Datenstruktur

public struct EndUser: Codable {
    public let id: Int?
    public let name: String?
    public let identifier: String?
    public let email: String?
    public let phone: String?

    public var displayName: String { name ?? email ?? identifier ?? "Customer" }
}

Zugriff auf Endnutzerinformationen

Implementierungsbeispiel: Rufen Sie das Profil des aktuellen Endnutzers mit der schreibgeschützten Property endUser ab.

if let user = CCAI.shared.endUserService?.endUser {
    print("Current user: \\(user.displayName)")
    print("Email: \\(user.email ?? "N/A")")
    print("Phone: \\(user.phone ?? "N/A")")
}

Endnutzerinformationen werden aktualisiert

Implementierungsbeispiel: Aktualisieren Sie den Endnutzerdatensatz mit neuen Profildaten oder löschen Sie ihn bei der Abmeldung.

// Update end user information
let newUser = EndUser(
    id: 123,
    name: "John Doe",
    identifier: "user123",
    email: "john@example.com",
    phone: "+1234567890"
)
CCAI.shared.endUserService?.updateEndUser(newUser)

// Clear end user information
CCAI.shared.endUserService?.updateEndUser(nil)

Benutzerdefinierte Daten

Was das SDK bietet: Einen Mechanismus zum Anhängen strukturierter Metadaten an Chatsitzungen, entweder als signierte JWTs (von Ihrem Backend verifiziert) oder als unsignierte Nutzlasten (direkt im Client festgelegt).

Was du erstellst: Die Logik für die Datenerhebung in deiner App und für signierte Daten den JWT-Signierungsendpunkt auf deinem Backend-Server (das vollständige Authentifizierungs- und JWT-Nutzlastschema findest du unter Endnutzer authentifizieren).

Signierte benutzerdefinierte Daten

Für signierte benutzerdefinierte Daten wird ein JWT-Token verwendet, das mit dem Unternehmens-Secret auf Ihrem Backend-Server signiert ist. Dies ist die sichere Methode, um vertrauliche oder vertrauenswürdige Daten zu übergeben.

Implementierungsbeispiel: Erstellen Sie ein signiertes benutzerdefiniertes Datenobjekt aus einem JWT, das auf Ihrem Backend generiert wurde.

// JWT signed with company secret (signing must happen on your backend)
let customData = CustomData(signed: "header.payload.signature")

Nicht signierte benutzerdefinierte Daten

Nicht signierte benutzerdefinierte Daten werden direkt im Client mit CustomDataPayload und CustomDataItem festgelegt.

Implementierungsbeispiel: Erstellen Sie eine unsignierte Nutzlast mit sichtbaren und für den Agenten ausgeblendeten Datenelementen.

var payload = CustomDataPayload()
payload["user_name"] = CustomDataItem(
    label: "Name",
    value: "John"
)
payload["user_age"] = CustomDataItem(
    label: "Age",
    value: 30,
    type: .number,
    invisibleToAgent: true
)
let customData = CustomData(unsigned: payload)

Benutzerdefinierte Datenelemente unterstützen die folgenden Eigenschaften:

  • label: Das Label, das dem Agenten angezeigt wird.

  • value: Der Datenwert (Beispiele: String, Int, Bool).

  • type: Datentyp (.string, .number, .date, .url, .boolean).

  • invisibleToAgent: Bei true werden die Daten vor Kundenservicemitarbeitern verborgen, sind aber für Routing und Analysen verfügbar.

Benutzerdefinierte Daten in Chatanfragen verwenden

Implementierungsbeispiel: Benutzerdefinierte Daten beim Starten einer Chatsitzung anhängen.

let chatRequest = ChatRequest(
    menuId: 123,
    lang: "en",
    customData: customData
)
do {
    try await CCAI.shared.chatService?.start(request: chatRequest)
} catch {
    print("Failed to start chat: \(error)")
}

Übertragung des externen Chats

Was das SDK bietet: Eine Datenstruktur (ExternalChatTransfer), um den Namen eines vorherigen Agents und das Transkript der Unterhaltung an eine neue CCAI Platform-Sitzung zu übergeben.

Was Sie erstellen: Den Migrationsablauf, der Kontext aus Ihrem externen Chatsystem extrahiert und für das SDK verpackt.

Implementierungsbeispiel: Mit diesem Code wird ein externes Chatübertragungsobjekt mit dem Namen des vorherigen Kundenservicemitarbeiters erstellt und an die benutzerdefinierten Daten der Sitzung angehängt.

let transfer = ExternalChatTransfer(
    agent: ExternalChatAgent(name: "John Smith"),
    transcript: []
)

// Attach to your custom data payload
var payload = CustomDataPayload()
payload.externalChatTransfer = transfer
let customData = CustomData(unsigned: payload)

Das ist nützlich, wenn ein Nutzer von einem Drittanbieter-Chatsystem zu einer CCAI Platform-Sitzung migriert wird, da der Kontext der Unterhaltung für den empfangenden Agenten erhalten bleibt.

Combine-Integration (reaktive Programmierung)

Was das SDK bietet: Publisher, die Echtzeit-SDK-Ereignisse (eingehende Nachrichten, Statusänderungen bei der Bildschirmfreigabe) ausgeben, werden als beobachtbare Streams kombiniert.

Was Sie erstellen: Reaktive UI-Bindungen, die diese Publisher abonnieren und Ihre SwiftUI- oder UIKit-Ansichten entsprechend aktualisieren.

Chatnachrichten

Das chatService stellt Combine-Publisher bereit, um Echtzeit-Chat-Ereignisse zu beobachten.

Publisher Emittiert
messagesReceived Listen eingehender Chatnachrichten (von Kundenservicemitarbeitern, virtuellen Kundenservicemitarbeitern oder dem System).
typingEvent Wenn ein Nutzer oder ein Agent tippt.
memberEvent Wenn ein Nutzer oder ein KI-Agent dem Chat beitritt oder ihn verlässt (einschließlich Weiterleitungen und Trennungen von KI-Agenten).
stateChanged Statusänderungen des Chatanbieters (Verbindung wird hergestellt, verbunden, getrennt, Fehler).
chatReceived Chatantwortdaten, wenn ein Chat empfangen oder aktualisiert wird (einschließlich Statusänderungen, Zuweisung von Kundenservicemitarbeitern und Status nach der Sitzung).

chatService stellt auch transferEvent für Übertragungsereignisse und networkConnectivityChanged für die Gerätekonnektivität bereit. Eine vollständige Liste der Typsignaturen und aller verfügbaren Publisher finden Sie in der API-Referenz für das Headless Mobile SDK für iOS.

Implementierungsbeispiel

import Combine
import Foundation
import CCAIKit
import CCAIChat

private var cancellables = Set<AnyCancellable>()

// 1. Incoming messages
CCAI.shared.chatService?.messagesReceived
    .receive(on: DispatchQueue.main)
    .sink { messages in
        for message in messages {
            updateChatUI(with: message)
        }
    }
    .store(in: &cancellables)

// 2. Typing indicators
CCAI.shared.chatService?.typingEvent
    .receive(on: DispatchQueue.main)
    .sink { event in
        switch event {
        case .started:
            showTypingIndicator()
        case .ended:
            hideTypingIndicator()
        default:
            break
        }
    }
    .store(in: &cancellables)

// 3. Member join/leave
// Note: the associated value on .joined / .left is `identity: String?` (the
// member's identity, not a full Member struct).
CCAI.shared.chatService?.memberEvent
    .receive(on: DispatchQueue.main)
    .sink { event in
        switch event {
        case .joined(let identity):
            print("Member joined: \(identity ?? "Unknown")")
        case .left(let identity):
            print("Member left: \(identity ?? "Unknown")")
        default:
            break
        }
        // Refresh chat status after member changes
        Task { try? await CCAI.shared.chatService?.checkStatus() }
    }
    .store(in: &cancellables)

// 4. Chat provider state changes
CCAI.shared.chatService?.stateChanged
    .receive(on: DispatchQueue.main)
    .sink { state in
        // Update UI based on connection state (connecting, connected, etc.)
        updateConnectionStatus(state)
        Task { try? await CCAI.shared.chatService?.checkStatus() }
    }
    .store(in: &cancellables)

// 5. Chat metadata updates (agent assignment, status changes)
CCAI.shared.chatService?.chatReceived
    .receive(on: DispatchQueue.main)
    .sink { chat in
        guard let chat = chat else { return }
        updateAgentInfo(chat.agent)
        handlePostSessionIfNeeded(chat)
    }
    .store(in: &cancellables)

Fehlgeschlagene Teilnahmeversuche

Wenn das SDK dem Chat nicht beitreten kann, veröffentlicht stateChanged .error mit ChatError.failedToJoin. Wenn der Chat nach den Wiederholungsversuchen des SDKs immer noch nicht verfügbar ist, wird stattdessen .error mit ChatError.failedToGetChat oder ChatError.failedToGetChatId veröffentlicht, wenn das SDK die Chat-ID nicht abrufen konnte. Diese Fehler werden von diesem Publisher ausgegeben, nicht von start(request:) oder resumeChat(_:). Ein do/catch um diese Aufrufe herum fängt sie also nicht ab. Verarbeiten Sie sie in Ihrem stateChanged-Abonnenten:

import Foundation
import CCAIKit
import CCAIChat

CCAI.shared.chatService?.stateChanged
    .receive(on: DispatchQueue.main)
    .sink { state in
        if case .error(let error, _, _) = state,
           error == .failedToJoin || error == .failedToGetChat || error == .failedToGetChatId {
            showError("We couldn't connect you to the chat. Please try again.")
        }
    }
    .store(in: &cancellables)

Status der Bildschirmfreigabe

Implementierungsbeispiel: Überwachen Sie Änderungen am Status der Bildschirmfreigabe reaktiv und reagieren Sie auf jede Sitzungsphase.

CCAI.shared.screenShareService?.statePublisher
    .receive(on: DispatchQueue.main)  // Ensure UI updates run on the main thread
    .sink { state in
        switch state {
        case .none:
            print("No screen share session")
        case .pending:
            print("Screen share pending")
        case .authorizing:
            print("Screen share authorizing")
        case .active:
            print("Screen share active")
        case .ended:
            print("Screen share ended")
        }
    }
    .store(in: &cancellables)

Überlegungen zum Threading

Das Headless Mobile SDK für iOS ist für die strukturierte Nebenläufigkeit (async/await) von Swift konzipiert und weitgehend main-safe. Bei Headless-Integrationen sind jedoch wichtige Threading-Aspekte zu beachten.

Threadsicherheit

Alle SDK-Methoden sind threadsicher und können von jedem Thread aus aufgerufen werden. Netzwerkvorgänge werden asynchron mit dem Async- und Await-Muster von Swift ausgeführt. Sie unterbrechen die aufrufende Aufgabe, ohne den Thread zu blockieren.

// Safe to call from the main thread - suspends, does not block
Task {
    let result = try await CCAI.shared.queueMenuService?.get(
        key: nil,
        language: "en"
    )
    // Back on the calling context after suspension
    displayQueueMenu(result)
}

CCAIDelegate und asynchrone Authentifizierung

Die Methode ccaiShouldAuthenticate() in Ihrer CCAIDelegate ist eine asynchrone Funktion, sodass Sie darin sicher Netzwerkaufrufe ausführen können:

func ccaiShouldAuthenticate() async -> String? {
    // This runs in an async context - safe to call async functions
    guard let jwt = await signJWTRemotely() else { return nil }
    return try? await CCAI.shared.authService?.authenticate(jwt)
}

UI-Updates von SDK-Callbacks

Wenn Sie SDK-Ereignisse mit Combine-Publishern beobachten, müssen UI-Updates im Hauptthread erfolgen. Der Chatdienst und die Publisher für die Bildschirmfreigabe sind Rohsubjekte, die intern keinen Hauptthread-Planer anwenden. Fügen Sie daher immer .receive(on: DispatchQueue.main) vor einem sink ein, das die Benutzeroberfläche aktualisiert:

// Explicitly hop to the main thread before updating UI
CCAI.shared.chatService?.messagesReceived
    .receive(on: DispatchQueue.main)
    .sink { [weak self] messages in
        // Safe to update UI here
        self?.chatTableView.reloadData()
    }
    .store(in: &cancellables)

Verwenden Sie für asynchrone SDK-Aufrufe @MainActor (in Swift-Nebenläufigkeit / asynchronem und await-Code) oder DispatchQueue.main.async (in Grand Central Dispatch / Closure-basiertem Code), um zum Hauptthread zurückzukehren, bevor Sie die Benutzeroberfläche aktualisieren:

// Async SDK calls - use @MainActor to update UI
func refreshChatStatus() {
    Task {
        do {
            try await CCAI.shared.chatService?.checkStatus()
            await MainActor.run {
                updateStatusIndicator()
            }
        } catch {
            await MainActor.run {
                showError(error.localizedDescription)
            }
        }
    }
}

Wenn Sie Daten aus einem Hintergrundkontext erfassen, wechseln Sie explizit zurück:

Task.detached(priority: .userInitiated) {
    // Processing off main thread
    let processed = heavyProcessing()
    await MainActor.run {
        // Update UI on Main thread
        updateChatUI(processed)
    }
}

Initialisierungs-Threading

Die SDK-Initialisierung (CCAI.shared.initialize(options:)) muss beim Start der App in der application(_:didFinishLaunchingWithOptions:)-Methode des AppDelegate aufgerufen werden. Die Initialisierung des Funktionsmoduls (initializeChat(), initializeScreenShare()) sollte ebenfalls zu diesem Zeitpunkt erfolgen, bevor Dienstaufrufe erfolgen.

// Always initialize on the main thread during app launch
func application(
    _ application: UIApplication,
    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
) -> Bool {
    let options = InitOptions(
        key: "YOUR_COMPANY_KEY",
        urlHost: "your_subdomain.ccaiplatform.com",
        delegate: self,
        languageCode: "en"
    )
    do {
        try CCAI.shared.initialize(options: options)
        CCAI.shared.initializeChat()
    } catch {
        print("Failed to initialize CCAI: \\(error.localizedDescription)")
    }
    return true
}

Speicherverwaltung

Eine ordnungsgemäße Speicherverwaltung ist wichtig, um Lecks zu vermeiden und SDK-Ressourcen sauber zu entfernen.

Referenzen delegieren

Das Headless Mobile SDK für iOS verwendet schwache Referenzen für alle Delegaten, um Retain-Zyklen zu verhindern. In den meisten Fällen müssen Sie Delegierte nicht manuell auf „nil“ setzen, aber es ist eine gute Praxis, dies in deinit zu tun.

Abbrechbare Vorgänge kombinieren

Speichern Sie Combine-Abos immer in einem Set<AnyCancellable> und bereinigen Sie sie, wenn die Zuordnung Ihres Ansichtscontrollers oder Ansichtsmodells aufgehoben wird:

import Combine

class ChatViewModel {
    private var cancellables = Set<AnyCancellable>()

    init() {
        // Subscribe to chat messages
        CCAI.shared.chatService?.messagesReceived
            .sink { messages in
                // Handle new messages
            }
            .store(in: &cancellables)

        // Subscribe to screen share state
        CCAI.shared.screenShareService?.statePublisher
            .sink { state in
                // Handle state changes
            }
            .store(in: &cancellables)
    }

    deinit {
        // Clean up all subscriptions
        cancellables.removeAll()

        // Nil out delegates
        CCAI.shared.screenShareService?.delegate = nil
    }
}

Best Practices

  • Abbrechbare Objekte speichern: Speichere immer AnyCancellable-Referenzen, um zu verhindern, dass Abos sofort wieder freigegeben werden.

  • Bereinigen Sie deinit: Entfernen Sie alle abbrechbaren Elemente und setzen Sie Delegierte auf „nil“, wenn die Zuordnung Ihres Objekts aufgehoben wird.

  • Vermeiden Sie Retain-Zyklen: Verwenden Sie [weak self] in Closures, die self erfassen. Dadurch wird eine Referenz ohne Eigentümer erstellt, sodass der Closure das Objekt nicht länger als nötig beibehält. So werden Speicherlecks verhindert, wenn die Zuordnung des Objekts aufgehoben wird, bevor der Closure ausgeführt wird:

    CCAI.shared.chatService?.messagesReceived
        .sink { [weak self] messages in
            self?.handleMessages(messages)
        }
        .store(in: &cancellables)
    
  • Dienste werden vom SDK verwaltet: Sie müssen SDK-Dienste nicht manuell freigeben, da sie vom Singleton CCAI.shared verwaltet werden.

Fehlerbehebung

Folgen Sie diesen Vorschlägen, um häufige Probleme zu beheben.

App Store-Einreichung – VoIP-Berechtigung

Wenn Sie Ihre App zur Überprüfung bei Apple einreichen, werden Sie im App Store Folgendes gefragt:

„Verwendet diese App den VoIP-Hintergrundmodus oder PushKit-VoIP-Push-Benachrichtigungen?“

Antworten Sie mit „Ja“. Da das SDK PushKit für eingehende Anrufe und PSTN-basierte Smart Actions verwendet (siehe Für VoIP-Push-Benachrichtigungen (PushKit) registrieren), ist die VoIP-Berechtigung erforderlich. Wenn Sie „Nein“ auswählen oder die Berechtigung weglassen, wird die App abgelehnt oder die Anruf- und Push-Funktion funktioniert nicht.

Build- und Abhängigkeitsprobleme

Problem: Swift Package Manager kann CCAIKit nicht auflösen.

  • Ursache: Die Paket-URL oder der Zweig in Ihren Package.swift- oder Xcode-SPM-Einstellungen ist falsch.

  • Lösung: Achten Sie darauf, dass Ihre SPM-Abhängigkeit die richtige Repository-URL und den richtigen Branch verwendet:

    dependencies: [
        package(url: "https://github.com/UJET/ccai-ios-sdk.git", from: "3.5.0")   
    ]
    

Prüfen Sie, ob der Zweig mit der SDK-Version übereinstimmt, die Sie verwenden möchten. Wenn Xcode das Paket nicht auflösen kann, versuchen Sie es mit File > Packages > Reset Package Caches und dann mit Resolve Package Versions.

Problem: Build-Fehler in einem SwiftUI-Projekt im Zusammenhang mit AppDelegate.

  • Ursache: Das SDK benötigt ein AppDelegate für die Initialisierung und Push-Benachrichtigungs-Delegates, aber reine SwiftUI-Apps haben standardmäßig keines.

  • Lösung: Deklarieren Sie @UIApplicationDelegateAdaptor in Ihrer App-Struktur:

    @main
    struct YourAppName: App {
        @UIApplicationDelegateAdaptor(AppDelegate.self) var appDelegate
        // ...
    }
    

Implementieren Sie dann Ihre AppDelegate-Klasse mit CCAIDelegate-Konformität und Push-Benachrichtigungs-Delegaten, wie unter CCAIDelegate für die Authentifizierung implementieren und für Remote-Benachrichtigungen registrieren beschrieben.

Initialisierungsprobleme

Problem: chatService gibt nil zurück.

  • Ursache: CCAI.shared.initializeChat() wurde nicht oder vor CCAI.shared.initialize(options:) aufgerufen.

  • Lösung: Achten Sie auf die Initialisierungsreihenfolge in Ihrer AppDelegate.application(_:didFinishLaunchingWithOptions:):

    // 1. Initialize the Core SDK
    try CCAI.shared.initialize(options: options)
    // 2. Initialize Chat
    CCAI.shared.initializeChat()
    // 3. Initialize Call (if you use voice)
    CCAI.shared.initializeCall()
    // 4. Initialize Screen Share (optional)
    // CCAI.shared.initializeScreenShare(screenShareOptions)
    

Das Attribut chatService für CCAI.shared hat erst einen Wert, nachdem initializeChat() aufgerufen wurde.

Problem: screenShareService gibt nil zurück.

  • Ursache: CCAI.shared.initializeScreenShare() wurde nicht aufgerufen oder mit ungültigem ScreenShareOptions aufgerufen.

  • Lösung: Achten Sie darauf, dass Sie initializeScreenShare() mit einem gültigen Schlüssel für die Bildschirmfreigabe aufrufen:

    CCAI.shared.initializeScreenShare(ScreenShareOptions(key: "YOUR_SCREEN_SHARE_LICENSE_KEY"))
    

Authentifizierungsprobleme

Problem: Die Authentifizierung schlägt ohne Fehlermeldung fehl oder ccaiShouldAuthenticate() wird nie aufgerufen.

  • Ursache: Der Bevollmächtigte wurde nicht in InitOptions festgelegt.

  • Lösung: Achten Sie darauf, dass delegate an InitOptions übergeben wird:

    let options = InitOptions(
        key: "YOUR_KEY",
        urlHost: "your_subdomain.ccaiplatform.com",
        delegate: self  // Must conform to CCAIDelegate
    )
    

Das Attribut delegate für InitOptions wird als weak deklariert. Das übergebene Objekt muss also an anderer Stelle aufbewahrt werden (z. B. in Ihrem AppDelegate oder einem langlebigen Koordinator).

Problem: JWT-Validierungsfehler oder authService?.authenticate()-Ausnahmen.

  • Ursache: Das JWT ist abgelaufen, fehlerhaft oder mit dem falschen Secret signiert.

  • Lösung: Prüfen Sie, ob Ihr Backend:

    • Verwendet den richtigen geheimen Unternehmenscode.

    • Legt gültige iat- und exp-Zeitstempel fest.

    • Signiert das JWT mit dem HS384-Algorithmus.

    • Gibt einen korrekt formatierten JWT-String zurück.

Probleme mit Push-Benachrichtigungen

Problem: Push-Benachrichtigungen werden nicht empfangen oder nicht verarbeitet.

  • Ursache: Push-Benachrichtigungs-Delegates sind nicht implementiert oder APNs-/VoIP-Tokens werden nicht an das SDK weitergeleitet.

  • Lösung:

    • Implementieren Sie die erforderlichen UIApplicationDelegate-Methoden und leiten Sie Tokens an das SDK weiter:

      func application(
          _ application: UIApplication,
          didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data
      ) {
          CCAI.shared.pushNotificationService?.updatePushToken(
              data: deviceToken,
              type: .apns
          )
      }
      
    • Implementieren Sie für VoIP-Push-Benachrichtigungen PKPushRegistryDelegate und leiten Sie das VoIP-Token mit type: .voip weiter (siehe Für VoIP-Push-Benachrichtigungen registrieren (PushKit)).

    • Prüfen Sie, ob sowohl APNs- als auch VoIP-Zertifikate im CCAI Platform-Portal hochgeladen wurden (siehe Zertifikate konfigurieren).

    • Achten Sie darauf, dass Push-Benachrichtigungen und Hintergrundmodi (Voice over IP, Remote-Benachrichtigungen) in den Signatur- und Funktionsoptionen Ihres Ziels aktiviert sind.

Problem: VoIP-Push-Benachrichtigungen wecken die App nicht aus dem beendeten Zustand auf.

  • Ursache: PKPushRegistry ist nicht konfiguriert oder der Hintergrundmodus für Voice over IP ist nicht aktiviert.

  • Lösung:

    • Erstellen Sie in didFinishLaunchingWithOptions ein PKPushRegistry mit desiredPushTypes = [.voIP] (siehe Für VoIP-Push-Benachrichtigungen registrieren (PushKit)).

    • Achten Sie darauf, dass der Hintergrundmodus „Voice over IP“ unter Target > Signing & Capabilities > Background Modes aktiviert ist.

    • VoIP-Push-Benachrichtigungen funktionieren nur auf physischen Geräten und werden im iOS-Simulator nicht unterstützt.

Probleme mit der Chatsitzung

Problem: chatService?.start() gibt einen Fehler aus.

  • Ursache: Ungültige menuId, Authentifizierungsfehler, Netzwerkproblem oder Konflikt mit einer vorhandenen Sitzung.

  • Lösung:

    • Prüfen Sie, ob menuId mit einer gültigen Warteschlange in Ihrem Administratorportal übereinstimmt.

    • Prüfen Sie, ob ccaiShouldAuthenticate() ein gültiges Authentifizierungstoken zurückgibt.

    • Prüfen Sie, ob das Gerät eine Netzwerkverbindung hat.

    • Rufen Sie immer getLastChatInProgress() auf, bevor Sie einen neuen Chat starten. Wenn eine frühere Sitzung noch aktiv ist (z. B. wenn die App während einer Unterhaltung beendet wurde), schlägt das Starten eines zweiten Chats fehl. Setzen Sie die bestehende Sitzung fort oder beenden Sie sie (siehe Chatsitzung starten).

    • Verpacken Sie den Aufruf in einen do/catch und protokollieren Sie die Fehlerdetails.

Problem: Chatnachrichten werden nicht in der Benutzeroberfläche angezeigt.

  • Ursache: Der Combine-Publisher des Chat-Dienstes wurde nicht abonniert.

  • Lösung: Achten Sie darauf, dass Sie messagesReceived abonnieren und das abbrechbare Element speichern (siehe Chatnachrichten weiter oben in diesem Artikel):

    CCAI.shared.chatService?.messagesReceived
        .sink { [weak self] messages in
            for message in messages {
                self?.updateChatUI(with: message)
            }
        }
        .store(in: &cancellables)
    

Probleme mit der Bildschirmfreigabe

Problem: Die Bildschirmfreigabe wird nach dem Erstellen der Sitzung nicht gestartet.

  • Ursache: Das CCAIScreenShare-Modul wurde nicht initialisiert oder der Schlüssel für die Bildschirmfreigabe wurde nicht konfiguriert.

  • Lösung:

    • Achten Sie darauf, dass CCAI.shared.initializeScreenShare() mit einem gültigen ScreenShareOptions aufgerufen wird, der Ihren Schlüssel für die Bildschirmfreigabe enthält (im CCAI Platform-Portal unter Einstellungen > Entwicklereinstellungen > Bildschirmfreigabe).

    • Prüfen Sie, ob der aktuelle Chat die Bildschirmfreigabe unterstützt, indem Sie chat?.isSupportingScreenShare == true prüfen.

    • Abonnieren Sie statePublisher und requestPublisher (siehe Bildschirmfreigabe).

Problem: Die Bildschirmfreigabe für das gesamte Gerät funktioniert nicht.

  • Ursache: Die Broadcast-Erweiterung ist nicht richtig konfiguriert.

  • Lösung:

    • Prüfen Sie, ob Sie ein Broadcast-Upload-Erweiterungsziel (keine Broadcast-UI-Erweiterung) hinzugefügt haben. Deaktivieren Sie beim Erstellen die Option UI-Erweiterung einschließen.

    • Sowohl das App-Ziel als auch das Erweiterungsziel müssen die Berechtigung io.cobrowse für die Schlüsselbundfreigabe haben.

    • Fügen Sie die Paket-ID der Erweiterung der Info.plist Ihrer App hinzu (nicht der Erweiterung):

      <key>CBIOBroadcastExtension</key>
      <string>your.app.extension.bundle.ID.here</string>
      
    • Fügen Sie CobrowseSDK unter „Frameworks and Libraries“ (Frameworks und Bibliotheken) zu Ihrem Ziel für die Übertragungserweiterung hinzu.

    • Ersetzen Sie den generierten SampleHandler.swift durch:

      import CobrowseSDK
      class SampleHandler: CobrowseIOReplayKitExtension { }
      
    • Die Bildschirmfreigabe für das gesamte Gerät ist nur auf physischen Geräten verfügbar und funktioniert nicht im iOS-Simulator.

Allgemeine Tipps zur Fehlerbehebung

  1. Aktivieren Sie während der Entwicklung das ausführliche Logging, um den internen Status des SDK zu sehen.

  2. Prüfen Sie im CCAI Platform-Administratorportal die Warteschlangenkonfiguration, die Kanalaktivierung und die Öffnungszeiten.

  3. Überwachen Sie den Netzwerkverkehr mit Tools wie Charles Proxy oder Instruments, um API-Aufrufe an *.ccaiplatform.com zu prüfen.

  4. Prüfen Sie, ob die SPM-Paketversionen übereinstimmen. Alle CCAI-Module sollten denselben SPM-Zweig verwenden, um Kompatibilitätsprobleme zu vermeiden.

Zusammenfassung

In dieser fünfteiligen Reihe haben Sie Folgendes getan:

Vollständige Methodensignaturen, vollständige Strukturdefinitionen und vollständige Enum-Auflistungen finden Sie in der begleitenden Headless Mobile SDK – iOS API-Referenz.