SDK mobile headless per Android: inizia

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.

Invece di presentare un widget con il brand CCAI Platform, devi:

• Aggiungi i moduli dell'SDK Android CCAI come dipendenze.

• Crea le tue schermate, i tuoi flussi e il tuo design visivo 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.

  • Supporta le azioni intelligenti, gli allegati e i flussi post-sessione (CSAT, sondaggi, agente virtuale).

CCAI Platform gestisce la logica del contact center (routing, code, canali, configurazione, report). L'esperienza completa dell'app (interfaccia utente, flussi e branding) è di tua proprietà.

Se preferisci un'interfaccia utente predefinita con temi configurabili, utilizza l'SDK mobile standard.

Requisiti e ambienti supportati

Questa sezione descrive i requisiti e gli ambienti supportati per l'SDK mobile headless per Android.

Requisiti della piattaforma Android

Ad Android si applicano i seguenti requisiti della piattaforma:

• Versione Android minima: Android 6.0 (livello API 23) o versioni successive

• Compila SDK: 36 (consigliato)

• Lingue supportate: Kotlin (consigliato) o Java

• Compatibilità Java: Java 17+

• Gradle / Android Studio: una versione recente del plug-in Android per Gradle e di Android Studio compatibile con la tua app e la versione dell'SDK che stai utilizzando

• Versione di Kotlin: 1.6.0 o successive

Requisiti per l'istanza della piattaforma CCAI

Per ottenere:

• Chiave dell'azienda

• Codice segreto dell'azienda

• URL host: il nome host della piattaforma CCAI (ad esempio, your_subdomain.ccaiplatform.com)

Questi valori vengono utilizzati per:

• Chiave dell'azienda e URL host: nella tua app per Android per inizializzare l'SDK.

• Codice segreto dell'azienda: nel 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 tutti 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 tuo insieme di funzionalità):

• Stato di internet / della rete: per tutte le comunicazioni dell'SDK.

• Microfono: per le chiamate vocali.

• Notifiche: per le notifiche push di Firebase Cloud Messaging (FCM).

• Archiviazione / media: per gli allegati.

• 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 fornire:

• Notifiche per le chiamate in arrivo.

• Alcuni messaggi relativi alle azioni intelligenti e alle chiamate.

• Aggiornamenti per mantenere lo stato quando l'app viene eseguita 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 della chiamata in corso nella tua app.

Come si integra l'SDK Android headless nella tua app

L'SDK Headless Mobile per Android può essere visualizzato 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, queueMenuService e altro ancora).

• La pipeline di trasporto sicura per azioni intelligenti, allegati e condivisione dello schermo.

• Logica di deviazione e valutazione della gerarchia post-sessione.

La tua app per Android (UI e logica gestite da te)

Controlli l'intera esperienza visiva e di navigazione:

• Punti di accesso: ad esempio, una scheda Guida o un pulsante Contattaci.

• Menu: come vengono visualizzate le code (ad esempio Fatturazione, Assistenza tecnica).

• UI in sessione: le bolle di chat, le schermate di chiamata e i controlli personalizzati.

• Cosa fa la tua app: chiama le API di servizio dell'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 (orari di apertura, canali disponibili, soglie di tempo di attesa e sondaggi). L'SDK legge questa configurazione e la espone alla tua app come dati ed eventi non elaborati. Decidi tu come disegnare la configurazione sullo schermo.

Recuperare le credenziali aziendali

Prima di integrare l'SDK, ottieni le credenziali dall'istanza della piattaforma CCAI:

1. Accedi al portale di amministrazione della piattaforma CCAI con un account amministratore.

2. Vai a Impostazioni > Impostazioni sviluppatore.

3. Nella sezione Chiave e codice segreto dell'azienda, copia:

   • Chiave dell'azienda

   • Codice segreto dell'azienda

4. 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 segreto dell'azienda per firmare i JWT per l'autenticazione dell'utente finale e i dati e il contesto personalizzati facoltativi utilizzati dalla piattaforma CCAI.

Aggiungere l'SDK all'app per Android

L'SDK headless utilizza un'architettura modulare. Installa il modulo principale CCAIKit insieme ai moduli delle funzionalità specifiche richieste dalla tua app (ad esempio, CCAIChat o CCAIScreenShare).

Aggiungere il repository Maven di CCAI

