SDK mobile headless per iOS: argomenti avanzati, localizzazione e flussi post-sessione

Questo documento spiega come integrare e personalizzare l'SDK Headless Mobile nella tua app per Android. Copre tutto ciò che accade dopo la fine di una sessione, tra cui localizzazione, gestione degli errori e gestione delle sessioni, servizi utenti, dati dei clienti, trasferimento di chat esterne, pattern Combine reattivi, considerazioni sul threading, gestione della memoria e risoluzione dei problemi.

Flussi post-sessione (assistente virtuale post-sessione, sondaggi e CSAT)

Al termine di una chat live o di una chiamata vocale, i contact center spesso vogliono raccogliere feedback o offrire follow-up automatici. Contact Center AI Platform supporta tre tipi di esperienze post-sessione:

  1. Agente virtuale post-sessione (agente virtuale): un chatbot automatico che continua la conversazione dopo che l'agente umano si è disconnesso.

  2. Sondaggi: un modulo con più domande personalizzato per la coda specifica.

  3. CSAT (soddisfazione del cliente): una valutazione (ad esempio, da 1 a 5 stelle) e un feedback testuale facoltativo.

Applicazione della gerarchia

È comune per gli amministratori configurare regole sovrapposte nel portale (ad esempio, attivare CSAT a livello globale, ma anche attivare un agente virtuale post-sessione per la coda "Fatturazione").

Cosa offre l'SDK: un motore di risoluzione dei conflitti rigoroso. L'SDK valuta le regole del portale e garantisce che venga attivato un solo flusso post-sessione per sessione, rispettando rigorosamente la seguente gerarchia:

  • La priorità post-sessione: agente virtuale post-sessione > sondaggi > CSAT.

    • Esempio: se per una coda sono attivati sia il CSAT sia l'agente virtuale post-sessione, l'utente vede solo l'agente virtuale post-sessione.

Cosa crei: un listener che attende la fine della sessione, chiede all'SDK quale flusso ha vinto la valutazione della gerarchia e disegna la schermata corrispondente. Non è necessario scrivere una logica if, else complessa per capire quale esperienza vince; l'SDK esegue i calcoli per te.

Esempio di implementazione: questo snippet mostra come l'app deve ascoltare la fine di una sessione e chiedere all'SDK cosa fare dopo.

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

Transizione alla fase post-sessione

Indipendentemente dal flusso che vince la gerarchia, devi chiamare due metodi del ciclo di vita condiviso su chatService per segnalare alla piattaforma CCAI Platform che la fase post-sessione è iniziata.

Cosa fornisce l'SDK: metodi del ciclo di vita per la transizione della sessione alla fase post-sessione e durante questa fase (startPostSession, readyPostSession).

Cosa crei: la logica di orchestrazione che chiama questi metodi nei punti corretti del flusso dell'interfaccia utente post-sessione.

Esempio di implementazione: questo codice esegue la transizione della sessione attraverso le due fasi del ciclo di vita post-sessione.

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

Dopo che la piattaforma ha confermato la transizione, procedi con il flusso specifico.

Campi di stato post-sessione su ChatResponse

Due campi di orchestrazione post-sessione su ChatResponse guidano la logica di transizione:

  • postSessionTransferStatus: String?: lo stato attuale del trasferimento post-sessione (ad esempio, "in_progress", "ready", "completed"). La piattaforma attiva la macchina a stati di orchestrazione da questo campo: startPostSession() lo sposta in "in_progress", readyPostSession() lo sposta in "ready" e osservi questo valore nei payload ChatResponse successivi (tramite chatReceived) per confermare la transizione lato piattaforma.

  • postSessionOptInRequired: Bool?: indica se l'utente deve attivare esplicitamente il flusso post-sessione prima che venga eseguito. Quando true, mostra un prompt di attivazione nella UI e chiama startPostSession() solo dopo che l'utente ha dato il consenso. Quando false o nil, il controllo dell'attivazione non è richiesto e puoi passare direttamente al flusso post-sessione.

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 indica se è configurato un flusso post-sessione per la sessione.

  • postSessionOptInRequired ti indica se è necessario il consenso esplicito dell'utente prima di eseguirlo.

  • postSessionTransferStatus indica la fase del ciclo di vita della transizione in cui si trova la piattaforma.

