Headless Mobile SDK für Android: Erste Schritte

In diesem Dokument wird beschrieben, wie Sie das SDK in Ihre Android-Anwendung einbinden und anpassen.

Jetzt starten

Mit dem Headless Mobile SDK für Android können Sie die Contact-Center-Funktionen der CCAI Platform in Ihre eigene integrierte Android-Benutzeroberfläche einbinden.

Anstatt ein Widget mit dem Branding der CCAI Platform zu präsentieren, gehen Sie so vor:

  • Fügen Sie die CCAI Android SDK-Module als Abhängigkeiten hinzu.

  • Erstellen Sie Ihre eigenen Bildschirme, Abläufe und das visuelle Design in Kotlin (empfohlen) oder Java.

  • Mit dem SDK können Sie Folgendes tun:

    • Chat- und Sprachsitzungen starten und verwalten.

    • Bieten Sie Optionen für E‑Mail, Sprachanruf und Ablenkung an.

    • Unterstützung von Smart Actions, Anhängen und Abläufen nach der Sitzung (CSAT, Umfragen, virtueller Kundenservicemitarbeiter).

Die CCAI Platform übernimmt die Contact Center-Logik (Routing, Warteschlangen, Kanäle, Konfiguration, Berichte). Sie haben die volle Kontrolle über die Nutzerfreundlichkeit der App (UI, Abläufe und Branding).

Wenn Sie eine vordefinierte Benutzeroberfläche mit konfigurierbarem Design bevorzugen, verwenden Sie das Standard-Mobile-SDK.

Anforderungen und unterstützte Umgebungen

In diesem Abschnitt werden die Anforderungen und unterstützten Umgebungen für das Headless Mobile SDK for Android beschrieben.

Anforderungen an die Android-Plattform

Für Android gelten die folgenden Plattformanforderungen:

  • Android-Mindestversion: Android 6.0 (API-Level 23) oder höher

  • SDK kompilieren: 36 (empfohlen)

  • Unterstützte Sprachen: Kotlin (empfohlen) oder Java

  • Java-Kompatibilität: Java 17 oder höher

  • Gradle/Android Studio: eine aktuelle Version des Android-Gradle-Plug-ins und von Android Studio, die mit Ihrer App und der von Ihnen verwendeten SDK-Version kompatibel ist

  • Kotlin-Version: 2.0 oder höher

Anforderungen an CCAI Platform-Instanzen

Sie benötigen Zugriff auf die Entwicklereinstellungen Ihrer CCAI Platform-Instanz, um Folgendes abzurufen:

  • Unternehmensschlüssel

  • Geheimer Code des Unternehmens

  • Host-URL: Der Hostname für die CCAI Platform (z. B. your_subdomain.ccaiplatform.com)

Diese Werte werden für Folgendes verwendet:

  • Unternehmensschlüssel und Host-URL in Ihrer Android-App, um das SDK zu initialisieren.

  • Geheimer Unternehmenscode: Wird in Ihrem Backend verwendet, um JSON Web Tokens (JWT) zu signieren, die zur Authentifizierung von Nutzern verwendet werden.

Netzwerk und Berechtigungen

Ihre App muss ausgehenden Traffic zu CCAI Platform-Endpunkten und allen von Ihnen konfigurierten Endpunkten von Sprachanbietern zulassen.

Zu den typischen Android-Berechtigungen gehören (die tatsächliche Liste kann je nach SDK-Version und Funktionsumfang variieren):

  • Internet-/Netzwerkstatus: für die gesamte SDK-Kommunikation.

  • Mikrofon: für Sprachanrufe.

  • Benachrichtigungen: nur, wenn Sie Push-Benachrichtigungen verwenden (siehe Push-Benachrichtigungen unten).

  • Speicher/Medien: Nur wenn deine App Fotos, Videos oder Dateien direkt aus dem freigegebenen Speicher liest. Für die eigenen Dateien Ihrer App und die System-Bildauswahl ist keine Berechtigung erforderlich.

  • Kamera: für Foto- oder Videoaufnahmen in intelligenten Aktionen.

  • Screenshot: für die Bildschirmfreigabe (MediaProjection).

Laufzeitberechtigungen gemäß den Richtlinien für das Android-Betriebssystem deklarieren und anfordern

Push-Benachrichtigungen

Das Headless Android SDK verwendet FCM, um Folgendes zu senden:

  • Benachrichtigungen über eingehende Anrufe

  • Bestimmte Nachrichten im Zusammenhang mit intelligenten Aktionen und Anrufen.

  • Updates, die den Status beibehalten, wenn die App im Hintergrund ausgeführt wird.

