Premiers pas avec le SDK Mobile headless pour Android

Ce document explique comment intégrer et personnaliser le SDK dans votre application Android.

Commencer

Le SDK Headless Mobile pour Android vous permet d'intégrer les fonctionnalités de centre de contact de CCAI Platform à votre propre UI Android intégrée.

Au lieu de présenter un widget portant la marque CCAI Platform, vous :

• Ajoutez les modules du SDK Android CCAI en tant que dépendances.

• Créez vos propres écrans, flux et conception visuelle en Kotlin (recommandé) ou en Java.

• Utilisez le SDK pour :

  • démarrer et gérer des sessions de chat et vocales ;

  • Proposez des options d'e-mail, d'appel vocal et de déviation.

  • Prise en charge des actions intelligentes, des pièces jointes et des flux post-session (CSAT, enquêtes, agent virtuel).

CCAI Platform gère la logique du centre de contact (routage, files d'attente, canaux, configuration, rapports). Vous êtes propriétaire de l'ensemble de l'expérience de l'application (UI, flux et branding).

Si vous préférez une UI prédéfinie avec un thème configurable, utilisez le SDK mobile standard.

Configuration requise et environnements compatibles

Cette section décrit les exigences et les environnements compatibles pour le SDK Headless Mobile pour Android.

Exigences concernant la plate-forme Android

Les exigences de plate-forme suivantes s'appliquent à Android :

• Version minimale d'Android : Android 6.0 (niveau d'API 23) ou version ultérieure

• Compiler le SDK : 36 (recommandé)

• Langages compatibles : Kotlin (recommandé) ou Java

• Compatibilité Java : Java 17 ou version ultérieure

• Gradle / Android Studio : une version récente du plug-in Android Gradle et d'Android Studio compatible avec votre application et la version du SDK que vous utilisez

• Version de Kotlin : 1.6.0 ou version ultérieure

Exigences concernant les instances CCAI Platform

Vous aurez besoin d'accéder aux paramètres pour les développeurs de votre instance CCAI Platform pour obtenir les éléments suivants :

• Clé de l'entreprise

• Code secret de l'entreprise

• URL de l'hôte : nom d'hôte de la plate-forme CCAI (par exemple, your_subdomain.ccaiplatform.com)

Ces valeurs sont utilisées pour :

• Clé de l'entreprise et URL de l'hôte : dans votre application Android pour initialiser le SDK.

• Code secret de l'entreprise : dans votre backend pour signer les jetons Web JSON (JWT) utilisés pour authentifier les utilisateurs.

Mise en réseau et autorisations

Votre application doit autoriser le trafic sortant vers les points de terminaison CCAI Platform et tous les points de terminaison de fournisseur de voix que vous avez configurés.

Les autorisations Android typiques incluent (la liste réelle peut varier selon la version du SDK et votre ensemble de caractéristiques) :

• État d'Internet / du réseau : pour toutes les communications du SDK.

• Microphone : pour les appels vocaux.

• Notifications : pour les notifications push Firebase Cloud Messaging (FCM).

• Stockage / Multimédia : pour les pièces jointes.

• Appareil photo : pour prendre des photos ou des vidéos dans les actions intelligentes.

• Capture d'écran : pour le partage d'écran (MediaProjection).

Déclarez et demandez des autorisations d'exécution conformément aux consignes de l'OS Android.

Notifications push

Le SDK Android sans interface graphique utilise FCM pour fournir les éléments suivants :

• Notifications d'appels entrants

• Certains messages liés aux actions intelligentes et aux appels

• Mises à jour pour aider à maintenir l'état lorsque l'application est mise en arrière-plan.

Vous avez alors besoin de :

• Un projet Firebase.

• Un fichier google-services.json valide dans le module de votre application.

• Gestion et enregistrement des jetons FCM dans votre application.

• Interface utilisateur personnalisée pour les notifications et les appels dans votre application.

Comment le SDK Android sans interface graphique s'intègre à votre application

Le SDK Headless Mobile pour Android peut être considéré comme composé de trois couches :

Plate-forme et SDK CCAI Platform (gérés par CCAI Platform)

Le SDK interagit de manière sécurisée avec la plate-forme CCAI Platform et fournit les éléments suivants :

• Authentification à l'aide de jetons Web JSON (JWT).

• Métadonnées de routage des files d'attente et des canaux (chat, appel vocal, e-mail, liens de redirection externes).

• Gestion de l'état de la session en temps réel à l'aide d'objets de service (chatService, queueMenuService, etc.).

• Pipeline de transport sécurisé pour les actions intelligentes, les pièces jointes et le partage d'écran.

