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,queueMenuServiceusw.)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:
Melden Sie sich mit einem Administratorkonto im CCAI Platform-Admin-Portal an.
Gehen Sie zu Einstellungen > Entwicklereinstellungen.
Kopieren Sie unter Unternehmensschlüssel und Geheimcode Folgendes:
Unternehmensschlüssel
Geheimer Code des Unternehmens
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:
Das SDK stellt fest, dass der Nutzer authentifiziert werden muss.
Sie ruft die Methode
CCAIDelegate(ccaiShouldAuthenticate()) auf, die eine Sperrfunktion ist.Ihre App ruft Ihren Backend-Server auf, um ein signiertes JWT abzurufen.
Ihre App übergibt das signierte JWT dann an
CCAI.authService?.authenticate(jwt), um es gegen ein Authentifizierungstoken auszutauschen.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
Erstellen Sie ein Firebase-Projekt oder verwenden Sie ein vorhandenes.
Registrieren Sie Ihre Android-App und laden Sie die Datei
google-services.jsonherunter.Platzieren Sie
google-services.jsonim Verzeichnis Ihres App-Moduls.Fügen Sie in der Datei
build.gradle.ktsauf Stammebene das Google-Dienste-Plug-in hinzu:// build.gradle.kts (Project) plugins { id("com.google.gms.google-services") version "4.4.2" apply false }Wenden Sie das Plug-in in der Datei
build.gradle.ktsauf App-Ebene an und fügen Sie dieFirebase-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") }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.