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 CCAI Platform-Branding zu präsentieren,

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

• Sie können eigene Bildschirme, Abläufe und visuelle Designs in Kotlin (empfohlen) oder Java erstellen.

• Mit dem SDK können Sie:

  • Chat- und Sprachchatsitzungen starten und verwalten

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

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

Die CCAI Platform übernimmt die Contact Center-Logik (Routing, Warteschlangen, Kanäle, Konfiguration, Berichterstellung). Sie sind für die gesamte App verantwortlich, einschließlich Benutzeroberfläche, Abläufe und Branding.

Wenn Sie eine vorgefertigte Benutzeroberfläche mit konfigurierbaren Designs 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:

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

• Compile SDK: 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 verwendeten SDK-Version kompatibel ist

• Kotlin-Version: 1.6.0 oder höher

Anforderungen an CCAI Platform-Instanzen

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

• Unternehmensschlüssel

• Geheimcode des Unternehmens

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

Diese Werte werden für Folgendes verwendet:

• Unternehmensschlüssel und Host-URL: in Ihrer Android-App zum Initialisieren des SDK.

• Geheimer Unternehmenscode: In Ihrem Backend zum Signieren von JSON Web Tokens (JWTs), die zur Authentifizierung von Nutzern verwendet werden.

Netzwerk und Berechtigungen

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

Typische Android-Berechtigungen sind (die tatsächliche Liste kann je nach SDK-Version und Feature-Set variieren):

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

• Mikrofon: für Sprachanrufe.

• Benachrichtigungen: für Firebase Cloud Messaging-Push-Benachrichtigungen (FCM).

• Speicher / Medien: für Anhänge.

• Kamera: für die Aufnahme von Fotos oder Videos in Smart Actions.

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

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

Push-Benachrichtigungen

Das Headless Android SDK verwendet FCM für die folgenden Zwecke:

• Benachrichtigungen über eingehende Anrufe

• Bestimmte Nachrichten zu Smart Actions und Anrufen

• Updates, die dazu beitragen, den Status beizubehalten, wenn die App im Hintergrund ausgeführt wird.

Folgendes wird benötigt:

• Ein Firebase-Projekt

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

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

• Benutzerdefinierte Benachrichtigungs- und Anruf-UI in Ihrer App.

So wird das Headless Android SDK in Ihre App eingebunden

Das Headless Mobile SDK für Android besteht aus drei Ebenen:

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 die Warteschlangen- und Kanalweiterleitung (Chat, Sprachanruf, E‑Mail, externe Weiterleitungslinks).

• Echtzeit-Verwaltung des Sitzungsstatus mit Dienstobjekten (chatService, queueMenuService usw.).

• Die sichere Transportpipeline für Smart Actions, Dateianhänge und Bildschirmfreigabe.

• Ablenkungslogik und Hierarchiebewertung nach der Sitzung.

Ihre Android-App (Benutzeroberfläche und Logik – von Ihnen verwaltet)

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

• Einstiegspunkte: z. B. der Tab Hilfe oder die Schaltfläche Kontakt.

• Menüs: So werden Warteschlangen angezeigt, z. B. Abrechnung, Technischer Support.

• UI während der Sitzung: Ihre benutzerdefinierten Chatblasen, Anruf-Filter und Steuerelemente.

• Funktionsweise Ihrer App: Ruft SDK-Dienst-APIs auf, um Sitzungen zu starten und zu beenden, beobachtet SDK-Ereignisse mit Kotlin-Coroutines und Flow und steuert die Komponentennavigation.

Konfiguration des CCAI Platform Admin Portal

Ihre CCAI Platform-Administratoren konfigurieren die Regeln für die Interaktion (Betriebszeiten, verfügbare Channels, Wartezeitschwellen 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.

Unternehmensanmeldedaten abrufen

Bevor Sie das SDK einbinden, müssen Sie die Anmeldedaten aus Ihrer CCAI Platform-Instanz abrufen:

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 geheimer Code Folgendes:

   • Unternehmensschlüssel

   • Geheimcode des Unternehmens

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

Sie benötigen:

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

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

SDK in Ihre Android-App einbinden

Das Headless SDK verwendet eine modulare Architektur. Sie installieren das Core-Modul 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 der settings.gradle.kts-Datei Ihres Projekts (oder der build.gradle-Datei des Stammverzeichnisses) 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 die Verwendung eines Gradle-Versionskatalogs zur Verwaltung von SDK-Abhängigkeiten. Fügen Sie Folgendes zu gradle/libs.versions.toml hinzu:

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

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 Kernsystem der CCAI-Plattform initialisieren und dann die spezifischen Channel-Anbieter (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 vom SDK aufgerufen wird, wenn ein JWT benötigt wird.

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

Das obige Snippet zeigt den minimalen zweistufigen Ablauf (sign → authenticate → return).

Den vollständigen Authentifizierungsvertrag finden Sie unter Endnutzer authentifizieren und benutzerdefinierte Daten übergeben. Er enthält unter anderem:

• wie Sie das JWT in Ihrem Backend signieren,
• wie authenticate(jwt) es gegen ein Autorisierungstoken eintauscht,
• Token-Caching und ‑Ungültigmachung und
• Beispiele mit Fehlerbehandlung.

SDK in Ihrer Anwendungsklasse initialisieren

Initialisieren Sie das SDK in Ihrer benutzerdefinierten Anwendungsklasse 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.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"
        //     )
        // )
    }
}

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

Prüfen Sie, ob 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 CCAI-Singleton-Objekt auf verschiedene Dienste zugreifen:

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

Hinweis:CCAI ist ein Objekt (Singleton) in Kotlin. Sie greifen also direkt über CCAI.propertyName auf Eigenschaften zu. Es ist nicht erforderlich, getInstance() aufzurufen oder einen gemeinsamen Accessor zu verwenden.

