Questo documento spiega come integrare e personalizzare l'SDK nella tua applicazione Android.
Inizia
L'SDK Headless Mobile per Android ti consente di integrare le funzionalità del contact center di CCAI Platform nella tua UI Android integrata.
Anziché presentare un widget con il brand CCAI Platform, puoi:
Aggiungi i moduli dell'SDK Android CCAI come dipendenze.
Crea schermate, flussi e design visivo personalizzati in Kotlin (consigliato) o Java.
Utilizza l'SDK per:
Avviare e gestire sessioni di chat e vocali.
Offri opzioni di email, chiamata vocale e deviazione.
Supportare azioni smart, allegati e flussi post-sessione (CSAT, sondaggi, agente virtuale).
CCAI Platform gestisce la logica del contact center (routing, code, canali, configurazione, report). Sei tu a gestire l'intera esperienza con l'app (UI, flussi e branding).
Se preferisci un'interfaccia utente predefinita con temi configurabili, utilizza l'SDK per dispositivi mobili standard.
Requisiti e ambienti supportati
Questa sezione descrive i requisiti e gli ambienti supportati per l'SDK Headless Mobile per Android.
Requisiti della piattaforma Android
Per Android si applicano i seguenti requisiti della piattaforma:
Versione minima di Android: Android 6.0 (livello API 23) o versioni successive
SDK di compilazione: 36 (consigliato)
Lingue supportate: Kotlin (consigliato) o Java
Compatibilità con Java: Java 17 e versioni successive
Gradle/Android Studio: una versione recente del plug-in Android per Gradle e di Android Studio compatibile con la tua app e la release dell'SDK che stai utilizzando
Versione di Kotlin: 2.0 o versioni successive
Requisiti delle istanze di CCAI Platform
Per ottenere quanto segue, devi accedere alle impostazioni sviluppatore dell'istanza della piattaforma CCAI:
Chiave aziendale
Codice segreto dell'azienda
URL host: il nome host della piattaforma CCAI (ad esempio, your_subdomain.ccaiplatform.com)
Questi valori vengono utilizzati per:
Chiave aziendale e URL host: nella tua app per Android per inizializzare l'SDK.
Codice secret dell'azienda: nel tuo backend per firmare i token web JSON (JWT) utilizzati per autenticare gli utenti.
Networking e autorizzazioni
La tua app deve consentire il traffico in uscita verso gli endpoint della piattaforma CCAI e gli endpoint del provider vocale che hai configurato.
Le autorizzazioni Android tipiche includono (l'elenco effettivo può variare in base alla versione dell'SDK e al set di funzionalità):
Stato di internet/della rete: per tutte le comunicazioni dell'SDK.
Microfono: per le chiamate vocali.
Notifiche: solo se utilizzi le notifiche push (vedi Notifiche push di seguito).
Spazio di archiviazione/media: solo se l'app legge foto, video o file direttamente dallo spazio di archiviazione condiviso. I file della tua app e il selettore di foto di sistema non richiedono un'autorizzazione.
Fotocamera: per l'acquisizione di foto o video nelle azioni intelligenti.
Acquisizione schermo: per la condivisione schermo (
MediaProjection).
Dichiara e richiedi le autorizzazioni di runtime in base alle linee guida del sistema operativo Android.
Notifiche push
L'SDK Android headless utilizza FCM per inviare:
Avvisi di chiamata in arrivo.
Alcuni messaggi relativi ad azioni intelligenti e chiamate.
Aggiornamenti per mantenere lo stato quando l'app è in background.
Ti serviranno:
Un progetto Firebase.
Un file google-services.json valido nel modulo dell'app.
Gestione e registrazione dei token FCM nella tua app.
Notifica personalizzata e UI durante la chiamata nella tua app.
Come l'SDK Android headless si integra nella tua app
L'SDK Headless Mobile per Android può essere visto come tre livelli:
Piattaforma e SDK CCAI Platform (gestiti da CCAI Platform)
L'SDK interagisce in modo sicuro con la piattaforma CCAI Platform e fornisce:
Autenticazione tramite token web JSON (JWT).
Metadati di routing di code e canali (chat, chiamata vocale, email, link di deviazione esterni).
Gestione dello stato della sessione in tempo reale utilizzando oggetti di servizio (
chatService,queueMenuServicee altri).La pipeline di trasporto sicura per azioni intelligenti, allegati di file e condivisione schermo.
Logica di deviazione e valutazione della gerarchia post-sessione.
La tua app per Android (UI e logica, gestite da te)
Puoi controllare l'intera esperienza visiva e di navigazione:
Punti di accesso: ad esempio, una scheda Guida o un pulsante Contattaci.
Menu: il modo in cui mostri le code (ad esempio, Fatturazione, Assistenza tecnica).
UI durante la sessione: i fumetti della chat, le schermate di chiamata e i controlli personalizzati.
Cosa fa la tua app: chiama le API del servizio SDK per avviare e terminare le sessioni, osserva gli eventi dell'SDK utilizzando le coroutine e il flusso Kotlin e gestisce la navigazione dei componenti.
Configurazione del portale di amministrazione di CCAI Platform
Gli amministratori di CCAI Platform configurano le regole di coinvolgimento (orario di apertura, canali disponibili, soglie dei tempi di attesa e sondaggi). L'SDK legge questa configurazione e la espone alla tua app sotto forma di dati non elaborati ed eventi. Sei tu a decidere come disegnare la configurazione sullo schermo.
Recupera le credenziali aziendali
Prima di integrare l'SDK, ottieni le credenziali dalla tua istanza della piattaforma CCAI:
Accedi al portale di amministrazione della piattaforma CCAI con un account amministratore.
Vai a Impostazioni > Impostazioni sviluppatore.
Nella sezione Chiave aziendale e codice segreto, copia:
Chiave aziendale
Codice segreto dell'azienda
Prendi nota dell'URL host, ovvero il nome host della piattaforma CCAI (ad esempio,
your_subdomain.ccaiplatform.com).
Utilizzerai:
Nell'app per Android: Chiave azienda e URL host.
Nel server di backend: codice secret aziendale per firmare i JWT per l'autenticazione dell'utente finale e dati e contesto personalizzati facoltativi utilizzati dalla piattaforma CCAI.
Aggiungi l'SDK alla tua app per Android
L'SDK headless utilizza un'architettura modulare. Installa il core CCAIKit
insieme ai moduli delle funzionalità specifici richiesti dalla tua app (ad esempio,
CCAIChat o CCAIScreenShare).
Aggiungi il repository Maven di CCAI
Aggiungi il repository Maven di CCAI al file settings.gradle.kts (o build.gradle principale) del tuo progetto:
// settings.gradle.kts
dependencyResolutionManagement {
repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
repositories {
google()
mavenCentral()
maven { url = uri("https://sdk.ujet.co/ccaip/android/") }
}
}
Configura il catalogo delle versioni Gradle (consigliato)
Google Cloud consiglia di utilizzare un catalogo delle versioni Gradle per la gestione delle dipendenze dell'SDK. Aggiungi quanto segue al tuo gradle/libs.versions.toml:
[versions]
ccaiVersion = "3.5.0"
[libraries]
ccai-kit = { group = "com.ccaiplatform.android", name = "CCAIKit", version.ref = "ccaiVersion" }
ccai-chat = { group = "com.ccaiplatform.android", name = "CCAIChat", version.ref = "ccaiVersion" }
ccai-chat-red = { group = "com.ccaiplatform.android", name = "CCAIChatRed", version.ref = "ccaiVersion" }
ccai-call = { group = "com.ccaiplatform.android", name = "CCAICall", version.ref = "ccaiVersion" }
ccai-call-red = { group = "com.ccaiplatform.android", name = "CCAICallRed", version.ref = "ccaiVersion" }
ccai-screenshare = { group = "com.ccaiplatform.android", name = "CCAIScreenShare", version.ref = "ccaiVersion" }
Aggiungi dipendenze
Nel file build.gradle.kts a livello di app, aggiungi l'SDK di base e i moduli delle funzionalità specifiche:
// app/build.gradle.kts
android {
compileSdk = 36
compileOptions {
sourceCompatibility = JavaVersion.VERSION_17
targetCompatibility = JavaVersion.VERSION_17
}
kotlinOptions {
jvmTarget = "17"
}
}
dependencies {
// 1. Core (always required)
implementation(libs.ccai.kit)
// 2. Chat (required for chat sessions)
implementation(libs.ccai.chat)
implementation(libs.ccai.chat.red) // media layer paired with CCAIChat
// 3. Voice (required for instant calls, voicemail, and scheduled calls)
implementation(libs.ccai.call)
implementation(libs.ccai.call.red) // media/transport layer paired with CCAICall
// 4. Screen Share (optional)
// implementation(libs.ccai.screenshare)
}
Se non utilizzi il catalogo delle versioni, puoi dichiarare le dipendenze direttamente:
val ccaiVersion = "3.3.1"
dependencies {
implementation("com.ccaiplatform.android:CCAIKit:$ccaiVersion")
implementation("com.ccaiplatform.android:CCAIChat:$ccaiVersion")
implementation("com.ccaiplatform.android:CCAIChatRed:$ccaiVersion")
implementation("com.ccaiplatform.android:CCAICall:$ccaiVersion") // Voice calls
implementation("com.ccaiplatform.android:CCAICallRed:$ccaiVersion") // Twilio VoIP backend
implementation("com.ccaiplatform.android:CCAIScreenShare:$ccaiVersion") // Optional, for screen share
}
Inizializzazione e configurazione
Inizializza l'SDK durante l'avvio dell'app. A causa dell'architettura modulare dell'SDK, inizializza prima il sistema principale della piattaforma CCAI, quindi registra i provider di canali specifici (come chat o screen share).
Implementa l'interfaccia CCAIDelegate
L'SDK utilizza un'interfaccia CCAIDelegate per i callback di autenticazione. Il metodo
chiave è una funzione di sospensione Kotlin ccaiShouldAuthenticate() che l'SDK
chiama quando ha bisogno di un JWT.
import com.ccaiplatform.ccaikit.CCAI
import com.ccaiplatform.ccaikit.CCAIDelegate
import kotlinx.coroutines.CancellationException
class MyCCAIDelegate : CCAIDelegate {
/**
* Called by the SDK when it needs a signed JWT for authentication.
* This is a suspend function - you can make network calls here.
*
* @return The auth token returned by `authService.authenticate(jwt)`,
* or null on failure. This is what the SDK expects - not the raw JWT.
*/
override suspend fun ccaiShouldAuthenticate(): String? {
return try {
// 1. Call your backend server to get a signed JWT
val jwt = MyBackendApi.getSignedJwt() ?: return null
// 2. Exchange the JWT for an auth token using authService - this is
// what the SDK expects to be returned (not the raw JWT).
CCAI.authService?.authenticate(jwt)
} catch (e: CancellationException) {
throw e
} catch (e: Throwable) {
// Includes NetworkError, which extends Error rather than Exception
null // Return null to signal authentication failure
}
}
}
Lo snippet precedente mostra il flusso minimo in due passaggi (firma → autenticazione → restituzione).
Consulta Autentica gli utenti finali e passa i dati personalizzati per il contratto di autenticazione completo, tra cui:
- come firmare il JWT sul tuo backend,
- come
authenticate(jwt)lo scambia con un token di autenticazione, - memorizzazione nella cache e annullamento della convalida dei token e
- esempi pratici con gestione degli errori.
Inizializza l'SDK nella classe dell'applicazione
Inizializza l'SDK nella classe Application personalizzata utilizzando l'oggetto singleton CCAI:
import android.app.Application
import com.ccaiplatform.ccaikit.CCAI
import com.ccaiplatform.ccaikit.InitOptions
import com.ccaiplatform.ccaichat.initializeChat
import com.ccaiplatform.ccaichat.model.ChatOptions
import com.ccaiplatform.ccaicall.initializeCall
// import com.ccaiplatform.ccaiscreenshare.initializeScreenShare // If using screen share
import com.ccaiplatform.ccaikit.models.screenShare.ScreenShareOptions
class MainApplication : Application() {
private val delegate = MyCCAIDelegate()
override fun onCreate() {
super.onCreate()
// 1. Build InitOptions
val initOptions = InitOptions(
key = "YOUR_COMPANY_KEY",
urlHost = "your_subdomain.ccaiplatform.com",
delegate = delegate // Your CCAIDelegate implementation
)
// 2. Initialize the Core SDK
CCAI.initialize(
context = this,
options = initOptions
)
// Optional: set the SDK language (ISO 639 code). See Languages and localization
// in Headless Mobile SDK v3 for Android: Advanced Topics, Localization, and Post-Session Flows.
CCAI.languageService?.languageCode = "en"
// 3. Initialize Chat - minimal
CCAI.initializeChat(context = this)
// Initialize Chat - with optional configuration
// val chatOptions = ChatOptions(
// webFormHandler = null, // Optional suspend handler that renders web forms in your own UI
// downloadTranscriptVisibility = DownloadTranscriptVisibility.SHOW_ALL
// )
// To set a chat greeting, pass Chat(greeting = ...) in the ChatRequest
// CCAI.initializeChat(
// context = this,
// options = chatOptions
// )
// 4. Initialize call (required whenever your app uses voice or scheduled calls)
CCAI.initializeCall(context = this)
// 5. Initialize screen share (optional)
// CCAI.initializeScreenShare(
// context = this,
// options = ScreenShareOptions(
// key = "YOUR_SCREEN_SHARE_LICENSE_KEY", // License Key (Settings > Developer Settings > Screen Share)
// domain = "https://your-screen-share-domain.example.com" // Optional: the Screen Share Domain URL
// )
// )
}
}
Riferimento per la configurazione di InitOptions
data class InitOptions(
/// The company key used for authentication
var key: String,
/// The host URL for CCAI platform (for example, "my-unique-instance.uc1.ccaiplatform.com")
var urlHost: String,
/// The preferred language code for localization (defaults to "en")
var languageCode: String? = "en",
/// Listener that handles authentication
var delegate: CCAIDelegate? = null,
/// Whether to cache the authentication token (defaults to true)
var cacheAuthToken: Boolean = true
)
Aggiorna AndroidManifest.xml
Assicurati che la classe dell'applicazione personalizzata sia registrata:
<application
android:name=".MainApplication"
android:icon="@mipmap/ic_launcher"
android:label="@string/app_name"
android:theme="@style/Theme.YourApp">
</application>
Servizi SDK disponibili
Dopo l'inizializzazione, puoi accedere a vari servizi tramite l'oggetto singleton CCAI:
val authService = CCAI.authService
val companyService = CCAI.companyService
val queueMenuService = CCAI.queueMenuService
val languageService = CCAI.languageService
val pushNotificationService = CCAI.pushNotificationService
val smartActionService = CCAI.smartActionService
val endUserService = CCAI.endUserService
val chatService = CCAI.chatService // Only available after initializeChat()
val screenShareService = CCAI.screenShareService // Only available after initializeScreenShare()
val rateService = CCAI.rateService // For CSAT ratings and survey submission
val callService = CCAI.callService // Only available after initializeCall()
Recupera la configurazione dell'azienda
Dopo l'inizializzazione, puoi recuperare la configurazione a livello di azienda utilizzando
companyService. Ciò è utile per compilare i selettori lingua, visualizzare il nome dell'azienda o leggere i dati di contatto dell'assistenza prima che l'utente entri in una coda.
// Fetch company details
val company = CCAI.companyService?.get()
// CompanyResponse contains:
// - displayName: String?
// - supportEmail: String?
// - languages: List<LanguageSetting>? (each with lang, name, and enabled)
// - phoneNumber: String?
// ...
Autentica gli utenti finali e trasmetti dati personalizzati
L'SDK Headless Mobile per Android utilizza i token web JSON (JWT) per autenticare gli utenti e trasmettere in modo sicuro le informazioni contestuali al CRM dell'agente.
Come funziona
L'SDK utilizza un flusso di autenticazione asincrona semplificato in due passaggi:
L'SDK determina che deve autenticare l'utente.
Chiama il metodo
CCAIDelegate,ccaiShouldAuthenticate(), che è una funzione di sospensione.La tua app chiama il server di backend per ottenere un JWT firmato.
L'app passa quindi il JWT firmato a
CCAI.authService?.authenticate(jwt)per scambiarlo con un token di autenticazione.Il token di autenticazione viene restituito all'SDK per completare la connessione.
Implementa l'CCAIDelegate per l'autenticazione
La tua app deve implementare l'interfaccia CCAIDelegate. L'SDK chiama il primo metodo suspend quando richiede l'autenticazione.
Interfaccia CCAIDelegate
interface CCAIDelegate {
suspend fun ccaiShouldAuthenticate(): String?
}
Esempio di implementazione (Kotlin)
class MyCCAIDelegate : CCAIDelegate {
override suspend fun ccaiShouldAuthenticate(): String? {
// 1. Sign JWT remotely on your backend server
val jwt = signJWTRemotely() ?: return null
// 2. Authenticate JWT using authService to get an auth token
return try {
CCAI.authService?.authenticate(jwt)
} catch (e: CancellationException) {
throw e
} catch (e: Throwable) {
// Includes NetworkError, which extends Error rather than Exception
null
}
}
}
Passa i dati dei clienti al CRM
Se vuoi trasmettere dati contestuali all'agente (ad esempio, il sistema operativo del dispositivo, la posizione o il livello dell'account dell'utente), il tuo backend deve inserire un oggetto custom_data nel payload JWT prima di firmarlo.
Ogni dato personalizzato deve essere formattato come un oggetto JSON contenente un'etichetta (ciò che vede l'agente), un valore e un tipo.
Tipi di dati supportati
string: testo standard (ad esempio, "Pixel 8 Pro").number: numeri interi o con virgola mobile (ad esempio, 1234 o 99,99).date: un timestamp Unix UTC di 13 cifre, inclusi i millisecondi (ad esempio, 1537399655992).url: formato URL HTTP/HTTPS standard.boolean: valore booleano standard.
Visibilità dell'agente: facoltativamente, puoi passare alla piattaforma CCAI Platform dati nascosti all'agente umano, ma disponibili per il routing o l'analisi del backend. Per farlo, includi "invisible_to_agent": true nell'oggetto dati.
Chiavi CRM riservate
La piattaforma CCAI supporta chiavi riservate specifiche che attivano comportamenti integrati nella piattaforma, ad esempio contrassegnare un utente come VIP o avvisare un agente di un malintenzionato. Questi devono essere formattati come tipi boolean e verranno accettati solo se il payload è firmato utilizzando il metodo JWT sicuro.
reserved_verified_customer: indica se un cliente è stato autenticato correttamente dai tuoi sistemi interni.reserved_bad_actor: segnala l'utente all'agente come potenziale spammer o account fraudolento.reserved_repeat_customer: indica se questo cliente ha contattato spesso l'assistenza di recente.
Esempio di payload con chiavi riservate
{
"iat": 1537399656,
"exp": 1537400256,
"custom_data": {
"reserved_verified_customer": {
"label": "Verified Customer",
"value": true,
"type": "boolean"
},
"reserved_bad_actor": {
"label": "Bad Actor",
"value": false,
"type": "boolean"
},
"reserved_repeat_customer": {
"label": "Repeat Customer",
"value": false,
"type": "boolean"
}
}
}
Gestisci i token di autenticazione
L'SDK fornisce metodi per aggiornare o cancellare manualmente il token di autenticazione memorizzato nella cache:
// Set a new auth token
CCAI.authService?.updateAuthToken("new_auth_token")
// Clear the current token (for example, on user logout)
CCAI.authService?.updateAuthToken(null)
Schema del payload JWT dei dati dei clienti
Quando il tuo backend crea il payload finale da firmare con la tua Company
Secret Code, deve seguire rigorosamente questo schema. Tieni presente i timestamp obbligatori iat (data/ora di emissione) e exp (data/ora di scadenza).
{
"iat": 1537399656,
"exp": 1537400256,
"custom_data": {
"os_version": {
"label": "OS Version",
"value": "14.0",
"type": "string"
},
"membership_tier": {
"label": "Membership Tier",
"value": "Platinum",
"type": "string"
},
"ssn_last_four": {
"label": "SSN",
"value": "1234",
"type": "string",
"invisible_to_agent": true
},
"reserved_verified_customer": {
"label": "Verified Customer",
"value": true,
"type": "boolean"
}
}
}
Attiva notifiche push
L'SDK utilizza le notifiche push per:
Chiamate in arrivo.
Determinate azioni rapide ed eventi correlati alle chiamate.
Mantenere lo stato quando l'app è in background.
Configurazione di Firebase
Crea o utilizza un progetto Firebase esistente.
Registra la tua app per Android e scarica il file
google-services.json.Posiziona
google-services.jsonnella directory del modulo dell'app.Nel file
build.gradle.ktsa livello di directory principale, aggiungi il plug-in dei servizi Google:// build.gradle.kts (Project) plugins { id("com.google.gms.google-services") version "4.4.2" apply false }Nel file
build.gradle.ktsa livello di app, applica il plug-in e aggiungi le dipendenzeFirebase:// app/build.gradle.kts plugins { id("com.google.gms.google-services") } dependencies { // Firebase BoM for version management implementation(platform("com.google.firebase:firebase-bom:33.5.1")) implementation("com.google.firebase:firebase-messaging") }Sincronizza il progetto.
Registra il token FCM con l'SDK
Registra il token push FCM tramite pushNotificationService e inoltra i payload di dati FCM in entrata all'SDK. La tua app è responsabile del rendering di qualsiasi notifica rivolta ai clienti o dell'UI durante la chiamata.
Implementa onMessageReceived
Se utilizzi FCM, implementa un listener nella classe FirebaseMessagingService per le notifiche push. Se non vengono implementati, il servizio non funzionerà correttamente.
import com.google.firebase.messaging.FirebaseMessagingService
import com.google.firebase.messaging.RemoteMessage
import com.ccaiplatform.ccaikit.CCAI
import kotlinx.coroutines.CoroutineScope
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.launch
class MyFirebaseMessagingService : FirebaseMessagingService() {
private val scope = CoroutineScope(Dispatchers.IO)
override fun onMessageReceived(remoteMessage: RemoteMessage) {
scope.launch {
// Forward CCAI platform push notifications to the SDK.
CCAI.pushNotificationService?.handlePushNotification(remoteMessage.data)
// Render any customer-facing notification UI in your own app code.
MyNotificationRenderer.showIfNeeded(application, remoteMessage.data)
}
}
}
Implementa onNewToken
Implementa anche il metodo onNewToken per gestire gli aggiornamenti dei token. In questo modo, l'SDK Headless Mobile per Android riceve il token di notifica push più recente:
class MyFirebaseMessagingService : FirebaseMessagingService() {
// ...
override fun onNewToken(token: String) {
// Fetch the updated token from Firebase and update it in CCAI
CCAI.pushNotificationService?.updatePushToken(token)
}
}
Registra il servizio in AndroidManifest.xml
Aggiungi il servizio Firebase Messaging al tuo AndroidManifest.xml in modo che il sistema possa inviare messaggi push al tuo servizio:
<application>
<service
android:name=".firebase.MyFirebaseMessagingService"
android:exported="true">
<intent-filter>
<action android:name="com.google.firebase.MESSAGING_EVENT" />
</intent-filter>
</service>
</application>
Registrazione iniziale del token
All'avvio dell'app (dopo l'inizializzazione dell'SDK), registra in modo proattivo il token FCM corrente:
import com.google.firebase.messaging.FirebaseMessaging
// In your Application.onCreate(), after CCAI.initialize()
FirebaseMessaging.getInstance().token.addOnCompleteListener { task ->
if (task.isSuccessful) {
val token = task.result
CCAI.pushNotificationService?.updatePushToken(token)
}
}
Gestione delle autorizzazioni alle notifiche (Android 13 e versioni successive)
Su Android 13 (livello API 33) e versioni successive, la tua app deve disporre dell'autorizzazione di runtime POST_NOTIFICATIONS per mostrare le notifiche. L'SDK fornisce un'utilità integrata per richiederla:
import com.ccaiplatform.ccaikit.util.PermissionUtil
// Request notification permissions from the user
PermissionUtil.requestPermissionsForNotifications(activity)
// Check if permissions have been granted
val isGranted = PermissionUtil.isPermissionsForNotificationsGranted(context)
if (isGranted) {
Log.d("CCAI", "Push notifications permitted")
}
Richiama questo metodo all'inizio del ciclo di vita dell'app (ad esempio, durante l'onboarding o il primo lancio) prima di registrare il token FCM, in modo che le notifiche push possano essere recapitate.