‫Google משתמשת בטכנולוגיית AI כדי לתרגם תוכן לשפה המועדפת עליך. בתרגומים כאלו עשויות להיות שגיאות.

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

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

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

‫Headless Mobile SDK ל-Android מאפשר לכם לשלב את היכולות של מוקד שירות הלקוחות של CCAI Platform בממשק משתמש מובנה משלכם ל-Android.

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

מוסיפים את מודולי CCAI Android SDK כתלות.
אפשר ליצור מסכים, תהליכים ועיצוב חזותי משלכם ב-Kotlin (מומלץ) או ב-Java.
אפשר להשתמש ב-SDK כדי:
- התחלה וניהול של סשנים של צ'אט ושיחות קוליות.
- להציע אפשרויות של אימייל, שיחת טלפון והפניה.
- תמיכה בפעולות חכמות, בקבצים מצורפים ובזרימות אחרי סיום הסשן (שביעות רצון לקוחות, סקרים, נציג וירטואלי).

פלטפורמת 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: 1.6.0 ואילך

הדרישות לגבי מופע של CCAI Platform

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

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

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

מפתח החברה וכתובת ה-URL של המארח – באפליקציית Android כדי לאתחל את ה-SDK.
קוד סודי של החברה – בקצה העורפי כדי לחתום על אסימוני JWT (‏JSON Web Tokens) שמשמשים לאימות משתמשים.

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

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

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

מצב האינטרנט או הרשת: לכל התקשורת של ה-SDK.
מיקרופון: לשיחות קוליות.
התראות: להתראות פוש של העברת הודעות בענן ב-Firebase ‏ (FCM).
אחסון / מדיה: לצירוף קבצים.
מצלמה: לצילום תמונות או סרטונים בפעולות חכמות.
צילום מסך: לשיתוף מסך (MediaProjection).

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

התראות

‫Headless Android SDK משתמש ב-FCM כדי לספק:

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

תצטרכו:

פרויקט Firebase.
קובץ google-services.json תקין במודול האפליקציה.
טיפול בטוקן של FCM ורישום באפליקציה.
התראה מותאמת אישית וממשק משתמש בשיחה באפליקציה.

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

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

פלטפורמת CCAI ו-SDK (בטיפול של פלטפורמת CCAI)

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