Folgendes wird benötigt:

  • Ein Firebase-Projekt

  • Eine gültige google-services.json-Datei in Ihrem App-Modul.

  • FCM-Token-Verarbeitung und -Registrierung in Ihrer App.

  • Benutzerdefinierte Benachrichtigungen und Anruf-UI in Ihrer App.

So fügt sich das Headless Android SDK in Ihre App ein

Das Headless Mobile SDK für Android kann in drei Ebenen unterteilt werden:

CCAI Platform und SDK (von CCAI Platform verwaltet)

Das SDK interagiert sicher mit der CCAI Platform und bietet Folgendes:

  • Authentifizierung mit JSON Web Tokens (JWT).

  • Metadaten für Warteschlangen- und Kanalrouting (Chat, Sprachanruf, E‑Mail, externe Weiterleitungslinks).

  • Echtzeit-Sitzungsstatusverwaltung mit Dienstobjekten (chatService, queueMenuService usw.)

  • Die sichere Transportpipeline für intelligente Aktionen, Dateianhänge und Bildschirmfreigabe.

  • Ablenkungslogik und Bewertung der Hierarchie nach der Sitzung.

Ihre Android-App (UI und Logik – von Ihnen verwaltet)

Sie haben die volle Kontrolle über die visuelle Darstellung und die Navigation:

  • Einstiegspunkte: z. B. ein Tab Hilfe oder eine Schaltfläche Kontakt.

  • Menüs: wie Sie Warteschlangen anzeigen (z. B. Abrechnung, Technischer Support).

  • In-Session-UI: Ihre benutzerdefinierten Chat-Bubbles, Anrufbildschirme und Steuerelemente.

  • Was Ihre App tut: Sie ruft SDK-Dienst-APIs auf, um Sitzungen zu starten und zu beenden, beobachtet SDK-Ereignisse mit Kotlin-Koroutinen und Flow und steuert die Komponentennavigation.

Konfiguration des CCAI Platform-Admin-Portals

Ihre CCAI Platform-Administratoren konfigurieren die Regeln für die Interaktion (Öffnungszeiten, verfügbare Kanäle, Schwellenwerte für Wartezeiten und Umfragen). Das SDK liest diese Konfiguration und stellt sie Ihrer App als Rohdaten und Ereignisse zur Verfügung. Sie entscheiden, wie diese Konfiguration auf dem Bildschirm dargestellt wird.

Anmeldedaten des Unternehmens abrufen

Bevor Sie das SDK einbinden, rufen Sie die Anmeldedaten aus Ihrer CCAI Platform-Instanz ab:

  1. Melden Sie sich mit einem Administratorkonto im CCAI Platform-Admin-Portal an.

  2. Gehen Sie zu Einstellungen > Entwicklereinstellungen.

  3. Kopieren Sie unter Unternehmensschlüssel und Geheimcode Folgendes:

    • Unternehmensschlüssel

    • Geheimer Code des Unternehmens

  4. Notieren Sie sich die Host-URL, also den Hostnamen für die CCAI-Plattform (z. B. your_subdomain.ccaiplatform.com).

Sie verwenden:

  • In Ihrer Android-App: Unternehmensschlüssel und Host-URL.

  • Auf Ihrem Backend-Server: Geheimer Unternehmenscode zum Signieren von JWTs für die Endnutzerauthentifizierung und optionale benutzerdefinierte Daten und Kontext, die von der CCAI Platform verwendet werden.

SDK zu Ihrer Android-App hinzufügen

Das Headless SDK verwendet eine modulare Architektur. Sie installieren das Kernmodul CCAIKit zusammen mit den spezifischen Funktionsmodulen, die Ihre App benötigt (z. B. CCAIChat oder CCAIScreenShare).

CCAI-Maven-Repository hinzufügen

Fügen Sie das CCAI-Maven-Repository zur settings.gradle.kts-Datei (oder zur Stamm-build.gradle-Datei) Ihres Projekts hinzu:

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

Gradle-Versionskatalog konfigurieren (empfohlen)

Google Cloud empfiehlt, einen Gradle-Versionskatalog zum Verwalten von SDK-Abhängigkeiten zu verwenden. Fügen Sie der Datei gradle/libs.versions.toml Folgendes hinzu:

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

Abhängigkeiten hinzufügen

Fügen Sie in der Datei build.gradle.kts auf App-Ebene das Core SDK und die spezifischen Funktionsmodule hinzu:

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

Wenn Sie den Versionskatalog nicht verwenden, können Sie Abhängigkeiten direkt deklarieren:

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
}

Initialisierung und Einrichtung

