This document explains how to integrate and customize the SDK in your Android
application.

## Get started

The Headless Mobile SDK for Android lets you integrate
CCAI Platform's contact center capabilities into your own built-in
Android UI.

Instead of presenting a CCAI Platform-branded widget, you:

- Add the CCAI Android SDK modules as dependencies.

- Build your own screens, flows, and visual design in Kotlin (recommended) or
  Java.

- Use the SDK to:

  - Start and manage chat and voice sessions.

  - Offer email, voice call, and deflection options.

  - Support smart actions, attachments, and post-session flows (CSAT,
    surveys, virtual agent).

CCAI Platform handles the contact center logic (routing, queues,
channels, configuration, reporting). You own the entire app experience (UI,
flows, and branding).

If you'd prefer a prebuilt UI with configurable theming, use the standard mobile
SDK.

## Requirements and supported environments

This section describes requirements and supported environments for Headless
Mobile SDK for Android.

### Android platform requirements

The following platform requirements apply to Android:

- **Minimum Android version**: Android 6.0 (API level 23) or later

- **Compile SDK**: 36 (recommended)

- **Supported languages**: Kotlin (recommended) or Java

- **Java compatibility**: Java 17+

- **Gradle / Android Studio**: a recent Android Gradle Plugin and Android
  Studio version compatible with your app and the SDK release you're using

- **Kotlin version**: 2.0 or higher

### CCAI Platform instance requirements

You will need access to your CCAI Platform instance's **Developer
settings** to obtain:

- **Company key**

- **Company secret code**

- **Host URL** --- the hostname for the CCAI platform (for example,
  your_subdomain.ccaiplatform.com)

These values are used for:

- **Company key** and **Host URL** --- in your Android app to initialize
  the SDK.

- **Company secret code** --- in your backend to sign JSON Web Tokens
  (JWT) used to authenticate users.

### Networking and permissions

Your app must allow outbound traffic to CCAI Platform endpoints and any
voice provider endpoints you have configured.

Typical Android permissions include (the actual list may vary by SDK version and
your feature set):

- **Internet / network state**: for all SDK communications.

- **Microphone**: for voice calls.

- **Notifications** : only if you use push notifications (see
  [Push notifications](https://docs.cloud.google.com/contact-center/ccai-platform/docs/headless-mobile-sdk-android-getting-started#push-notifications) below).

- **Storage / media**: only if your app reads photos, videos, or files from
  shared storage directly. Your app's own files and the system photo picker
  don't need a permission.

- **Camera**: for photo or video capture in smart actions.

- **Screen capture** : for screen share (`MediaProjection`).

Declare and request runtime permissions according to Android OS guidelines.

### Push notifications

The Headless Android SDK uses FCM to deliver:

- Incoming call notifications.

- Certain smart-action and call-related messages.

- Updates to help maintain state when the app is backgrounded.

You will need:

- A Firebase project.

- A valid google-services.json in your app module.

- FCM token handling and registration in your app.

- Custom notification and in-call UI in your app.

## How the headless Android SDK fits into your app

The Headless Mobile SDK for Android can be viewed as three layers:

### CCAI Platform platform and SDK (handled by CCAI Platform)

The SDK securely interacts with the CCAI Platform platform and
provides:

- Authentication using JSON Web Tokens (JWT).

- Queue and channel routing metadata (chat, voice call, email, external
  deflection links).

- Real-time session state management using service objects (`chatService`,
  `queueMenuService`, and more).

- The secure transport pipeline for smart actions, file attachments, and
  screen share.

- Deflection logic and post-session hierarchy evaluation.

### Your Android app (UI and logic - handled by you)

You control the entire visual and navigational experience:

- **Entry points** : for example, a **Help** tab or **Contact us** button.

- **Menus** : how you surface queues (for example, **Billing** , **Tech
  support**).

- **In-session UI**: your custom chat bubbles, call screens, and controls.

- **What your app does**: calls SDK service APIs to start and end sessions,
  observes SDK events using Kotlin Coroutines and Flow, and drives component
  navigation.

### CCAI Platform Admin Portal configuration

Your CCAI Platform admins configure the rules of engagement (operating
hours, available channels, wait time thresholds, and surveys). The SDK reads
this configuration and exposes it to your app as raw data and events. You decide
how to draw that configuration on the screen.

## Retrieve company credentials

Before you integrate the SDK, obtain the credentials from your
CCAI Platform instance:

1. Sign in to the CCAI Platform Admin Portal with an administrator
   account.

2. Navigate to **Settings \> Developer settings**.

3. Under **Company key \& secret code**, copy:

   - **Company key**

   - **Company secret code**

4. Note your **Host URL** --- the hostname for the CCAI platform (for
   example, `your_subdomain.ccaiplatform.com`).

You will use:

- **In your Android app** : **Company key** and **Host URL**.

- **In your backend server** : **Company secret code** to sign JWTs for
  end-user authentication and optional custom data and context used by
  CCAI Platform.

## Add the SDK to your Android app

The Headless SDK uses a modular architecture. You install the core `CCAIKit`
alongside the specific feature modules your app requires (for example,
`CCAIChat` or `CCAIScreenShare`).

### Add the CCAI Maven repository

Add the CCAI Maven repository to your project's `settings.gradle.kts` (or root
`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/") }
        }
    }

### Configure the Gradle version catalog (recommended)

Google Cloud recommends using a Gradle version catalog for managing SDK
dependencies. Add the following to your `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" }

### Add dependencies

In your app-level `build.gradle.kts`, add the core SDK and the specific feature
modules:

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

If you aren't using the version catalog, you can declare dependencies directly:

    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
    }

## Initialization and setup

Initialize the SDK during app launch. Because of the SDK's modular architecture,
initialize the core CCAI Platform system first, then register the
specific channel providers (such as `chat` or `screen share`).

### Implement the `CCAIDelegate` interface

The SDK uses a `CCAIDelegate` interface for authentication callbacks. The key
method is a Kotlin suspend function `ccaiShouldAuthenticate()` that the SDK
calls when it needs a 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
            }
        }
    }

