このドキュメントでは、Android アプリに SDK を統合してカスタマイズする方法について説明します。
使ってみる
Headless Mobile SDK for Android を使用すると、CCAI Platform のコンタクト センター機能を独自の組み込み Android UI に統合できます。
CCAI プラットフォーム ブランドのウィジェットを表示する代わりに、次の操作を行います。
CCAI Android SDK モジュールを依存関係として追加します。
Kotlin(推奨)または Java で独自の画面、フロー、ビジュアル デザインを構築します。
SDK を使用して、次のことができます。
チャット セッションと音声セッションを開始して管理する。
メール、音声通話、デフレクションのオプションを提供します。
スマート アクション、添付ファイル、セッション後のフロー(CSAT、アンケート、仮想エージェント)をサポートします。
CCAI Platform は、コンタクト センターのロジック(ルーティング、キュー、チャネル、構成、レポート)を処理します。アプリ エクスペリエンス(UI、フロー、ブランディング)全体を所有します。
テーマ設定が可能な事前構築済みの UI を使用する場合は、標準のモバイル SDK を使用します。
要件と対応環境
このセクションでは、Headless Mobile SDK for Android の要件とサポートされている環境について説明します。
Android プラットフォームの要件
Android には、次のプラットフォーム要件が適用されます。
Android の最小バージョン: Android 6.0(API レベル 23)以降
コンパイル SDK: 36(推奨)
サポートされている言語: Kotlin(推奨)または Java
Java 互換性: Java 17 以降
Gradle / Android Studio: アプリおよび使用している SDK リリースと互換性のある、最新の Android Gradle プラグインと Android Studio バージョン
Kotlin バージョン: 2.0 以降
CCAI プラットフォーム インスタンスの要件
以下を取得するには、CCAI プラットフォーム インスタンスのデベロッパー設定にアクセスする必要があります。
会社キー
会社のシークレット コード
ホスト URL - CCAI プラットフォームのホスト名(例: your_subdomain.ccaiplatform.com)
これらの値は次の目的で使用されます。
会社キーとホスト URL - Android アプリで SDK を初期化します。
会社のシークレット コード - バックエンドで、ユーザーの認証に使用される JSON Web Token(JWT)に署名します。
ネットワーキングと権限
アプリは、CCAI Platform エンドポイントと、構成した音声プロバイダ エンドポイントへのアウトバウンド トラフィックを許可する必要があります。
一般的な Android の権限は次のとおりです(実際のリストは、SDK のバージョンと機能セットによって異なる場合があります)。
インターネット / ネットワークの状態: すべての SDK 通信。
マイク: 音声通話に使用します。
通知: プッシュ通知を使用する場合のみ(下記のプッシュ通知を参照)。
ストレージ / メディア: アプリが共有ストレージから写真、動画、ファイルを直接読み取る場合にのみ必要です。アプリ独自のファイルとシステムの写真選択ツールには権限は必要ありません。
カメラ: スマート アクションで写真や動画を撮影するために使用します。
画面キャプチャ: 画面共有(
MediaProjection)用。
Android OS のガイドラインに沿って、実行時の権限を宣言してリクエストします。
プッシュ通知
ヘッドレス Android SDK は、FCM を使用して以下を配信します。
着信通知。
特定のスマート アクションと通話関連のメッセージ。
アプリがバックグラウンドに移行したときに状態を維持するための更新。
以下のものが必要になります。
Firebase プロジェクト
アプリ モジュール内の有効な google-services.json。
アプリでの FCM トークンの処理と登録。
アプリ内のカスタム通知と通話中 UI。
ヘッドレス Android SDK をアプリに組み込む方法
Headless Mobile SDK for Android は、次の 3 つのレイヤで構成されています。
CCAI プラットフォームと SDK(CCAI プラットフォームで処理)
SDK は CCAI Platform プラットフォームと安全にやり取りし、次の機能を提供します。
JSON Web Token(JWT)を使用した認証。
キューとチャネルのルーティング メタデータ(チャット、音声通話、メール、外部のデフレクション リンク)。
サービス オブジェクト(
chatService、queueMenuServiceなど)を使用したリアルタイムのセッション状態管理。スマート アクション、ファイル添付、画面共有用の安全な転送パイプライン。
デフレクション ロジックとセッション後の階層評価。
Android アプリ(UI とロジック - デベロッパーが処理)
ビジュアルとナビゲーションのエクスペリエンス全体を制御できます。
エントリ ポイント: [ヘルプ] タブや [お問い合わせ] ボタンなど。
メニュー: キューを表示する方法(例: 請求、テクニカル サポート)。
セッション中の UI: カスタムのチャットのふきだし、通話画面、コントロール。
アプリの動作: SDK サービス API を呼び出してセッションを開始、終了し、Kotlin のコルーチンと Flow を使用して SDK イベントを監視し、コンポーネントのナビゲーションを推進します。
CCAI Platform 管理ポータルの構成
CCAI プラットフォーム管理者は、エンゲージメントのルール(営業時間、利用可能なチャネル、待機時間のしきい値、アンケート)を構成します。SDK はこの構成を読み取り、元データとイベントとしてアプリに公開します。その構成を画面に描画する方法を決定します。
会社の認証情報を取得する
SDK を統合する前に、CCAI Platform インスタンスから認証情報を取得します。
管理者アカウントで CCAI Platform 管理ポータルにログインします。
[設定] > [デベロッパー向けの設定] に移動します。
[Company key & secret code] で、以下をコピーします。
会社キー
会社のシークレット コード
ホスト URL(CCAI プラットフォームのホスト名、例:
your_subdomain.ccaiplatform.com)をメモします。
使用するサービス:
Android アプリの場合: 会社キーとホスト URL。
バックエンド サーバー: エンドユーザー認証用の JWT に署名するための会社の秘密コード。CCAI Platform で使用されるカスタムデータとコンテキスト(省略可)。
Android アプリに SDK を追加する
Headless SDK はモジュラー アーキテクチャを使用しています。コア CCAIKit は、アプリに必要な特定の機能モジュール(CCAIChat や CCAIScreenShare など)とともにインストールします。
CCAI Maven リポジトリを追加する
CCAI Maven リポジトリをプロジェクトの 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 では、SDK の依存関係の管理に Gradle バージョン カタログを使用することをおすすめしています。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 Platform システムを初期化してから、特定のチャネル プロバイダ(chat や screen share など)を登録します。
CCAIDelegate インターフェースを実装する
SDK は、認証コールバックに CCAIDelegate インターフェースを使用します。重要なメソッドは、SDK が JWT を必要とするときに呼び出す Kotlin の suspend 関数 ccaiShouldAuthenticate() です。
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
}
}
}
上記のスニペットは、最小限の 2 ステップのフロー(署名 → 認証 → 戻る)を示しています。
エンドユーザーを認証してカスタムデータを渡すで、以下を含む完全な認証契約を確認してください。
- バックエンドで JWT に署名する方法、
authenticate(jwt)がそれを認証トークンと交換する方法- トークンのキャッシュ保存と無効化
- エラー処理の例を紹介します。
アプリケーション クラスで SDK を初期化する
CCAI シングルトン オブジェクトを使用して、カスタム Application クラスで SDK を初期化します。
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 サービス
初期化後は、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 for Android は、JSON Web Token(JWT)を使用してユーザーを認証し、コンテキスト情報をエージェントの CRM に安全に渡します。
仕組み
SDK は、簡素化された 2 段階の非同期認証フローを使用します。
SDK は、ユーザーを認証する必要があると判断します。
CCAIDelegateメソッド(ccaiShouldAuthenticate())を呼び出します。これは suspend 関数です。アプリがバックエンド サーバーを呼び出して、署名付き JWT を取得します。
アプリは、署名付き JWT を
CCAI.authService?.authenticate(jwt)に渡して、認証トークンと交換します。認証トークンが SDK に返され、接続が完了します。
認証用の CCAIDelegate を実装する
アプリは CCAIDelegate インターフェースを実装する必要があります。SDK は、認証が必要なときに最初の suspend メソッドを呼び出します。
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 に渡す
コンテキスト データ(ユーザーの現在のデバイス OS、場所、アカウント階層など)をエージェントに渡す場合は、バックエンドで custom_data オブジェクトを JWT ペイロードに挿入してから署名する必要があります。
カスタムデータの各要素は、ラベル(エージェントに表示されるもの)、値、タイプを含む JSON オブジェクトとしてフォーマットする必要があります。
サポートされるデータタイプ
string: 標準テキスト(例: 「Google Pixel 8 Pro」)。number: 整数または浮動小数点数(例: 1234、99.99)。date: ミリ秒を含む 13 桁の UTC Unix タイムスタンプ(例: 1537399655992)。urlThe following is a list of questions about the Google Cloud Platform (GCP). Your task is to answer the questions.Question:What is the primary purpose of the Google Cloud Platform (GCP) Resource Hierarchy?Options:(A) To organize resources geographically(B) To manage billing and access control(C) To optimize network performance(D) To store data in multiple formatsPlease select the correct option (A, B, C, or D).boolean: 標準の true または false 値。
エージェントの可視性: 必要に応じて、人間のエージェントには表示されないが、ルーティングやバックエンド分析に使用できるデータを CCAI Platform プラットフォームに渡すことができます。これを行うには、データ オブジェクトに "invisible_to_agent": true を含めます。
予約済みの CRM キー
CCAI Platform は、プラットフォームに組み込まれた動作をトリガーする特定の予約済みキーをサポートしています。たとえば、ユーザーを VIP としてフラグ付けしたり、悪意のあるユーザーについてエージェントに警告したりできます。これらは boolean 型としてフォーマットする必要があり、ペイロードが安全な 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)
カスタムデータ JWT ペイロード スキーマ
バックエンドが 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 プロジェクトを作成するか、既存の 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 に登録する
pushNotificationService を介して FCM プッシュ トークンを登録し、受信した FCM データ ペイロードを SDK に転送します。アプリは、顧客向けの通知や通話中の UI をレンダリングする必要があります。
onMessageReceived を実装する
FCM を使用している場合は、プッシュ通知用のリスナーを 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 for 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 Messaging Service を 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 トークンを登録する前に、アプリのライフサイクルの早い段階(オンボーディング中や初回起動時など)でこのメソッドを呼び出します。