• Logique de redirection et évaluation hiérarchique post-session.

Votre application Android (UI et logique gérées par vous)

Vous contrôlez l'ensemble de l'expérience visuelle et de navigation :

• Points d'entrée : par exemple, un onglet Aide ou un bouton Nous contacter.

• Menus : façon dont vous affichez les files d'attente (par exemple, Facturation, Assistance technique).

• UI en session : vos bulles de chat, écrans d'appel et commandes personnalisés.

• Ce que fait votre application : elle appelle les API de service du SDK pour démarrer et mettre fin aux sessions, observe les événements du SDK à l'aide de Kotlin Coroutines et Flow, et gère la navigation des composants.

Configuration du portail d'administration CCAI Platform

Vos administrateurs CCAI Platform configurent les règles d'engagement (heures d'ouverture, canaux disponibles, seuils de temps d'attente et enquêtes). Le SDK lit cette configuration et l'expose à votre application sous forme de données et d'événements bruts. Vous décidez comment dessiner cette configuration à l'écran.

Récupérer les identifiants de l'entreprise

Avant d'intégrer le SDK, obtenez les identifiants à partir de votre instance CCAI Platform :

1. Connectez-vous au portail d'administration de la plate-forme CCAI avec un compte administrateur.

2. Accédez à Paramètres > Paramètres pour les développeurs.

3. Sous Clé et code secret de l'entreprise, copiez :

   • Clé de l'entreprise

   • Code secret de l'entreprise

4. Notez votre URL hôte, c'est-à-dire le nom d'hôte de la plate-forme CCAI (par exemple, your_subdomain.ccaiplatform.com).

Vous utiliserez ces produits :

• Dans votre application Android : clé d'entreprise et URL de l'hôte.

• Sur votre serveur backend : code secret de l'entreprise pour signer les jetons JWT pour l'authentification des utilisateurs finaux, ainsi que les données et le contexte personnalisés facultatifs utilisés par la plate-forme CCAI.

Ajouter le SDK à votre application Android

Le SDK sans interface graphique utilise une architecture modulaire. Vous installez le CCAIKit principal en même temps que les modules de fonctionnalités spécifiques dont votre application a besoin (par exemple, CCAIChat ou CCAIScreenShare).

Ajouter le dépôt Maven CCAI

Ajoutez le dépôt Maven CCAI au fichier settings.gradle.kts de votre projet (ou au fichier build.gradle racine) :

// settings.gradle.kts
dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
        maven { url = uri("https://sdk.ujet.co/ccaip/android/") }
    }
}

Configurer le catalogue de versions Gradle (recommandé)

Google Cloud recommande d'utiliser un catalogue de versions Gradle pour gérer les dépendances du SDK. Ajoutez le code suivant à votre 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" }

Ajouter des dépendances

Dans le fichier build.gradle.kts au niveau de l'application, ajoutez le SDK Core et les modules de fonctionnalités spécifiques :

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

Si vous n'utilisez pas le catalogue de versions, vous pouvez déclarer directement les dépendances :

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
}

Initialisation et configuration

Initialisez le SDK au lancement de l'application. En raison de l'architecture modulaire du SDK, initialisez d'abord le système principal de la plate-forme CCAI, puis enregistrez les fournisseurs de canaux spécifiques (tels que chat ou screen share).

Implémenter l'interface CCAIDelegate

Le SDK utilise une interface CCAIDelegate pour les rappels d'authentification. La méthode key est une fonction de suspension Kotlin ccaiShouldAuthenticate() que le SDK appelle lorsqu'il a besoin d'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
        }
    }
}

L'extrait précédent montre le flux minimal en deux étapes (connexion → authentification → retour).

Consultez Authentifier les utilisateurs finaux et transmettre des données personnalisées pour connaître l'intégralité du contrat d'authentification, y compris :

• comment signer le JWT sur votre backend ;
• comment authenticate(jwt) l'échange contre un jeton d'authentification ;
• la mise en cache et l'invalidation des jetons ;
• des exemples pratiques avec gestion des exceptions.

Initialiser le SDK dans la classe de votre application

Initialisez le SDK dans votre classe d'application personnalisée à l'aide de l'objet 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"
        //     )
        // )
    }
}

Documentation de référence sur la configuration de 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
)

Mise à jour de AndroidManifest.xml…

Assurez-vous que votre classe d'application personnalisée est enregistrée :

<application
    android:name=".MainApplication"
    android:icon="@mipmap/ic_launcher"
    android:label="@string/app_name"
    android:theme="@style/Theme.YourApp">