Initialisieren Sie das SDK beim Start der App. Aufgrund der modularen Architektur des SDK müssen Sie zuerst das CCAI Platform-Kernsystem initialisieren und dann die spezifischen Kanalanbieter (z. B. chat oder screen share) registrieren.

CCAIDelegate-Schnittstelle implementieren

Das SDK verwendet eine CCAIDelegate-Schnittstelle für Authentifizierungs-Callbacks. Die Schlüsselmethode ist eine Kotlin-Suspend-Funktion ccaiShouldAuthenticate(), die das SDK aufruft, wenn es ein JWT benötigt.

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

Das vorherige Snippet zeigt den minimalen zweistufigen Ablauf (Signieren → Authentifizieren → Zurückgeben).

Informationen zum vollständigen Authentifizierungsvertrag finden Sie unter Endnutzer authentifizieren und benutzerdefinierte Daten übergeben. Dazu gehören:

  • wie Sie das JWT in Ihrem Backend signieren,
  • wie authenticate(jwt) ihn gegen ein Autorisierungstoken eintauscht,
  • Token-Caching und -Entwertung sowie
  • Beispiele mit Fehlerbehandlung.

SDK in Ihrer Anwendungsklasse initialisieren

Initialisieren Sie das SDK in Ihrer benutzerdefinierten Application-Klasse mit dem Singleton-Objekt 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
        //     )
        // )
    }
}

InitOptions-Konfigurationsreferenz

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
)

AndroidManifest.xml aktualisieren

Achten Sie darauf, dass Ihre benutzerdefinierte Anwendungsklasse registriert ist:

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

Verfügbare SDK-Dienste

Nach der Initialisierung können Sie über das Singleton-Objekt CCAI auf verschiedene Dienste zugreifen:

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

Unternehmenskonfiguration abrufen

Nach der Initialisierung können Sie die Konfiguration auf Unternehmensebene mit dem companyService abrufen. Das ist nützlich, um Sprachauswahlmenüs zu füllen, den Unternehmensnamen anzuzeigen oder die Kontaktdaten des Supports zu lesen, bevor der Nutzer in eine Warteschlange aufgenommen wird.

// 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?
// ...

Endnutzer authentifizieren und benutzerdefinierte Daten übergeben

Das Headless Mobile SDK für Android verwendet JSON-Webtokens (JWT), um Nutzer zu authentifizieren und Kontextinformationen sicher an das CRM des Agenten zu übertragen.

Funktionsweise

Das SDK verwendet einen vereinfachten asynchronen Authentifizierungsprozess mit zwei Schritten:

  1. Das SDK stellt fest, dass der Nutzer authentifiziert werden muss.

  2. Sie ruft die Methode CCAIDelegate (ccaiShouldAuthenticate()) auf, die eine Sperrfunktion ist.

  3. Ihre App ruft Ihren Backend-Server auf, um ein signiertes JWT abzurufen.

  4. Ihre App übergibt das signierte JWT dann an CCAI.authService?.authenticate(jwt), um es gegen ein Authentifizierungstoken auszutauschen.

  5. Das Authentifizierungstoken wird an das SDK zurückgegeben, um die Verbindung herzustellen.

CCAIDelegate für die Authentifizierung implementieren

Ihre App muss die CCAIDelegate-Schnittstelle implementieren. Das SDK ruft die erste Sperrmethode auf, wenn eine Authentifizierung erforderlich ist.

CCAIDelegate-Schnittstelle

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

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

Benutzerdefinierte Daten an das CRM-System übergeben

Wenn Sie Kontextdaten an den Agenten übergeben möchten (z. B. das aktuelle Betriebssystem des Nutzers, den Standort oder die Kontostufe), muss Ihr Backend ein custom_data-Objekt in die JWT-Nutzlast einfügen, bevor es signiert wird.

Jeder benutzerdefinierte Datensatz muss als JSON-Objekt formatiert sein, das ein Label (was der Agent sieht), einen Wert und einen Typ enthält.

Unterstützte Datentypen

  • string: Standardtext (z. B. „Pixel 8 Pro“).

  • number: Ganzzahlen oder Gleitkommazahlen (z. B. 1234 oder 99, 99).

  • date: ein 13-stelliger UTC-Unix-Zeitstempel einschließlich Millisekunden (z. B. 1537399655992).

  • url: Standard-HTTP-/HTTPS-URL-Format.

  • boolean: Standardwert „true“ oder „false“.

Sichtbarkeit für Kundenservicemitarbeiter: Sie können optional Daten an die CCAI Platform-Plattform übergeben, die für den menschlichen Kundenservicemitarbeiter ausgeblendet, aber für das Routing oder die Backend-Analyse verfügbar sind. Fügen Sie dazu "invisible_to_agent": true in das Datenobjekt ein.