Tutti e tre sono indipendenti, quindi controllali sempre tutti.

Agente virtuale post-sessione (priorità più alta)

Cosa fornisce l'SDK: lo stato di transizione per trasferire la sessione da un agente umano a un bot automatico e il routing dei messaggi del bot.

Cosa crei: niente di completamente nuovo. Poiché l'agente virtuale post-sessione funziona come una chat, mantieni aperta la UI della chat personalizzata esistente e lascia che gestisca i messaggi automatici in arrivo nello stesso modo in cui ha gestito i messaggi dell'agente umano.

Esempio di implementazione: se l'SDK segnala una transizione a un VA post-sessione, aggiorna la UI della chat per riflettere la modifica.

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

Sondaggi (priorità media)

Cosa fornisce l'SDK: l'SDK rateService espone i metodi per recuperare le domande del sondaggio e inviare le risposte per una sessione di comunicazione. Le domande del sondaggio vengono configurate dall'amministratore per ogni coda e possono includere più tipi di domande (CSAT, valutazione a stelle, testo in formato libero, enumerazione, scala numerica). Gli esempi in questa sezione valutano una chat (communicationType: "chats"). Per una chiamata, passa l'ID della chiamata e "calls".

Cosa creerai: un modulo dinamico che recupera il sondaggio, scorre le domande, esegue il rendering della UI appropriata (ad esempio pulsanti di opzione, valutazioni a stelle o campi di testo) per ciascuna, convalida la compilazione dei campi obbligatori e pacchettizza le risposte da inviare.

Tipi di chiavi:

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

Esempio di implementazione: questo codice recupera le domande del sondaggio da rateService, ne esegue il rendering in un controller di visualizzazione personalizzato e invia le risposte.

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 - soddisfazione del cliente (priorità più bassa)

Cosa fornisce l'SDK: Il provider di SDK rateService espone un metodo rate() per inviare un punteggio CSAT e un feedback facoltativo per una sessione di comunicazione. La valutazione è in genere un valore intero compreso tra 1 e 5.

Cosa crei: la schermata di valutazione visiva (ad esempio una riga di stelle toccabili o una scala numerica da 1 a 5), un campo se è consentito il feedback e un pulsante Invia.

Tipi di chiavi:

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

Esempio di implementazione: dopo che l'utente ha toccato una valutazione a stelle e scritto il proprio feedback, trasmetti questi valori a 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.")
        }
    }
}

Download delle trascrizioni delle chat

Cosa fornisce l'SDK: metodi per scaricare la trascrizione della chat in formato PDF, tramite un URL file o come Data non elaborato in memoria (solo iOS).

Cosa crei: il pulsante di download nella UI e la logica di gestione dei file (salvataggio, condivisione o anteprima).

Esempio di implementazione: questo codice mostra entrambi gli approcci per il download della trascrizione: il salvataggio in un URL di file e il recupero dei dati PDF non elaborati in memoria.

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

Il metodo downloadChatTranscriptData() è solo per iOS e restituisce direttamente il PDF non elaborato Data, consentendoti di utilizzarlo senza salvarlo prima sul disco. Il metodo downloadChatTranscript(to:) esegue il download in un URL file specificato con logica di ripetizione integrata.

Lingue e localizzazione

Poiché stai creando una UI personalizzata utilizzando l'SDK Headless Mobile, sei responsabile della traduzione dei pulsanti, dei menu e degli avvisi personalizzati della tua app.

Perché l'SDK della piattaforma CCAI deve conoscere la lingua dell'utente?

  1. Routing delle code: la piattaforma CCAI utilizza il codice lingua per indirizzare l'utente a un agente che parla quella lingua.

  2. Messaggi di sistema: i messaggi automatici generati dal backend della piattaforma CCAI (ad esempio, "Un agente sarà con te a breve") vengono recapitati nella lingua attiva.