אימות באמצעות אסימוני JWT (‏JSON Web Tokens).
מטא-נתונים של ניתוב תורים וערוצים (צ'אט, שיחות קוליות, אימייל, קישורים להפנייה חיצונית).
ניהול מצב הפעילות בזמן אמת באמצעות אובייקטים של שירותים (chatService,‏ queueMenuService ועוד).
צינור התעבורה המאובטח לפעולות חכמות, לקבצים מצורפים ולשיתוף מסך.
לוגיקת ההפניה והערכה של ההיררכיה אחרי הסשן.

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

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

נקודות כניסה: לדוגמה, כרטיסיית עזרה או לחצן יצירת קשר.
תפריטים: איך מציגים תורים (לדוגמה, חיוב, תמיכה טכנית).
ממשק משתמש במהלך השיחה: בועות הצ'אט, מסכי השיחה ואמצעי הבקרה בהתאמה אישית.
מה האפליקציה עושה: קוראת לממשקי API של שירות SDK כדי להתחיל ולהסיים סשנים, צופה באירועי SDK באמצעות Kotlin Coroutines ו-Flow, ומניעה את הניווט ברכיבים.

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

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

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

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

נכנסים לפורטל האדמין של פלטפורמת CCAI באמצעות חשבון אדמין.
עוברים אל הגדרות > הגדרות למפתחים.
בקטע מפתח החברה וקוד סודי, מעתיקים את:
- מפתח החברה
- קוד סודי של החברה
רושמים את כתובת ה-URL של המארח – שם המארח של פלטפורמת CCAI (לדוגמה, your_subdomain.ccaiplatform.com).

תשתמשו ב:

באפליקציית Android: מפתח החברה וכתובת ה-URL של המארח.
בשרת הקצה העורפי: קוד סודי של החברה לחתימה על JWT לצורך אימות משתמשי קצה, ונתונים והקשר מותאמים אישית אופציונליים שמשמשים את CCAI Platform.

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

ערכת ה-SDK של Headless משתמשת בארכיטקטורה מודולרית. מתקינים את ליבת 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.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" }

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

בקובץ 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 לקריאות חוזרות לאימות. השיטה העיקרית היא פונקציית השהיה של Kotlin‏ ccaiShouldAuthenticate() שה-SDK קורא לה כשהוא צריך אסימון JWT.

import com.ccaiplatform.ccaikit.CCAIDelegate

class MyCCAIDelegate : CCAIDelegate {

    /**
     *   Called by the SDK when it needs a signed JWT for authentication.
     *   This is a suspend function - you can make network calls here.
     *
     *   @return The auth token returned by `authService.authenticate(jwt)`,

*   or null on failure. This is what the SDK expects - not the raw JWT.
     */
    override suspend fun ccaiShouldAuthenticate(): String? {
        return try {
            // 1. Call your backend server to get a signed JWT
            val jwt = MyBackendApi.getSignedJwt() ?: return null

            // 2. Exchange the JWT for an auth token using authService - this is
            //    what the SDK expects to be returned (not the raw JWT).
            CCAI.authService?.authenticate(jwt)
        } catch (e: Exception) {
            null // Return null to signal authentication failure
        }
    }
}

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

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

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

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

מפעילים את ה-SDK במחלקה של האפליקציה המותאמת אישית באמצעות אובייקט CCAI singleton:

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` חומר עזר בנושא הגדרות

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 זמינים

אחרי האתחול, אפשר לגשת לשירותים שונים דרך אובייקט הסינגלטון CCAI:

val authService = CCAI.authService
val companyService = CCAI.companyService
val queueMenuService = CCAI.queueMenuService
val optionsService = CCAI.optionsService
val languageService = CCAI.languageService
val pushNotificationService = CCAI.pushNotificationService
val chatService = CCAI.chatService              // Only available after initializeChat()
val screenShareService = CCAI.screenShareService // Only available after initializeScreenShare()
val rateService = CCAI.rateService              // For CSAT ratings and survey submission
val callService = CCAI.callService              // Only available after initializeCall()

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

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

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

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

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

ערכת ה-SDK לנייד ללא ממשק משתמש (headless) ל-Android משתמשת באסימוני JWT‏ (JSON Web Tokens) כדי לאמת משתמשים ולהעביר באופן מאובטח מידע הקשרי לסוכן ה-CRM.

איך זה עובד

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

ערכת ה-SDK קובעת שצריך לאמת את המשתמש.
הוא קורא ל-method CCAIDelegate –‏ ccaiShouldAuthenticate() – שהיא פונקציית השהיה.
האפליקציה חותמת על JWT מרחוק בשרת הקצה העורפי באמצעות המשתנה `Company
האפליקציה חותמת על JWT מרחוק בשרת הקצה העורפי באמצעות Company Secret Code.
האפליקציה מעבירה את ה-JWT החתום אל CCAI.authService?.authenticate(jwt) כדי להחליף אותו באסימון אימות.
אסימון האימות מוחזר ל-SDK כדי להשלים את החיבור.

הטמעה של `CCAIDelegate` לאימות

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

ממשק `CCAIDelegate`

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

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

דוגמה מלאה עם חתימת JWT (לעיון ולבדיקה בלבד)

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

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

אם רוצים להעביר נתונים הקשריים לסוכן (לדוגמה, מערכת ההפעלה הנוכחית של המכשיר של המשתמש, המיקום או רמת החשבון), צריך להוסיף אובייקט 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 שמוסתרים מהסוכן האנושי אבל זמינים לניתוב או לניתוח בקצה העורפי. כדי לעשות את זה, צריך לכלול את "invisible_to_agent": true באובייקט הנתונים.

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

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

‫reserved_verified_customer: מציין אם לקוח עבר אימות בהצלחה במערכות הפנימיות שלכם.
‫reserved_bad_actor: מסמן את המשתמש לסוכן כמישהו שעשוי להיות שולח ספאם או כחשבון שמקורו בתרמית.
‫reserved_repeat_customer: מציין אם הלקוח הזה פנה לתמיכה לעיתים קרובות לאחרונה.

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

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

אזהרה: אם הערך של cacheAuthToken הוא true (ברירת המחדל ב-InitOptions), ה-SDK שומר במטמון את אסימון האימות כדי שאפשר יהיה להשתמש בו שוב בהפעלות חוזרות של האפליקציה בלי להיכנס שוב לחשבון. האסימון שנשמר במטמון ישמש עד שתוקפו יפוג או עד שהוא יימחק באופן מפורש. צריך לנקות את הטוקן שנשמר במטמון בכל פעם שנתונים שקשורים למשתמש משתנים – בעיקר באירועים של יציאה מהחשבון, מעבר בין משתמשים או עדכוני פרופיל. אם לא תעשו את זה, יכול להיות ש-SDK יאמת את הסשן של המשתמש הקודם. צריך להתקשר אל 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

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

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

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

בקובץ 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")
}

מסנכרנים את הפרויקט.

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

רושמים את טוקן ה-Push של FCM דרך pushNotificationService ומעבירים את מטען הנתונים הנכנס של 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, כדי שניתן יהיה לשלוח התראות פוש.