Reservierte CRM-Schlüssel

Die CCAI Platform unterstützt bestimmte reservierte Schlüssel, die integrierte Verhaltensweisen in der Plattform auslösen, z. B. das Kennzeichnen eines Nutzers als VIP oder das Warnen eines Kundenservicemitarbeiters vor einem böswilligen Akteur. Diese müssen als boolean-Typen formatiert sein und werden nur akzeptiert, wenn die Nutzlast mit der sicheren JWT-Methode signiert ist.

  • reserved_verified_customer: Gibt an, ob ein Kunde von Ihren internen Systemen erfolgreich authentifiziert wurde.

  • reserved_bad_actor: Kennzeichnet den Nutzer für den Agenten als potenziellen Spammer oder betrügerisches Konto.

  • reserved_repeat_customer: Gibt an, ob dieser Kunde in letzter Zeit häufig den Support kontaktiert hat.

Beispielnutzlast mit reservierten Schlüsseln

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

Authentifizierungstokens verwalten

Das SDK bietet Methoden zum manuellen Aktualisieren oder Löschen des im Cache gespeicherten Authentifizierungstokens:

// Set a new auth token
CCAI.authService?.updateAuthToken("new_auth_token")

// Clear the current token (for example, on user logout)
CCAI.authService?.updateAuthToken(null)

JWT-Nutzlastschema für benutzerdefinierte Daten

Wenn Ihr Backend die endgültige Nutzlast erstellt, die mit Ihrem Company Secret Code signiert werden soll, muss es sich strikt an dieses Schema halten. Beachten Sie die obligatorischen Zeitstempel iat (Ausstellungszeitpunkt) und exp (Ablaufzeitpunkt).

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

Push-Benachrichtigungen aktivieren

Das SDK verwendet Push-Benachrichtigungen für Folgendes:

  • Eingehende Anrufe.

  • Bestimmte intelligente Aktionen und anrufbezogene Ereignisse.

  • Beibehalten des Status, wenn die App im Hintergrund ausgeführt wird.

Firebase einrichten

  1. Erstellen Sie ein Firebase-Projekt oder verwenden Sie ein vorhandenes.

  2. Registrieren Sie Ihre Android-App und laden Sie die Datei google-services.json herunter.

  3. Platzieren Sie google-services.json im Verzeichnis Ihres App-Moduls.

  4. Fügen Sie in der Datei build.gradle.kts auf Stammebene das Google-Dienste-Plug-in hinzu:

    // build.gradle.kts (Project)
    plugins {
        id("com.google.gms.google-services") version "4.4.2" apply false
    }
    
  5. Wenden Sie das Plug-in in der Datei build.gradle.kts auf App-Ebene an und fügen Sie die Firebase-Abhängigkeiten hinzu:

    // 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. Synchronisieren Sie das Projekt.

FCM-Token beim SDK registrieren

Registrieren Sie das FCM-Push-Token über pushNotificationService und leiten Sie eingehende FCM-Datennutzlasten an das SDK weiter. Ihre App ist für das Rendern von kundenorientierten Benachrichtigungen oder der Benutzeroberfläche für Anrufe verantwortlich.

onMessageReceived implementieren

Wenn Sie FCM verwenden, implementieren Sie einen Listener in Ihrer FirebaseMessagingService-Klasse für Push-Benachrichtigungen. Wenn diese nicht implementiert sind, funktioniert der Dienst nicht ordnungsgemäß.

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

onNewToken implementieren

Implementieren Sie auch die Methode onNewToken, um Token-Updates zu verarbeiten. So wird sichergestellt, dass das Headless Mobile SDK für Android das neueste Push-Benachrichtigungstoken erhält:

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

Dienst in AndroidManifest.xml registrieren

Fügen Sie den Firebase Messaging Service zu Ihrer AndroidManifest.xml hinzu, damit das System Push-Benachrichtigungen an Ihren Dienst senden kann:

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

Erstmalige Tokenregistrierung

Registrieren Sie beim Start der App (nach der SDK-Initialisierung) proaktiv das aktuelle FCM-Token:

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

Umgang mit Berechtigungen zum Senden von Benachrichtigungen (Android 13 und höher)

Unter Android 13 (API-Level 33) und höher benötigt deine App die Laufzeitberechtigung POST_NOTIFICATIONS, um Benachrichtigungen anzuzeigen. Das SDK bietet ein integriertes Dienstprogramm, um sie anzufordern:

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

Rufen Sie diese Methode früh im Lebenszyklus Ihrer App auf (z. B. während des Onboardings oder beim ersten Start), bevor Sie das FCM-Token registrieren, damit Push-Benachrichtigungen zugestellt werden können.