API dei servizi linguistici

Cosa fornisce l'SDK: una proprietà languageCode di lettura e scrittura per la lingua dell'SDK attiva (predefinita "en") e getPortalAvailableLanguageCodes(), un metodo asincrono che restituisce le lingue attivate dagli amministratori nel portale della piattaforma CCAI.

Cosa crei: una UI del selettore lingua (se vuoi che gli utenti scelgano manualmente) e la logica per impostare la lingua prima dell'inizio di una sessione.

// 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() ?? []

L'SDK non espone un elenco fisso di lingue supportate. Per creare un selettore lingua, utilizza getPortalAvailableLanguageCodes() o l'elenco delle lingue di companyService.get().

Impostazione della lingua dell'SDK (regola pre-sessione)

Cosa fornisce l'SDK: un languageService che confronta la lingua che richiedi con le lingue effettivamente attivate dagli amministratori nel portale della piattaforma CCAI.

Cosa devi creare: se vuoi consentire agli utenti di eseguire l'override manuale della lingua (anziché fare affidamento sulle impostazioni predefinite del dispositivo), devi creare l'interfaccia utente di selezione (ad esempio un menu a discesa) e assicurarti che sia accessibile solo prima che tocchino un canale di assistenza.

Esempio di implementazione: questo codice mostra come eseguire l'override esplicito della lingua dell'SDK utilizzando i codici lingua ISO 639 standard (ad esempio, "es" per lo spagnolo, "fr" per il francese). La lingua preferita viene impostata utilizzando il parametro languageCode durante l'inizializzazione dell'SDK nella struttura InitOptions. Puoi anche impostarlo quando reinizializzi l'SDK:

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

Puoi anche passare la lingua quando recuperi i menu della coda:

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

In che modo CCAI Platform risolve la lingua finale

Se non imposti esplicitamente una lingua, l'SDK richiede comunque un codice lingua per il routing e i messaggi di sistema. Per un comportamento più prevedibile, impostalo tu prima che l'utente avvii una sessione di assistenza.

Utilizza questo ordine di priorità:

  1. Lingua esplicita (consigliata): se imposti una lingua in InitOptions.languageCode, l'SDK utilizza quella lingua.

  2. Lingua del dispositivo (se disponibile): se non imposti una lingua in modo esplicito, l'SDK utilizza la lingua selezionata nelle Impostazioni iOS dell'utente (Impostazioni > Generali > Lingua e Zona), a condizione che la lingua sia abilitata per la tua istanza nel portale della piattaforma CCAI.

  3. Fallback al dialetto principale: se sul dispositivo è impostato un dialetto regionale non attivato (ad esempio, es-CU), ma la lingua di base è attivata (es), l'SDK esegue il fallback alla lingua principale.

  4. Fallback in inglese: se nessuna delle opzioni precedenti è disponibile, l'SDK utilizza l'inglese come lingua di riserva.

Gestione degli errori, fallback e gestione delle sessioni

Anche le app più solide riscontrano interruzioni della connessione, dipendenze mancanti o problemi di autenticazione. L'SDK mobile headless è progettato per rilevare questi problemi della piattaforma sottostante e segnalarli alla tua app, consentendoti di gestirli correttamente all'interno della tua UI personalizzata o di fare affidamento sui fallback automatici di CCAI Platform.

Gestione degli errori SDK

Tutti i metodi asincroni nell'SDK Headless Mobile per iOS possono generare errori.

Cosa fornisce l'SDK: metodi di servizio asincroni come chatService, queueMenuService e authService che generano valori Swift Error quando un'operazione non va a buon fine. L'SDK per iOS non definisce un singolo tipo CCAIError unificante. Le modalità di errore specifiche sono espresse tramite tipi di errore mirati (ad esempio, NetworkError, ScreenShareError, ChatProviderError) insieme agli errori standard di Foundation. Per la maggior parte delle integrazioni, è sufficiente rilevare l'errore generico Error e leggere error.localizedDescription.

