‫Headless Mobile SDK ל-Android: תחילת העבודה

במסמך הזה מוסבר איך לשלב את ה-SDK באפליקציה ל-Android ולהתאים אותו אישית.

קדימה, מתחילים

בעזרת Headless Mobile SDK ל-Android, אתם יכולים לשלב את היכולות של מוקד השירות של פלטפורמת CCAI בממשק המשתמש המובנה שלכם ב-Android.

במקום להציג ווידג'ט עם המיתוג של CCAI Platform, אתם:

  • מוסיפים את המודולים של CCAI Android SDK כיחסי תלות.

  • אתם יכולים ליצור מסכים, תהליכים ועיצוב חזותי משלכם ב-Kotlin (מומלץ) או ב-Java.

  • אתם יכולים להשתמש ב-SDK כדי:

    • להתחיל ולנהל שיחות צ'אט ושיחות קוליות.

    • להציע אפשרויות לאימייל, לשיחת טלפון ולהפניה.

    • תמיכה בפעולות חכמות, בקבצים מצורפים ובתהליכים לאחר הסשן (CSAT, סקרים, נציג וירטואלי).

פלטפורמת CCAI מטפלת בלוגיקה של המוקד (ניתוב, תורים, ערוצים, הגדרות, דיווח). אתם הבעלים של כל חוויית השימוש באפליקציה (ממשק המשתמש, התהליכים והמיתוג).

אם אתם מעדיפים ממשק משתמש מובנה מראש עם עיצוב שניתן להגדרה, השתמשו ב-SDK הרגיל לנייד.

דרישות וסביבות נתמכות

בקטע הזה מתוארות הדרישות והסביבות הנתמכות של Headless Mobile SDK ל-Android.

דרישות לפלטפורמת Android

אלה דרישות הפלטפורמה שחלות על Android:

  • גרסת Android מינימלית: Android 6.0 (רמת API‏ 23) ואילך

  • ‫Compile SDK: ‏36 (מומלץ)

  • שפות נתמכות: Kotlin (מומלץ) או Java

  • תאימות ל-Java: ‏Java 17 ואילך

  • ‫Gradle או Android Studio: גרסה עדכנית של הפלאגין של Android Gradle ושל Android Studio שתואמת לאפליקציה ולגרסת ה-SDK שבה אתם משתמשים

  • ‫Kotlin: גרסה 2.0 ומעלה

דרישות לגבי המכונה של פלטפורמת CCAI

כדי לקבל את הפרטים הבאים, תצטרכו גישה להגדרות המפתחים במכונה של פלטפורמת CCAI:

  • מפתח החברה

  • קוד סודי של החברה

  • כתובת ה-URL של המארח – שם המארח של פלטפורמת CCAI (לדוגמה, your_subdomain.ccaiplatform.com)

הערכים האלה משמשים למטרות הבאות:

  • מפתח החברה וכתובת ה-URL של המארח – באפליקציה ל-Android כדי להפעיל את ה-SDK.

  • קוד סודי של החברה – בקצה העורפי שלכם, כדי לחתום על אסימוני אינטרנט מסוג JSON‏ (JWT) שמשמשים לאימות משתמשים.

רשתות והרשאות

האפליקציה צריכה לאפשר תנועה יוצאת לנקודות הקצה של פלטפורמת CCAI ולכל נקודות הקצה של ספק הקול שהגדרתם.

הרשאות Android אופייניות כוללות (הרשימה בפועל עשויה להשתנות בהתאם לגרסת ה-SDK ולקבוצת התכונות):

  • מצב האינטרנט או הרשת: לכל התקשורת של ה-SDK.

  • מיקרופון: לשיחות טלפון.

  • התראות: רק אם משתמשים בהתראות (ראו התראות בהמשך).

  • אחסון / מדיה: רק אם האפליקציה קוראת תמונות, סרטונים או קבצים ישירות מנפח אחסון משותף. לא צריך הרשאה כדי לגשת לקבצים של האפליקציה עצמה ולכלי לבחירת תמונות של המערכת.

  • מצלמה: לצילום תמונות או סרטונים בפעולות חכמות.

  • צילום מסך: לשיתוף המסך (MediaProjection).

להצהיר על הרשאות בתחילת ההפעלה ולבקש אותן בהתאם להנחיות של Android OS.

התראות

‫Headless Android SDK משתמש ב-FCM כדי להעביר:

  • התראות על שיחות נכנסות.

  • הודעות מסוימות שקשורות לפעולות חכמות ולשיחות.

  • עדכונים שעוזרים לשמור על המצב כשהאפליקציה פועלת ברקע.