Aggiungi il repository Maven di CCAI al file settings.gradle.kts (o build.gradle root) 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 gestire le dipendenze dell'SDK. Aggiungi quanto segue a gradle/libs.versions.toml:

[versions]
ccaiVersion = "3.3.1"

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

Aggiungere dipendenze

Nel file build.gradle.kts a livello di app, aggiungi l'SDK principale 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 all'avvio dell'app. A causa dell'architettura modulare dell'SDK, inizializza prima il sistema principale della piattaforma CCAI, poi registra i provider di canali specifici (come chat o screen share).

Implementare l'interfaccia CCAIDelegate

L'SDK utilizza un'interfaccia CCAIDelegate per i callback di autenticazione. Il metodo key è una funzione di sospensione Kotlin ccaiShouldAuthenticate() che l'SDK chiama quando ha bisogno di un JWT.

import com.ccaiplatform.ccaikit.CCAIDelegate

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: Exception) {
            null // Return null to signal authentication failure
        }
    }
}

Lo snippet precedente mostra il flusso minimo in due passaggi (sign → authenticate → return).

Consulta Autenticare gli utenti finali e trasmettere dati personalizzati per il contratto di autenticazione completo, che include:

• come firmare il JWT sul backend,
• in che modo authenticate(jwt) lo scambia con un token di autenticazione,
• memorizzazione nella cache e invalidazione dei token e
• esempi pratici con gestione degli errori.

Inizializza l'SDK nella classe dell'applicazione

Inizializza l'SDK nella tua classe di applicazione 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.ccaikit.initializeScreenShare
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",
            languageCode = "en",       // Optional: ISO 639 code
            delegate = delegate        // Your delegate implementation
        )

        // 2. Initialize the core SDK
        CCAI.initialize(
            context = this,
            options = initOptions
        )

        // 3. Initialize chat (minimal)
        CCAI.initializeChat(context = this)

        // Initialize chat (with optional configuration)
        // val chatOptions = ChatOptions(
        //     webFormInterface = null,              // Implement to intercept and render custom web forms within your own UI
        //     downloadTranscriptVisibility = DownloadTranscriptVisibility.SHOW_ALL,
        //     greeting = "Hello! How can I help you?"
        // )
        // 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_COMPANY_KEY",
        //         domain = "your_subdomain.ccaiplatform.com"
        //     )
        // )
    }
}

Riferimento alla 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 optionsService = CCAI.optionsService
val languageService = CCAI.languageService
val pushNotificationService = CCAI.pushNotificationService
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()

Nota: CCAI è un oggetto (singleton) in Kotlin, quindi puoi accedere alle proprietà direttamente utilizzando CCAI.propertyName, senza dover chiamare getInstance() o utilizzare un accessor condiviso.

Avviso: callService richiede un proprio passaggio di inizializzazione. A differenza degli altri servizi di base, CCAI.callService si trova nel modulo CCAICall ed è registrato come proprietà di estensione su CCAI solo dopo aver chiamato CCAI.initializeCall(context). Se salti questo passaggio, CCAI.callService sarà null in fase di runtime e le API di pianificazione nell'SDK Headless Mobile per Android: voce, condivisione schermo, chiamata pianificata ed email non saranno raggiungibili.

Recupero della configurazione aziendale in corso…

Dopo l'inizializzazione, puoi recuperare la configurazione a livello aziendale utilizzando companyService. È utile per compilare i selettori di 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<String>
// - phoneNumber: String?
// ...

Nota: l'elenco languages restituito da companyService riflette ciò che gli amministratori hanno attivato nel portale della piattaforma CCAI. Utilizzalo per creare un selettore lingua nelle impostazioni dell'app.

Autenticare gli utenti finali e trasmettere dati personalizzati

L'SDK Headless Mobile per Android utilizza i token web JSON (JWT) per autenticare gli utenti e trasferire in modo sicuro le informazioni contestuali al CRM dell'agente.

Come funziona

L'SDK utilizza un flusso di autenticazione asincrona semplificato in due passaggi:

1. L'SDK determina che è necessario autenticare l'utente.

2. Chiama il metodo CCAIDelegate, ccaiShouldAuthenticate(), che è una funzione di sospensione.