Cosa crei: gestione degli errori do/catch per ogni chiamata di servizio dell'SDK, visualizzazione di un messaggio rivolto agli utenti e, se opportuno, attivazione della logica di recupero (ad esempio, nuova richiesta di autenticazione in caso di errori authService).

Esempio di implementazione: questo codice inserisce una chiamata SDK in un blocco Swift standard do/catch, leggendo la descrizione localizzata dell'errore per la visualizzazione e la registrazione.

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

  • Aggrega ogni chiamata di servizio SDK in do/catch. Le modalità di errore più comuni includono token di autenticazione scaduti (riattiva ccaiShouldAuthenticate()), valori menuId non validi, dipendenze dei moduli mancanti (ad esempio, chiamata chatService prima di initializeChat()) e problemi di rete o a livello di sistema.

  • Se devi creare rami per tipi di errore specifici, esegui la corrispondenza dei pattern con i tipi concreti generati dal sottosistema pertinente (ad esempio, ScreenShareError dal servizio di condivisione schermo).

  • La registrazione dei dettagli dell'errore durante lo sviluppo aiuta a individuare rapidamente le cause principali.

Controlla e cancella le sessioni

Poiché il ciclo di vita della tua app è separato da quello dell'assistenza della piattaforma CCAI, devi gestire lo stato della sessione, in particolare per quanto riguarda i logout degli utenti.

Cosa fornisce l'SDK: API di utilità per verificare se una sessione di assistenza è ancora in corso (anche dopo il riavvio o l'uscita forzata dall'app) e un metodo sicuro per cancellare tutto lo stato dell'SDK memorizzato nella cache associato a un utente finale specifico, in particolare il token di autenticazione memorizzato nella cache archiviato nel portachiavi iOS.

Cosa crei: controlli preliminari prima di provare ad avviare nuove sessioni e routine di pulizia che vengono attivate quando un utente esce dall'app principale.

Esempio di implementazione (pulizia al logout): termina qualsiasi sessione attiva, cancella il token di autenticazione memorizzato nella cache e il record dell'utente finale dall'SDK, cancella i dati dell'app locale e passa alla schermata di accesso, impedendo all'utente successivo che ha eseguito l'accesso di ereditare la sessione SDK dell'utente precedente.

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

Servizi per l'utente finale (solo iOS)

Cosa fornisce l'SDK: un servizio di lettura e scrittura (endUserService) per accedere e aggiornare le informazioni del profilo dell'utente finale autenticato (nome, email, telefono, identificatore). Questo servizio è disponibile solo per iOS.

Cosa crei: l'integrazione tra l'utente e il sistema di autenticazione della tua app e il record dell'utente finale dell'SDK, inclusi gli aggiornamenti all'accesso e la pulizia al logout (consulta Controlla e cancella le sessioni in precedenza in questo articolo).

Struttura dei dati EndUser

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

Accesso alle informazioni dell'utente finale

Esempio di implementazione: recupera il profilo dell'utente finale corrente utilizzando la proprietà endUser di sola lettura.

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

Aggiornamento delle informazioni dell'utente finale

Esempio di implementazione: aggiorna il record dell'utente finale con i nuovi dati del profilo o cancellalo al momento della disconnessione.

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

Dati personalizzati

Cosa fornisce l'SDK: un meccanismo per allegare metadati strutturati alle sessioni di chat, come JWT firmati (verificati dal tuo backend) o come payload non firmati (impostati direttamente nel client).

Cosa crei: la logica di raccolta dei dati nella tua app e, per i dati firmati, l'endpoint di firma JWT sul tuo server di backend (consulta Autentica gli utenti finali per lo schema completo di autenticazione e payload JWT).

Dati personalizzati firmati

I dati personalizzati firmati utilizzano un token JWT firmato con il secret della tua azienda sul tuo server di backend. Questo è l'approccio sicuro per trasmettere dati sensibili o attendibili.

Esempio di implementazione: crea un oggetto dati personalizzato firmato da un JWT generato sul tuo backend.

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

Dati personalizzati non firmati

I dati personalizzati non firmati vengono impostati direttamente nel client utilizzando CustomDataPayload e CustomDataItem.