מה צריך:

  • יש לכם פרויקט Firebase.

  • קובץ google-services.json תקין במודול של האפליקציה.

  • טיפול באסימוני FCM ורישום שלהם באפליקציה.

  • התראות בהתאמה אישית וממשק משתמש בשיחה באפליקציה.

איך ה-Android SDK ללא ממשק משתמש משתלב באפליקציה

אפשר לחלק את Headless Mobile SDK ל-Android לשלוש שכבות:

הפלטפורמה ו-SDK של CCAI Platform (מטופלים על ידי CCAI Platform)

ה-SDK יוצר אינטראקציה מאובטחת עם פלטפורמת CCAI Platform ומספק:

  • אימות באמצעות אסימוני אינטרנט מסוג JSON‏ (JWT).

  • מטא-נתונים של ניתוב תורים וערוצים (צ'אט, שיחת טלפון, אימייל, קישורים להסטה חיצונית).

  • ניהול מצב הסשן בזמן אמת באמצעות אובייקטים של שירות (chatService, queueMenuService ועוד).

  • צינור העברת הנתונים המאובטח לפעולות חכמות, לקבצים מצורפים ולשיתוף המסך.

  • לוגיקת הסטה והערכת היררכיה אחרי הסשן.

אפליקציית Android (ממשק משתמש ולוגיקה – בטיפול שלכם)

אתם שולטים בכל החוויה החזותית וחוויית הניווט:

  • נקודות כניסה: לדוגמה, כרטיסיית עזרה או לחצן יצירת קשר.

  • תפריטים: הדרך שבה אתם מציגים את התורים (לדוגמה, חיוב, תמיכה טכנית).

  • ממשק המשתמש במהלך השיחה: בועות הצ'אט, מסכי השיחה והלחצנים המותאמים אישית.

  • מה האפליקציה עושה: קוראת לממשקי ה-API של שירות ה-SDK כדי להתחיל ולסיים סשנים, צופה באירועי SDK באמצעות Kotlin Coroutines ו-Flow, ומפעילה ניווט ברכיבים.

הגדרת פורטל האדמין של פלטפורמת CCAI

האדמינים שלכם ב-CCAI Platform מגדירים את כללי ההתנהלות (שעות הפעילות, הערוצים הזמינים, סף זמן ההמתנה והסקרים). ה-SDK קורא את ההגדרות האלה וחושף אותן לאפליקציה כנתונים גולמיים וכאירועים. אתם מחליטים איך לצייר את התצורה הזו על המסך.

אחזור פרטי הכניסה של החברה

לפני שמשלבים את ה-SDK, צריך לקבל את פרטי הכניסה מהמופע של פלטפורמת CCAI:

  1. נכנסים לפורטל Admin של פלטפורמת CCAI באמצעות חשבון אדמין.

  2. עוברים אל הגדרות > הגדרות למפתחים.

  3. בקטע מפתח החברה וקוד סודי, מעתיקים את:

    • מפתח החברה

    • קוד סודי של החברה

  4. שימו לב לכתובת ה-URL של המארח – שם המארח של פלטפורמת CCAI (לדוגמה, your_subdomain.ccaiplatform.com).

אתם תשתמשו:

  • באפליקציה ל-Android: מפתח החברה וכתובת ה-URL של המארח.

  • בשרת בק-אנד: קוד סודי של החברה לחתימה על אסימוני JWT לאימות משתמשי קצה, ונתונים והקשר אופציונליים בהתאמה אישית שמשמשים את פלטפורמת CCAI.

הוספת ה-SDK לאפליקציה ל-Android

ה-SDK ללא ממשק משתמש מבוסס על ארכיטקטורה מודולרית. מתקינים את ה-core CCAIKit לצד המודולים הספציפיים של התכונות שהאפליקציה דורשת (לדוגמה, CCAIChat או CCAIScreenShare).

הוספת מאגר Maven של CCAI

מוסיפים את מאגר ה-Maven של CCAI לקובץ settings.gradle.kts (או לקובץ build.gradle ברמה הבסיסית) של הפרויקט:

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

הגדרת קטלוג הגרסאות של Gradle (מומלץ)

‫Google Cloud ממליצה להשתמש בקטלוג גרסאות של Gradle כדי לנהל את יחסי התלות של ה-SDK. מוסיפים את הפרטים הבאים אל gradle/libs.versions.toml:

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

הוספת יחסי תלות

בקובץ build.gradle.kts ברמת האפליקציה, מוסיפים את ה-SDK הראשי ואת המודולים של התכונות הספציפיות:

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

אם אתם לא משתמשים בקטלוג הגרסאות, אתם יכולים להצהיר על יחסי תלות באופן ישיר:

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
}