3. La tua app firma un JWT in remoto sul server di backend utilizzando il tuo `Company

4. La tua app firma un JWT da remoto sul server di backend utilizzando il tuo Company Secret Code.

5. La tua app passa quindi il JWT firmato a CCAI.authService?.authenticate(jwt) per scambiarlo con un token di autenticazione.

6. Il token di autenticazione viene restituito all'SDK per completare la connessione.

Avviso: la firma JWT deve essere sempre eseguita sul server di backend. Non incorporare mai Company Secret Code all'interno dell'app per Android compilata, in quanto ciò crea una grave vulnerabilità di sicurezza.

Implementare CCAIDelegate per l'autenticazione

La tua app deve implementare l'interfaccia CCAIDelegate. L'SDK chiama il primo metodo di sospensione quando richiede l'autenticazione.

Interfaccia CCAIDelegate

interface CCAIDelegate {
    suspend fun ccaiShouldAuthenticate(): String?
}

Esempio di implementazione (Kotlin)

class CCAIDelegate : 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: Exception) {
            null
        }
    }
}

Esempio completo con firma JWT (solo a scopo di riferimento e test)

class AuthController : CCAIDelegate {
    override suspend fun ccaiShouldAuthenticate(): String? {
        // First, sign JWT with company secret (do this on your backend in production)
        val jwt = Jwts.builder()
            .setClaims(claims)
            .signWith(SignatureAlgorithm.HS384, companySecret?.encodeToByteArray())
            .compact()

        // Then authenticate JWT using authService to get an auth token
        return try {
            CCAI.authService?.authenticate(jwt)
        } catch (e: Exception) {
            null
        }
    }
}

Trasferire dati personalizzati al CRM

Se vuoi trasmettere dati contestuali all'agente (ad esempio, il sistema operativo, 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 in virgola mobile (ad esempio, 1234 o 99,99).

• date: un timestamp Unix UTC a 13 cifre, inclusi i millisecondi (ad esempio, 1537399655992).

• url: formato URL HTTP/HTTPS standard.

• boolean: valore standard vero o falso.

Visibilità dell'agente: puoi trasmettere facoltativamente dati alla piattaforma CCAI che sono nascosti all'agente umano, ma disponibili per il routing o l'analisi di 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 sicuro JWT.

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

Avviso: quando cacheAuthToken è true (impostazione predefinita in InitOptions), l'SDK memorizza nella cache il token di autenticazione in modo che possa essere riutilizzato nei lanci dell'app senza richiedere nuovamente la firma. Il token memorizzato nella cache viene utilizzato fino alla sua scadenza o alla sua cancellazione esplicita. Devi cancellare il token memorizzato nella cache ogni volta che cambiano i dati relativi all'utente, in particolare in caso di eventi di disconnessione, cambio utente o aggiornamenti del profilo. In caso contrario, l'SDK potrebbe autenticare la sessione dell'utente precedente. Chiama updateAuthToken(null) nell'ambito della tua routine di disconnessione.

Schema del payload JWT dei dati personalizzati

Quando il backend crea il payload finale da firmare con il tuo Company Secret Code, deve rispettare rigorosamente questo schema. Prendi nota dei timestamp obbligatori iat (data di emissione) e exp (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"
    }
  }
}

Attivare le 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

1. Crea o utilizza un progetto Firebase esistente.

2. Registra la tua app per Android e scarica il file google-services.json.

3. Inserisci google-services.json nella directory del modulo dell'app.

4. Nel file build.gradle.kts a livello di radice, aggiungi il plug-in dei servizi Google:

   // build.gradle.kts (Project)
   plugins {
       id("com.google.gms.google-services") version "4.4.2" apply false
   }
   

5. Nel file build.gradle.kts a livello di app, applica il plug-in e aggiungi le dipendenze Firebase:

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

6. 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'interfaccia utente in 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)
        }
    }
}

Nota: CCAI.pushNotificationService?.handlePushNotification() elabora la notifica a livello di piattaforma. Crea il tuo renderer di notifiche per notifiche visibili, schermate di chiamate in arrivo e qualsiasi comportamento di notifica specifico dell'app.

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 di messaggistica Firebase 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+)

Su Android 13 (livello API 33), le app menzionate devono richiedere l'autorizzazione di runtime POST_NOTIFICATIONS. L'SDK fornisce un'utilità integrata per questo scopo:

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

Chiama questo metodo all'inizio del ciclo di vita dell'app (ad esempio, durante l'onboarding o il primo avvio) prima di registrare il token FCM, in modo che le notifiche push possano essere recapitate.