The preceding snippet shows the minimal two-step flow (**sign → authenticate →
return**).

See [Authenticate end users and pass custom
data](https://docs.cloud.google.com/contact-center/ccai-platform/docs/headless-mobile-sdk-android-getting-started#authenticate-end-users-and-pass-custom-data) for the full authentication
contract, including:

- how to sign the JWT on your backend,
- how `authenticate(jwt)` exchanges it for an auth token,
- token caching and invalidation, and
- worked examples with error handling.

### Initialize the SDK in your application class

Initialize the SDK in your custom `Application` class using the `CCAI` singleton
object:

    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` configuration reference

    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
    )

### Update `AndroidManifest.xml`

Ensure your custom application class is registered:

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

### Available SDK services

After initialization, you can access various services through the `CCAI`
singleton object:

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

> [!NOTE]
> **Note:** `CCAI` is an object (singleton) in Kotlin, so you access properties directly using `CCAI.propertyName` --- no need to call `getInstance()` or use a shared accessor.

> [!WARNING]
> **Warning:** `callService` requires its own initialization step. Unlike the other core services, `CCAI.callService` lives in the `CCAICall` module and is registered as an extension property on `CCAI` only after you call `CCAI.initializeCall(context)`. If you skip that step, `CCAI.callService` will be `null` at runtime and the scheduling APIs in Headless Mobile SDK for Android: voice, screen share, scheduled call, and email will be unreachable.

### Fetch company configuration

After initialization, you can fetch company-level configuration using the
`companyService`. This is useful for populating language pickers, displaying the
company name, or reading support contact details before the user enters a queue.

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

> [!NOTE]
> **Note:** The `languages` list returned by `companyService` reflects what your admins have enabled in the CCAI Platform Portal. Use it to build a language picker in your app's settings.

## Authenticate end users and pass custom data

The Headless Mobile SDK for Android uses JSON web tokens (JWT) to authenticate users
and securely pass contextual information to the agent's CRM.

### How it works

The SDK uses a simplified two-step async authentication flow:

1. The SDK determines it needs to authenticate the user.

2. It calls your `CCAIDelegate` method - `ccaiShouldAuthenticate()` - which is
   a suspend function.

3. Your app calls your backend server to get a signed JWT.

4. Your app then passes the signed JWT to
   `CCAI.authService?.authenticate(jwt)` to exchange it for an auth token.

5. The auth token is returned to the SDK to complete the connection.

> [!WARNING]
> **Warning:** JWT signing must always be performed on your backend server. Never embed the `Company Secret Code` inside your compiled Android app - doing so creates a severe security vulnerability.

### Implement the `CCAIDelegate` for authentication

Your app must implement the `CCAIDelegate` interface. The SDK calls the first
suspend method when it needs authentication.

#### `CCAIDelegate` interface

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

#### Implementation example (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
            }
        }
    }

### Pass custom data to the CRM

If you want to pass contextual data to the agent (for example, the user's
current device OS, location, or account tier), your backend must inject a
`custom_data` object into the JWT payload before signing it.

Each piece of custom data must be formatted as a `JSON` object containing a
label (what the agent sees), a value, and a type.

#### Supported data types

- `string`: standard text (for example, "Pixel 8 Pro").

- `number`: integers or floats (for example, 1234 or 99.99).

- `date`: a 13-digit UTC Unix timestamp including milliseconds (for example,
  1537399655992).

- `url`: standard HTTP/HTTPS URL format.

- `boolean`: standard true or false value.

**Agent visibility** : You can optionally pass data to the CCAI Platform
platform that is hidden from the human agent but available for routing or
backend analytics. To do this, include `"invisible_to_agent": true` in the
data object.

### Reserved CRM keys

CCAI Platform supports specific reserved keys that trigger built-in
behaviors in the platform, such as flagging a user as a VIP or warning an agent
about a bad actor. These must be formatted as `boolean` types and will only be
accepted if the payload is signed using the secure `JWT` method.

- `reserved_verified_customer`: indicates whether a customer has been
  successfully authenticated by your internal systems.

- `reserved_bad_actor`: flags the user to the agent as a potential spammer or
  fraudulent account.

- `reserved_repeat_customer`: indicates whether this customer has frequently
  contacted support recently.

#### Example payload with reserved keys

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

### Manage auth tokens

The SDK provides methods to manually update or clear the cached authentication
token:

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

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

> [!WARNING]
> **Warning:** When `cacheAuthToken` is `true` (the default in `InitOptions`), the SDK caches the auth token so it can be reused across app launches without re-signing. The cached token is used until it expires or is explicitly cleared. You must clear the cached token whenever user-related data changes --- most importantly on sign-out events, user switching, or profile updates. Failing to do so can cause the SDK to authenticate the *previous* user's session. Call `updateAuthToken(null)` as part of your logout routine.

### Custom data JWT payload schema

When your backend constructs the final payload to be signed with your `Company
Secret Code`, it must strictly follow this schema. Note the mandatory `iat`
(issued at) and `exp` (expiration) timestamps.

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

## Enable push notifications

The SDK uses push notifications for:

- Incoming calls.

- Certain smart actions and call-related events.

- Maintaining state when the app is in the background.

### Firebase setup

1. Create or use an existing Firebase project.

2. Register your Android app and download the `google-services.json` file.

3. Place `google-services.json` in your app module directory.

4. In your root-level `build.gradle.kts`, add the Google services plugin:

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

5. In your app-level `build.gradle.kts`, apply the plugin and add `Firebase`
   dependencies:

       // 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. Sync the project.

### Register the FCM token with the SDK

Register the FCM push token through `pushNotificationService` and forward
incoming FCM data payloads to the SDK. Your app is responsible for rendering any
customer-facing notification or in-call UI.

#### Implement `onMessageReceived`

If you are using FCM, implement a listener in your `FirebaseMessagingService`
class for push notifications. **If these aren't implemented, the service won't
work properly.**

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

> [!NOTE]
> **Note:** `CCAI.pushNotificationService?.handlePushNotification()` processes the notification at the platform level. Build your own notification renderer for visible notifications, incoming-call screens, and any app-specific notification behavior.

#### Implement `onNewToken`

Also implement the `onNewToken` method to handle token updates. This ensures
that the Headless Mobile SDK for Android receives the latest push notification
token:

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

#### Register the service in `AndroidManifest.xml`

Add the Firebase Messaging Service to your `AndroidManifest.xml` so the system
can deliver push messages to your service:

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

### Initial token registration

At app startup (after SDK initialization), proactively register the current 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)
        }
    }

### Notification permission handling (Android 13+)

On Android 13 (API level 33) and higher, your app needs the `POST_NOTIFICATIONS`
runtime permission to display notifications. The SDK provides a built-in
utility to request it:

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

Call this early in your app lifecycle (for example, during onboarding or first
launch) before registering the FCM token, so push notifications can be
delivered.