אתחול והגדרה

מפעילים את ה-SDK בזמן הפעלת האפליקציה. בגלל הארכיטקטורה המודולרית של ה-SDK, קודם צריך להפעיל את מערכת הליבה של פלטפורמת CCAI, ואז לרשום את ספקי הערוצים הספציפיים (כמו chat או screen share).

מטמיעים את הממשק CCAIDelegate

ערכת ה-SDK משתמשת בממשק CCAIDelegate לקריאות חוזרות (callbacks) של אימות. השיטה העיקרית היא פונקציית השהיה של Kotlin‏ ccaiShouldAuthenticate(), שה-SDK קורא לה כשהוא צריך JWT.

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

קטע הקוד שלמעלה מציג את התהליך המינימלי של שני השלבים (חתימה ← אימות ← החזרה).

במאמר אימות משתמשי קצה והעברת נתונים בהתאמה אישית מפורט חוזה האימות המלא, כולל:

  • איך לחתום על ה-JWT בקצה העורפי,
  • איך authenticate(jwt) מחליף אותו באסימון אימות,
  • שמירת טוקנים במטמון וביטול תוקף של טוקנים, וגם
  • דוגמאות מעשיות עם טיפול בשגיאות.

הפעלת ה-SDK במחלקת האפליקציה

מפעילים את ה-SDK במחלקה Application המותאמת אישית באמצעות אובייקט ה-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.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

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

מוודאים שמחלקת האפליקציה בהתאמה אישית רשומה:

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

שירותי SDK זמינים

אחרי ההפעלה, אפשר לגשת לשירותים שונים דרך האובייקט היחיד (singleton) של CCAI:

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

אחזור הגדרות החברה

אחרי ההפעלה, אפשר לאחזר את ההגדרות ברמת החברה באמצעות companyService. האפשרות הזו שימושית לאכלוס של הכלי לבחירת שפה, להצגת שם החברה או לקריאת פרטים ליצירת קשר עם התמיכה לפני שהמשתמש נכנס לתור.

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

אימות משתמשי קצה והעברת נתונים בהתאמה אישית

ערכת Headless Mobile SDK ל-Android משתמשת באסימוני אימות מסוג JSON ‏(JWT) כדי לאמת משתמשים ולהעביר בצורה מאובטחת מידע לפי הקשר למערכת ה-CRM של הנציג.

איך זה עובד

ערכת ה-SDK משתמשת בתהליך אימות אסינכרוני פשוט בשני שלבים:

  1. ערכת ה-SDK קובעת שהיא צריכה לאמת את המשתמש.

  2. הוא קורא ל-method CCAIDelegate – ccaiShouldAuthenticate() – שהיא פונקציית השהיה.

  3. האפליקציה קוראת לשרת בק-אנד כדי לקבל JWT חתום.

  4. לאחר מכן, האפליקציה מעבירה את ה-JWT החתום אל CCAI.authService?.authenticate(jwt) כדי להחליף אותו באסימון אימות.

  5. אסימון האימות מוחזר ל-SDK כדי להשלים את החיבור.

מטמיעים את CCAIDelegate לאימות

האפליקציה צריכה להטמיע את הממשק של CCAIDelegate. ה-SDK קורא ל-suspend method הראשון כשהוא צריך אימות.

ממשק CCAIDelegate

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

דוגמה להטמעה (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
        }
    }
}

העברת נתונים מותאמים אישית ל-CRM

אם רוצים להעביר נתונים לפי הקשר לנציג (לדוגמה, מערכת ההפעלה הנוכחית של המכשיר, המיקום או רמת החשבון של המשתמש), ה-backend צריך להוסיף אובייקט custom_data למטען הייעודי (payload) של ה-JWT לפני החתימה עליו.

כל פריט של נתוני לקוחות צריך להיות בפורמט של אובייקט JSON שמכיל תווית (מה שהנציג רואה), ערך וסוג.

סוגי נתונים נתמכים

  • ‫string: טקסט רגיל (לדוגמה, "Pixel 8 Pro").

  • ‫number: מספרים שלמים או מספרים עם נקודה צפה (לדוגמה, 1234 או 99.99).

  • date: חותמת זמן של מערכת Unix לפי שעון UTC, באורך 13 ספרות, כולל אלפיות השנייה (לדוגמה, 1537399655992).

  • ‫url: פורמט סטנדרטי של כתובת URL מסוג HTTP או HTTPS.

  • ‫boolean: ערך רגיל של True או False.