Esempio di implementazione: crea un payload non firmato con elementi dati visibili e nascosti dall'agente.

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)

Gli elementi dati personalizzati supportano le seguenti proprietà:

  • label: etichetta visualizzata dall'agente.

  • value: il valore dei dati (esempi: String, Int, Bool).

  • type: tipo di dati (.string, .number, .date, .url, .boolean).

  • invisibleToAgent: se true, i dati sono nascosti agli agenti, ma sono disponibili per il routing e l'analisi.

Utilizzo di dati personalizzati nelle richieste di chat

Esempio di implementazione: allega dati personalizzati quando avvii una sessione di chat.

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

Trasferimento della chat esterna

Cosa fornisce l'SDK: una struttura di dati (ExternalChatTransfer) per passare il nome di un agente precedente e la trascrizione della conversazione a una nuova sessione della piattaforma CCAI.

Cosa crei: il flusso di migrazione che estrae il contesto dal tuo sistema di chat esterno e lo pacchettizza per l'SDK.

Esempio di implementazione: questo codice crea un oggetto di trasferimento della chat esterno con il nome dell'agente precedente e lo allega ai dati personalizzati della sessione.

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)

Questo è utile quando si esegue la migrazione di un utente da un sistema di chat di terze parti a una sessione della piattaforma CCAI, preservando il contesto della conversazione per l'agente ricevente.

Integrazione di Combine (programmazione reattiva)

Cosa fornisce l'SDK: combina i publisher che emettono eventi SDK in tempo reale (messaggi in arrivo, modifiche allo stato della condivisione schermo) come stream osservabili.

Cosa creerai: associazioni di UI reattive che si iscrivono a questi publisher e aggiornano di conseguenza le visualizzazioni SwiftUI o UIKit.

Messaggi di Chat

chatService espone i publisher Combine per l'osservazione degli eventi di chat in tempo reale.

Publisher Emits
messagesReceived Elenchi di messaggi chat in arrivo (da agenti, agenti virtuali o dal sistema).
typingEvent Quando un utente o un agente sta digitando.
memberEvent Quando un utente o un agente partecipa o abbandona la chat (inclusi i trasferimenti e le disconnessioni degli agenti).
stateChanged Modifiche dello stato del provider di chat (connessione, connesso, disconnesso, errore).
chatReceived Dati di risposta della chat quando viene ricevuta o aggiornata una chat (incluse le modifiche di stato, l'assegnazione dell'agente e lo stato post-sessione).

chatService espone anche transferEvent per gli eventi di trasferimento e networkConnectivityChanged per la connettività dei dispositivi. Per le firme dei tipi complete e tutti i publisher disponibili, consulta il Riferimento API dell'SDK Headless Mobile per iOS.

Esempio di implementazione

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)

Errori di partecipazione

Se l'SDK non riesce a partecipare alla chat, stateChanged pubblica .error con ChatError.failedToJoin. Se la chat non è ancora disponibile dopo i tentativi dell'SDK, pubblica .error con ChatError.failedToGetChat o ChatError.failedToGetChatId se l'SDK non è riuscito a recuperare l'ID della chat. Questi errori arrivano su questo publisher, non come un errore generato da start(request:) o resumeChat(_:), quindi un do/catch intorno a queste chiamate non li rileva. Gestiscili nel tuo sottoscrittore stateChanged:

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)

Stato della condivisione schermo

Esempio di implementazione: monitora in modo reattivo le modifiche dello stato della condivisione schermo e rispondi a ogni fase della sessione.

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)

Considerazioni sul threading

L'SDK Headless Mobile per iOS è progettato per funzionare con la concorrenza strutturata di Swift (async/await) ed è in gran parte sicuro per il thread principale. Tuttavia, esistono importanti considerazioni sul threading per le integrazioni headless.

Thread safety

Tutti i metodi SDK sono thread-safe e possono essere chiamati da qualsiasi thread. Le operazioni di rete vengono eseguite in modo asincrono utilizzando il pattern async e await di Swift, che sospende l'attività di chiamata senza bloccare il thread.