</application>

Services SDK disponibles

Après l'initialisation, vous pouvez accéder à différents services via l'objet 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()

Remarque : CCAI est un objet (singleton) en Kotlin. Vous pouvez donc accéder directement aux propriétés à l'aide de CCAI.propertyName. Il n'est pas nécessaire d'appeler getInstance() ni d'utiliser un accesseur partagé.

Avertissement : callService nécessite sa propre étape d'initialisation. Contrairement aux autres services principaux, CCAI.callService se trouve dans le module CCAICall et n'est enregistré en tant que propriété d'extension sur CCAI qu'après l'appel de CCAI.initializeCall(context). Si vous ignorez cette étape, CCAI.callService sera null au moment de l'exécution, et les API de planification du SDK Headless Mobile pour Android (voix, partage d'écran, appel planifié et e-mail) seront inaccessibles.

Récupération de la configuration de l'entreprise

Après l'initialisation, vous pouvez récupérer la configuration au niveau de l'entreprise à l'aide de companyService. Cela permet de remplir les sélecteurs de langue, d'afficher le nom de l'entreprise ou de lire les coordonnées du service d'assistance avant que l'utilisateur ne soit placé dans une file d'attente.

// Fetch company details
val company = CCAI.companyService?.get()

// CompanyResponse contains:
// - displayName: String
// - supportEmail: String?
// - languages: List<String>
// - phoneNumber: String?
// ...

Remarque : La liste languages renvoyée par companyService reflète ce que vos administrateurs ont activé dans le portail CCAI Platform. Utilisez-le pour créer un outil de sélection de langue dans les paramètres de votre application.

Authentifier les utilisateurs finaux et transmettre des données personnalisées

Le SDK mobile sans interface utilisateur pour Android utilise des jetons Web JSON (JWT) pour authentifier les utilisateurs et transmettre de manière sécurisée des informations contextuelles au CRM de l'agent.

Fonctionnement

Le SDK utilise un flux d'authentification asynchrone en deux étapes simplifié :

1. Le SDK détermine qu'il doit authentifier l'utilisateur.

2. Il appelle votre méthode CCAIDelegate : ccaiShouldAuthenticate(), qui est une fonction de suspension.

3. Votre application signe un JWT à distance sur votre serveur backend à l'aide de votre `Company

4. Votre application signe un JWT à distance sur votre serveur backend à l'aide de votre Company Secret Code.

5. Votre application transmet ensuite le JWT signé à CCAI.authService?.authenticate(jwt) pour l'échanger contre un jeton d'authentification.

6. Le jeton d'authentification est renvoyé au SDK pour finaliser la connexion.

Avertissement : La signature JWT doit toujours être effectuée sur votre serveur backend. N'intégrez jamais Company Secret Code dans votre application Android compilée, car cela crée une grave faille de sécurité.

Implémenter CCAIDelegate pour l'authentification

Votre application doit implémenter l'interface CCAIDelegate. Le SDK appelle la première méthode de suspension lorsqu'il a besoin d'une authentification.

Interface CCAIDelegate

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

Exemple d'implémentation (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
        }
    }
}

Exemple complet avec signature JWT (pour référence et test uniquement)

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

Transmettre des données personnalisées au CRM

Si vous souhaitez transmettre des données contextuelles à l'agent (par exemple, l'OS, la position ou le niveau de compte de l'utilisateur), votre backend doit injecter un objet custom_data dans la charge utile JWT avant de la signer.

Chaque élément de données personnalisées doit être mis en forme en tant qu'objet JSON contenant un libellé (ce que voit l'agent), une valeur et un type.

Types de données acceptés

• string : texte standard (par exemple, "Pixel 8 Pro").

• number : entiers ou nombres à virgule flottante (par exemple, 1234 ou 99,99).

• date : code temporel Unix UTC à 13 chiffres, y compris les millisecondes (par exemple, 1537399655992).

• url : format d'URL HTTP/HTTPS standard.

• boolean : valeur standard "true" ou "false".

Visibilité de l'agent : vous pouvez éventuellement transmettre des données à la plate-forme CCAI Platform qui sont masquées pour l'agent humain, mais disponibles pour le routage ou l'analyse du backend. Pour ce faire, incluez "invisible_to_agent": true dans l'objet de données.

Clés CRM réservées

La plate-forme CCAI prend en charge des clés réservées spécifiques qui déclenchent des comportements intégrés dans la plate-forme, comme le signalement d'un utilisateur en tant que VIP ou l'avertissement d'un agent concernant une personne malintentionnée. Ils doivent être mis en forme en tant que types boolean et ne seront acceptés que si la charge utile est signée à l'aide de la méthode sécurisée JWT.