Warnung:Für callService ist ein eigener Initialisierungsschritt erforderlich. Im Gegensatz zu den anderen Core-Diensten befindet sich CCAI.callService im Modul CCAICall und wird erst als Erweiterungseigenschaft für CCAI registriert, nachdem Sie CCAI.initializeCall(context) aufgerufen haben. Wenn Sie diesen Schritt überspringen, ist CCAI.callService zur Laufzeit null und die Planungs-APIs im Headless Mobile SDK for Android: voice, screen share, scheduled call und email sind nicht erreichbar.

Unternehmenskonfiguration wird abgerufen

Nach der Initialisierung können Sie die Konfiguration auf Unternehmensebene mit companyService abrufen. Dies ist nützlich, um Sprachauswahlen zu füllen, den Namen des Unternehmens anzuzeigen oder Supportkontaktdaten zu lesen, bevor der Nutzer in eine Warteschlange gelangt.

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

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

Hinweis :Die von companyService zurückgegebene Liste languages spiegelt wider, was Ihre Administratoren im CCAI Platform-Portal aktiviert haben. Damit können Sie eine Sprachauswahl in den Einstellungen Ihrer App erstellen.

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 Kundenservicemitarbeiters zu übergeben.

Funktionsweise

Das SDK verwendet einen vereinfachten asynchronen Authentifizierungsvorgang in zwei Schritten:

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

2. Dabei wird die Methode CCAIDelegate – ccaiShouldAuthenticate() – aufgerufen, die eine suspend-Funktion ist.

3. Ihre App signiert ein JWT remote auf Ihrem Backend-Server mit Ihrem `Company

4. Ihre App signiert ein JWT remote auf Ihrem Backend-Server mit Ihrem Company Secret Code.

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

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

Warnung :Die JWT-Signierung muss immer auf Ihrem Backend-Server erfolgen. Betten Sie die Company Secret Code niemals in Ihre kompilierte Android-App ein, da dies eine schwerwiegende Sicherheitslücke darstellt.

CCAIDelegate für die Authentifizierung implementieren

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

CCAIDelegate-Schnittstelle

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

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

Vollständiges Beispiel mit JWT-Signierung (nur zu Referenz- und Testzwecken)

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

Benutzerdefinierte Daten an das CRM übergeben

Wenn Sie Kontextdaten an den Agent übergeben möchten, z. B. das aktuelle Gerätebetriebssystem, den Standort oder die Kontostufe des Nutzers, muss Ihr Backend vor dem Signieren ein custom_data-Objekt in die JWT-Nutzlast einfügen.

Jeder benutzerdefinierte Datensatz muss als JSON-Objekt formatiert sein, das ein Label (das, was der Kundenservicemitarbeiter 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 mit Millisekunden (z. B. 1537399655992).

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

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

Sichtbarkeit des Kundenservicemitarbeiters: Sie können optional Daten an die CCAI-Plattform übergeben, die für den Kundenservicemitarbeiter ausgeblendet, aber für das Routing oder die Backend-Analyse verfügbar sind. Dazu müssen Sie "invisible_to_agent": true in das Datenobjekt einfügen.

Reservierte CRM-Schlüssel

Die CCAI-Plattform unterstützt bestimmte reservierte Schlüssel, die integrierte Verhaltensweisen auf der Plattform auslösen, z. B. das Kennzeichnen eines Nutzers als VIP oder das Warnen eines Kundenservicemitarbeiters vor einem böswilligen Akteur. Sie 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)

Warnung :Wenn cacheAuthToken auf true gesetzt ist (Standardeinstellung in InitOptions), wird das Autorisierungstoken im SDK im Cache gespeichert, damit es bei App-Starts wiederverwendet werden kann, ohne dass eine erneute Anmeldung erforderlich ist. Das im Cache gespeicherte Token wird verwendet, bis es abläuft oder explizit gelöscht wird. Sie müssen das im Cache gespeicherte Token löschen, wenn sich nutzerbezogene Daten ändern, insbesondere bei Abmeldeereignissen, Nutzerwechseln oder Profilaktualisierungen. Wenn Sie dies nicht tun, kann es passieren, dass das SDK die Sitzung des vorherigen Nutzers authentifiziert. Rufen Sie updateAuthToken(null) im Rahmen Ihrer Abmelderoutine auf.

Benutzerdefiniertes Schema für die JWT-Nutzlast

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 (ausgestellt am) und exp (Ablaufdatum).

{
  "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 anrufrelevante Ereignisse.

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

Firebase einrichten

1. Erstellen Sie ein neues 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 App-Modulverzeichnis.

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 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-Daten-Payloads an das SDK weiter. Ihre App ist für das Rendern aller benachrichtigungsbezogenen oder In-Call-Benutzeroberflächen verantwortlich, die Kunden angezeigt werden.

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 richtig.

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

Hinweis :CCAI.pushNotificationService?.handlePushNotification() verarbeitet die Benachrichtigung auf Plattformebene. Erstellen Sie Ihren eigenen Benachrichtigungs-Renderer für sichtbare Benachrichtigungen, Bildschirme für eingehende Anrufe und app-spezifische Benachrichtigungen.

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 aktuelle 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 Ihrem AndroidManifest.xml den Firebase Messaging Service 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>

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

Verwaltung der Berechtigung zum Senden von Benachrichtigungen (Android 13 und höher)

Unter Android 13 (API‑Level 33) müssen die oben genannten Apps die Laufzeitberechtigung POST_NOTIFICATIONS anfordern. Das SDK bietet ein integriertes Dienstprogramm dafür:

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 Funktion 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.