// 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 e autenticazione asincrona

Il metodo ccaiShouldAuthenticate() nel tuo CCAIDelegate è una funzione asincrona, quindi puoi eseguire chiamate di rete al suo interno in tutta sicurezza:

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

Aggiornamenti della UI dai callback dell'SDK

Quando osservi gli eventi dell'SDK utilizzando i publisher Combine, assicurati che gli aggiornamenti della UI avvengano sul thread principale. I publisher del servizio di chat e della condivisione schermo sono soggetti non elaborati che non applicano internamente uno scheduler del thread principale, quindi inserisci sempre .receive(on: DispatchQueue.main) prima di un sink che aggiorna l'UI:

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

Per le chiamate SDK asincrone, utilizza @MainActor (nel codice di concorrenza/asincrono e di attesa di Swift) o DispatchQueue.main.async (nel codice basato su chiusura/Grand Central Dispatch) per tornare al thread principale prima di aggiornare la UI:

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

Se la raccolta avviene da un contesto in background, torna esplicitamente al contesto principale:

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

Threading di inizializzazione

L'inizializzazione dell'SDK (CCAI.shared.initialize(options:)) deve essere chiamata durante l'avvio dell'app nel metodo application(_:didFinishLaunchingWithOptions:) di AppDelegate. Anche l'inizializzazione del modulo della funzionalità (initializeChat(), initializeScreenShare()) deve essere eseguita in questo momento, prima di effettuare chiamate di servizio.

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

Gestione della memoria

Una corretta gestione della memoria è essenziale per evitare perdite e garantire una chiusura pulita delle risorse dell'SDK.

Riferimenti dei delegati

L'SDK Headless Mobile per iOS utilizza riferimenti deboli per tutti i delegati per evitare cicli di conservazione. Nella maggior parte dei casi non è necessario impostare manualmente i delegati su nil, ma è buona norma farlo in deinit.

Combina i cancellabili

Archivia sempre le sottoscrizioni Combine in un Set<AnyCancellable> e cancellale quando il view controller o il view model viene deallocato:

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 practice

  • Archivia gli oggetti cancellabili: archivia sempre i riferimenti AnyCancellable per evitare che gli abbonamenti vengano deallocati immediatamente.

  • Esegui la pulizia in deinit: rimuovi tutti gli elementi annullabili e azzera i delegati quando l'oggetto viene deallocato.

  • Evita i cicli di conservazione: utilizza [weak self] nelle chiusure che acquisiscono self. In questo modo viene creato un riferimento non proprietario, quindi la chiusura non mantiene l'oggetto attivo più a lungo del dovuto, evitando perdite di memoria quando l'oggetto viene deallocato prima dell'esecuzione della chiusura:

    CCAI.shared.chatService?.messagesReceived
        .sink { [weak self] messages in
            self?.handleMessages(messages)
        }
        .store(in: &cancellables)
    
  • I servizi sono gestiti dall'SDK: non è necessario rilasciare manualmente i servizi SDK, che sono gestiti dal singleton CCAI.shared.

Risoluzione dei problemi

Segui questi suggerimenti per risolvere i problemi comuni.

Invio all'App Store - Diritto VoIP

Quando invii la tua app ad Apple per la revisione, l'App Store ti chiederà:

"Does this app use the VoIP Background Mode or PushKit VoIP push notifications?"

Rispondi Sì. Poiché l'SDK utilizza PushKit per le chiamate in arrivo e le smart action basate su PSTN (consulta Registrazione per le notifiche push VoIP (PushKit)), è richiesto il diritto VoIP. Se rispondi "No" o ometti l'autorizzazione, l'app verrà rifiutata o le funzionalità di chiamata e push non funzioneranno.

Problemi di build e dipendenze

Problema: Swift Package Manager non riesce a risolvere CCAIKit.

  • Causa: l'URL o il branch del pacchetto non sono corretti nelle impostazioni di Package.swift o Xcode SPM.

  • Correzione: assicurati che la dipendenza SPM utilizzi l'URL del repository e il branch corretti:

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