חשיפה לנציג: אתם יכולים להעביר נתונים לפלטפורמת CCAI Platform שמוסתרים מהנציג האנושי, אבל זמינים לניתוב או לניתוח בקצה העורפי. כדי לעשות את זה, צריך לכלול את "invisible_to_agent": true באובייקט הנתונים.

מפתחות CRM שמורים

פלטפורמת CCAI תומכת במפתחות שמורים ספציפיים שמפעילים התנהגויות מובנות בפלטפורמה, כמו סימון משתמש כ-VIP או אזהרה לנציג לגבי גורם זדוני. הם חייבים להיות בפורמט של סוגי boolean ויתקבלו רק אם המטען הייעודי (payload) נחתם באמצעות השיטה המאובטחת JWT.

  • ‫reserved_verified_customer: מציין אם הלקוח אומת בהצלחה על ידי המערכות הפנימיות שלכם.

  • ‫reserved_bad_actor: מסמן את המשתמש לנציג כחשבון שעלול להיות ספאמר או חשבון שמקורו בתרמית.

  • ‫reserved_repeat_customer: מציין אם הלקוח פנה לאחרונה לתמיכה לעיתים קרובות.

מטען ייעודי לדוגמה עם מפתחות שמורים

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

ניהול טוקנים של אימות

ה-SDK מספק שיטות לעדכון או לניקוי ידני של אסימון האימות שנשמר במטמון:

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

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

סכימת המטען הייעודי (payload) של JWT לנתונים בהתאמה אישית

כשה-backend יוצר את המטען הייעודי (payload) הסופי שייחתם באמצעות Company Secret Code, הוא חייב לפעול בדיוק לפי הסכימה הזו. שימו לב לחותמות הזמן החובה iat (הונפק בתאריך) ו-exp (תפוגה).

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

הפעלת התראות

ערכת ה-SDK משתמשת בהתראות כדי:

  • שיחות נכנסות.

  • פעולות חכמות מסוימות ואירועים שקשורים לשיחות.

  • שמירה על המצב כשהאפליקציה פועלת ברקע.

הגדרת Firebase

  1. יוצרים פרויקט ב-Firebase או משתמשים בפרויקט קיים.

  2. רושמים את אפליקציית Android ומורידים את הקובץ google-services.json.

  3. ממקמים את google-services.json בספריית המודולים של האפליקציה.

  4. בקובץ build.gradle.kts ברמת הבסיס, מוסיפים את הפלאגין של שירותי Google:

    // build.gradle.kts (Project)
    plugins {
        id("com.google.gms.google-services") version "4.4.2" apply false
    }
    
  5. בקובץ build.gradle.kts ברמת האפליקציה, מחילים את הפלאגין ומוסיפים יחסי תלות של 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. מסנכרנים את הפרויקט.

רישום הטוקן של FCM ב-SDK

רושמים את טוקן ה-FCM להתראות דרך pushNotificationService ומעבירים את המטען הייעודי (payload) של נתוני ה-FCM הנכנסים ל-SDK. האפליקציה שלכם אחראית לעיבוד של כל התראה שמוצגת ללקוח או של ממשק המשתמש במהלך השיחה.

הטמעה של onMessageReceived

אם אתם משתמשים ב-FCM, הטמיעו מאזין (listener) בכיתה FirebaseMessagingService להתראות. אם לא תטמיעו את התפקידים האלה, השירות לא יפעל כמו שצריך.

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

צריך גם להטמיע את השיטה onNewToken כדי לטפל בעדכוני טוקנים. כך אפשר לוודא ש-Headless Mobile SDK ל-Android מקבל את הטוקן העדכני של ההתראה:

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

רישום השירות ב-AndroidManifest.xml

מוסיפים את שירות העברת ההודעות של Firebase אל AndroidManifest.xml כדי שהמערכת תוכל להעביר הודעות דחיפה לשירות:

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

רישום ראשוני של טוקן

כשהאפליקציה מופעלת (אחרי האתחול של ה-SDK), רושמים באופן יזום את הטוקן הנוכחי של FCM:

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

טיפול בהרשאות לשליחת התראות (Android מגרסה 13 ואילך)

ב-Android 13 (רמת API‏ 33) ומעלה, האפליקציה צריכה את ההרשאה POST_NOTIFICATIONS בתחילת ההפעלה כדי להציג התראות. ב-SDK יש כלי מובנה לבקשת ההרשאה:

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

צריך להפעיל את הפונקציה הזו בשלב מוקדם במחזור החיים של האפליקציה (לדוגמה, במהלך ההגדרה הראשונית או בהפעלה הראשונה) לפני רישום האסימון של FCM, כדי שאפשר יהיה לשלוח התראות.