• reserved_verified_customer : indique si un client a été authentifié avec succès par vos systèmes internes.

• reserved_bad_actor : signale à l'agent que l'utilisateur est un spammeur potentiel ou un compte frauduleux.

• reserved_repeat_customer : indique si ce client a fréquemment contacté l'assistance récemment.

Exemple de charge utile avec des clés réservées

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

Gérer les jetons d'authentification

Le SDK fournit des méthodes pour mettre à jour ou effacer manuellement le jeton d'authentification mis en 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)

Avertissement : Lorsque cacheAuthToken est défini sur true (valeur par défaut dans InitOptions), le SDK met en cache le jeton d'authentification afin qu'il puisse être réutilisé lors des lancements d'application sans avoir à se reconnecter. Le jeton mis en cache est utilisé jusqu'à son expiration ou sa suppression explicite. Vous devez effacer le jeton mis en cache chaque fois que des données utilisateur changent, en particulier lors des événements de déconnexion, de changement d'utilisateur ou de mise à jour du profil. Si vous ne le faites pas, le SDK risque d'authentifier la session de l'utilisateur précédent. Appelez updateAuthToken(null) dans le cadre de votre routine de déconnexion.

Schéma de charge utile JWT des données personnalisées

Lorsque votre backend construit la charge utile finale à signer avec votre Company Secret Code, il doit suivre strictement ce schéma. Notez les codes temporels obligatoires iat (date d'émission) et exp (date d'expiration).

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

Activer les notifications push

Le SDK utilise les notifications push pour :

• Appels entrants.

• Certaines actions intelligentes et certains événements liés aux appels.

• Maintien de l'état lorsque l'application est en arrière-plan.

Configurer Firebase

1. Créez un projet Firebase ou utilisez-en un existant.

2. Enregistrez votre application Android et téléchargez le fichier google-services.json.

3. Placez google-services.json dans le répertoire du module de votre application.

4. Dans votre fichier build.gradle.kts au niveau racine, ajoutez le plug-in des services Google :

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

5. Dans le fichier build.gradle.kts au niveau de votre application, appliquez le plug-in et ajoutez les dépendances 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. Synchronisez le projet.

Enregistrer le jeton FCM auprès du SDK

Enregistrez le jeton push FCM via pushNotificationService et transférez les charges utiles de données FCM entrantes vers le SDK. Votre application est responsable du rendu de toute notification ou UI en cours d'appel destinée au client.

Implémenter onMessageReceived

Si vous utilisez FCM, implémentez un écouteur dans votre classe FirebaseMessagingService pour les notifications push. Si ces éléments ne sont pas implémentés, le service ne fonctionnera pas correctement.

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

Remarque : CCAI.pushNotificationService?.handlePushNotification() traite la notification au niveau de la plate-forme. Créez votre propre moteur de rendu de notifications pour les notifications visibles, les écrans d'appel entrant et tout comportement de notification spécifique à une application.

Implémenter onNewToken

Implémentez également la méthode onNewToken pour gérer les mises à jour des jetons. Cela permet au SDK Headless Mobile pour Android de recevoir le dernier jeton de notification push :

class MyFirebaseMessagingService : FirebaseMessagingService() {
    // ...
    override fun onNewToken(token: String) {
        // Fetch the updated token from Firebase and update it in CCAI
        CCAI.pushNotificationService?.updatePushToken(token)
    }
}

Enregistrer le service dans AndroidManifest.xml

Ajoutez le service Firebase Messaging à votre AndroidManifest.xml pour que le système puisse envoyer des messages push à votre service :

<application>
    <service
        android:name=".firebase.MyFirebaseMessagingService"
        android:exported="true">
        <intent-filter>
            <action android:name="com.google.firebase.MESSAGING_EVENT" />
        </intent-filter>
    </service>
</application>

Enregistrement initial du jeton

Au démarrage de l'application (après l'initialisation du SDK), enregistrez de manière proactive le jeton FCM actuel :

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

Gestion des autorisations de notification (Android 13 et versions ultérieures)

Sur Android 13 (niveau d'API 33), les applications mentionnées ci-dessus doivent demander l'autorisation d'exécution POST_NOTIFICATIONS. Le SDK fournit un utilitaire intégré à cet effet :

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

Appelez cette méthode tôt dans le cycle de vie de votre application (par exemple, lors de l'intégration ou du premier lancement) avant d'enregistrer le jeton FCM, afin que les notifications push puissent être envoyées.