Verifica che il branch corrisponda alla versione dell'SDK che intendi utilizzare. Se Xcode non riesce a risolvere il pacchetto, prova File > Packages > Reset Package Caches (File > Pacchetti > Reimposta cache dei pacchetti) e poi Resolve Package Versions (Risolvi versioni dei pacchetti).

Problema: errori di build in un progetto SwiftUI relativi ad AppDelegate.

  • Causa: l'SDK richiede un AppDelegate per l'inizializzazione e i delegati delle notifiche push, ma le app SwiftUI pure non ne hanno uno per impostazione predefinita.

  • Correzione: dichiara @UIApplicationDelegateAdaptor nella struttura App:

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

Poi implementa la classe AppDelegate con la conformità CCAIDelegate e i delegati delle notifiche push, come mostrato in Implementa CCAIDelegate per l'autenticazione e Registrazione per le notifiche remote.

Problemi di inizializzazione

Problema: chatService restituisce nil.

  • Causa: CCAI.shared.initializeChat() non è stato chiamato o è stato chiamato prima di CCAI.shared.initialize(options:).

  • Correzione: assicurati che l'ordine di inizializzazione nel tuo AppDelegate.application(_:didFinishLaunchingWithOptions:) sia:

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

La proprietà chatService su CCAI.shared ha un valore solo dopo la chiamata di initializeChat().

Problema: screenShareService restituisce nil.

  • Causa: CCAI.shared.initializeScreenShare() non è stato chiamato o è stato chiamato con un ScreenShareOptions non valido.

  • Correzione: assicurati di chiamare initializeScreenShare() con una chiave di condivisione schermo valida:

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

Problemi di autenticazione

Problema: l'autenticazione non va a buon fine senza messaggi di errore o ccaiShouldAuthenticate() non viene mai chiamato.

  • Causa: il delegato non è stato impostato in InitOptions.

  • Correzione: assicurati che delegate venga trasmesso a InitOptions:

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

La proprietà delegate su InitOptions è dichiarata come weak, pertanto l'oggetto che passi deve essere conservato altrove (ad esempio, il tuo AppDelegate o un coordinatore di lunga durata).

Problema: errori di convalida JWT o eccezioni authService?.authenticate().

  • Causa: il JWT è scaduto, non è valido o è stato firmato con il secret sbagliato.

  • Correzione: verifica che il backend:

    • Utilizza il codice segreto aziendale corretto.

    • Imposta timestamp iat e exp validi.

    • Firma il JWT con l'algoritmo HS384.

    • Restituisce una stringa JWT formattata correttamente.

Problemi relativi alle notifiche push

Problema: le notifiche push non vengono ricevute o non vengono gestite.

  • Causa: i delegati delle notifiche push non sono implementati o i token APN/VoIP non vengono inoltrati all'SDK.

  • Soluzione:

    • Implementa i metodi UIApplicationDelegate richiesti e inoltra i token all'SDK:

      func application(
          _ application: UIApplication,
          didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data
      ) {
          CCAI.shared.pushNotificationService?.updatePushToken(
              data: deviceToken,
              type: .apns
          )
      }
      
    • Per i push VoIP, implementa PKPushRegistryDelegate e inoltra il token VoIP con type: .voip (consulta Registrazione per le notifiche push VoIP (PushKit)).

    • Verifica che i certificati APN e VoIP siano caricati nel portale della piattaforma CCAI (consulta Configurazione dei certificati).

    • Assicurati che le notifiche push e le modalità in background (Voice over IP, Notifiche remote) siano attivate in Firma e funzionalità del target.

Problema: i push VoIP non riattivano l'app dallo stato terminato.

  • Causa: PKPushRegistry non è configurato o la modalità in background di Voice over IP non è attiva.

  • Soluzione:

    • Crea un PKPushRegistry in didFinishLaunchingWithOptions con desiredPushTypes = [.voIP] (consulta Registrazione per le notifiche push VoIP (PushKit)).

    • Assicurati che la modalità in background Voice over IP sia selezionata in Target > Signing & Capabilities > Background Modes.

    • Le notifiche push VoIP funzionano solo su dispositivi fisici, non sono supportate nel simulatore iOS.

Problemi relativi alla sessione di chat

Problema: chatService?.start() genera un errore.

  • Causa: menuId non valido, errore di autenticazione, problema di rete o conflitto di sessione esistente.

  • Soluzione:

    • Verifica che menuId corrisponda a una coda valida nel portale amministratore.

    • Verifica che ccaiShouldAuthenticate() restituisca un token di autenticazione valido.

    • Assicurati che il dispositivo abbia una connessione di rete.

    • Chiama sempre getLastChatInProgress() prima di avviare una nuova chat. Se una sessione precedente è ancora attiva (ad esempio, l'app è stata chiusa forzatamente a metà conversazione), l'avvio di una seconda chat non andrà a buon fine. Riprendi o termina prima la sessione esistente (vedi Avviare una sessione di chat).

    • Aggrega la chiamata in un do/catch e registra i dettagli dell'errore.

Problema: i messaggi chat non vengono visualizzati nella UI.

  • Causa: mancata iscrizione al publisher Combine del servizio di chat.

  • Correzione: assicurati di iscriverti a messagesReceived e di archiviare l'oggetto cancellabile (consulta la sezione Messaggi di chat precedente in questo articolo):

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

Problemi di condivisione schermo

Problema: la condivisione schermo non si avvia dopo la creazione della sessione.

  • Causa: modulo CCAIScreenShare non inizializzato o chiave di condivisione schermo non configurata.

  • Soluzione:

    • Assicurati che CCAI.shared.initializeScreenShare() venga chiamato con un ScreenShareOptions valido contenente la chiave di condivisione schermo (nel portale della piattaforma CCAI in Impostazioni > Impostazioni sviluppatore > Condivisione schermo).

    • Verifica che la chat corrente supporti la condivisione schermo controllando chat?.isSupportingScreenShare == true.

    • Iscriviti a statePublisher e requestPublisher (vedi Condivisione schermo).

Problema: la condivisione schermo dell'intero dispositivo non funziona.

  • Causa: l'estensione di trasmissione non è configurata correttamente.

  • Soluzione:

    • Verifica di aver aggiunto un target di estensione di caricamento della trasmissione (non un'estensione dell'interfaccia utente della trasmissione). Deseleziona Includi estensione dell'interfaccia utente durante la creazione.

    • Sia il target dell'app sia quello dell'estensione devono condividere il diritto di condivisione del portachiavi io.cobrowse.

    • Aggiungi l'ID pacchetto dell'estensione al file Info.plist dell'app (non dell'estensione):

      <key>CBIOBroadcastExtension</key>
      <string>your.app.extension.bundle.ID.here</string>
      
    • Aggiungi CobrowseSDK alla destinazione dell'estensione di trasmissione in Frameworks and Libraries (Framework e librerie).

    • Sostituisci il valore SampleHandler.swift generato con:

      import CobrowseSDK
      class SampleHandler: CobrowseIOReplayKitExtension { }
      
    • La condivisione schermo dell'intero dispositivo è disponibile solo sui dispositivi fisici, non funziona nel simulatore iOS.

Suggerimenti generali per il debug

  1. Attiva il logging dettagliato durante lo sviluppo per visualizzare lo stato interno dell'SDK.

  2. Controlla il portale dell'amministratore di CCAI Platform per verificare la configurazione della coda, l'attivazione del canale e l'orario di apertura.

  3. Monitora il traffico di rete con strumenti come Charles Proxy o Instruments per verificare le chiamate API a *.ccaiplatform.com.

  4. Verifica che le versioni del pacchetto SPM corrispondano: tutti i moduli CCAI devono utilizzare lo stesso ramo SPM per evitare problemi di compatibilità.

Wrap up

In questa serie di cinque parti, hai:

Per le firme dei metodi complete, le definizioni delle strutture complete e gli elenchi completi degli enum, consulta il Riferimento API iOS dell'SDK Headless Mobile.