iOS 向け Headless Mobile SDK: 音声、画面共有、スケジュール設定された通話、メール

このドキュメントでは、Android アプリケーションで Headless Mobile SDK を統合してカスタマイズする方法について説明します。CCAICall を介した音声通話について説明します

音声通話

iOS 向け Headless Mobile SDK は、CCAICall モジュールを通じて音声通話のサポートを提供します。アプリがカスタム通話 UI を所有し、SDK が通話接続、CallKit 統合、VoIP プッシュ処理、通話ライフサイクル イベントを処理します。

SDK が提供するもの: インスタント通話の開始、ボイスメールの開始、着信通話の処理、通話状態のモニタリングを行うための通話サービス API。

構築するもの: 通話前のエントリ ポイント、録音の同意を求めるプロンプト、呼び出し中または待機中の状態、通話中のコントロール、通話後のナビゲーションなど、通話の視覚的なエクスペリエンス。

通話モジュールを初期化する

コア SDK を初期化した後に、通話モジュールを初期化します。

import CCAIKit
import CCAICall

try CCAI.shared.initialize(options: options)
CCAI.shared.initializeCall(CallOptions())

VoiceCallChannel 機能の検査

インスタント通話を提供する前に、キューの VoiceCallChannel 構造体を調べて、公開するエントリ ポイント(インスタント通話、ボイスメール フォールバック、チャネルレベルの転送)と、録音の同意が必要かどうかを判断します。

主な VoiceCallChannel フィールド

  • instantEnabled: Bool? - このキューでライブ(インスタント)音声通話が許可されているかどうか。nil または false を "don't offer an instant call button" 状態として扱います。キューに音声チャンネルがあるかどうかのみを示す voiceCall != nil とは異なります。

  • preSessionSmartAction: Bool? - 通話を開始する前に、この特定のチャネルでセッション前のスマート アクションが必要かどうか。補完的なキューレベルのパスについては、iOS 向けヘッドレス モバイル SDK: スマート アクション、添付ファイル、回避をご覧ください。

  • scheduleEnabled: Bool? - 予定されたコールがサポートされているかどうか。補完的なキューレベルのパスについては、スケジュールされた通話をご覧ください。

  • recordingOption: RecordingOption? - 通話の録音に対する同意モデル(録音に対する同意を参照)。スケジューリング固有の RecordingPermission.notAsked とは異なります。

  • voicemailReason: String? - チャネルがボイスメールに転送するように構成されている場合に設定されます。

  • phoneNumber: String? - 転送またはボイスメール用に構成された PSTN フォールバック番号。

  • scheduleDeflectionType: String? / deflected: Bool? / deflectedReason: String? - チャネルレベルの回避メタデータ。deflected == true の場合、管理者が構成した deflectedReason メッセージを表示し、インスタント通話を試みる代わりに、構成されたフォールバック(電話番号をダイヤルする、通話のスケジュールを設定するエントリ ポイントなど)を提供します。キューレベルの転送処理については、転送(営業時間外と容量超過)を参照してください。

func voiceEntryPoints(for menu: QueueMenu) {
    guard let voice = menu.channels?.voiceCall else {
        hideCallNowButton()
        hideVoicemailButton()
        return
    }

    // Instant call - only when explicitly enabled and not deflected
    callNowButton.isHidden = (voice.instantEnabled != true) || (voice.deflected == true)

    // Voicemail fallback
    if let number = voice.phoneNumber, voice.voicemailReason != nil {
        showVoicemailButton(number: number, reason: voice.voicemailReason)
    }

    // Channel-level deflection
    if voice.deflected == true {
        showChannelDeflection(reason: voice.deflectedReason)
    }
}

SDK が提供するもの: ポータルで管理者が構成した通話の録音の同意モデルを記述する VoiceCallChannel の recordingOption: RecordingOption? フィールド。

作成するもの: 同意モードのプロンプト(.askUser の場合)と、管理者の選択を尊重する分岐ロジック。

public enum RecordingOption: String, Decodable {
    case always   // Calls are always recorded - surface a disclosure before connecting
    case never    // Calls are never recorded - no disclosure needed
    case askUser  // Prompt the user for consent before the call connects
}

func handleRecordingConsent(
    for voice: VoiceCallChannel,
    completion: @escaping (Bool) -> Void
) {
    switch voice.recordingOption {
    case .always:
        showRecordingDisclosure(message: "This call will be recorded.")
        completion(true)
    case .never, .none:
        completion(true)
    case .askUser:
        presentConsentPrompt { granted in
            completion(granted)
        }
    }
}

インスタント通話を開始する

即席通話を開始する前に:

  1. 選択したキューの VoiceCallChannel を検査します。

  2. インスタント コールが有効になっていて、転送されていないことを確認します。

  3. キューの recordingOption に従って録音の同意を処理します。

  4. マイクの権限をリクエストします。

  5. startInstantCall を呼び出します。

func initiateInstantCall(for menu: QueueMenu) async {
    guard let voice = menu.channels?.voiceCall,
          voice.instantEnabled == true,
          voice.deflected != true else {
        return
    }

    let recordingPermission = await resolveRecordingPermission(for: voice)
    guard await requestMicrophonePermission() else { return }

    do {
        try await CCAI.shared.callService?.startInstantCall(
            InstantCallRequest(
                menuId: menu.id,
                recordingPermission: recordingPermission
            )
        )
    } catch {
        showCallStartError(error)
    }
}

通話の状態を監視する

通話を開始または応答する前に、call-service イベントをサブスクライブします。

CCAI.shared.callService?.stateChanged
    .receive(on: DispatchQueue.main)
    .sink { state in
        updateCallConnectionState(state)
    }
    .store(in: &cancellables)

CCAI.shared.callService?.callReceived
    .receive(on: DispatchQueue.main)
    .sink { call in
        updateCallDetails(call)
    }
    .store(in: &cancellables)

CCAI.shared.callService?.incomingCallEvent
    .receive(on: DispatchQueue.main)
    .sink { event in
        handleIncomingCallEvent(event)
    }
    .store(in: &cancellables)

CCAI.shared.callService?.waitTimeUpdated
    .receive(on: DispatchQueue.main)
    .sink { waitTime in
        // The platform pushed a new estimated wait time for the active call.
        updateEstimatedWaitTime(waitTime)
    }
    .store(in: &cancellables)

CCAI.shared.callService?.participantUpdated
    .receive(on: DispatchQueue.main)
    .sink { participant in
        // Agent assignment, transfer, or participant metadata changed.
        updateParticipantInfo(participant)
    }
    .store(in: &cancellables)

CCAI.shared.callService?.interruptionDetected
    .receive(on: DispatchQueue.main)
    .sink { interruption in
        // A PSTN interruption (for example, an incoming cellular call)
        // has paused the active CCAI call. Surface a "call interrupted"
        // banner and offer a Resume action after the interruption ends.
        showInterruptionBanner(reason: interruption)
    }
    .store(in: &cancellables)

CCAI.shared.callService?.deflectionOffered
    .receive(on: DispatchQueue.main)
    .sink { deflection in
        // The platform offered a wait-time deflection (for example, a
        // scheduled callback or PSTN fallback). Render the prompt and
        // honor the user's choice.
        presentWaitTimeDeflection(deflection)
    }
    .store(in: &cancellables)

プロバイダの状態とサーバーのステータス

stateChanged と callReceived.status は独立したシグナルです。行ではなく列として読み取ります。プロバイダの stateChanged はローカル VoIP ハンドシェイクをレポートし、サーバーサイドの callReceived.status はプラットフォーム上の通話のライフサイクルをレポートします。stateChanged が .connected に達したときではなく、callReceived.status から Connected フリップと通話タイマーの開始を駆動します。

シグナル レポートの内容 そこから導き出すもの
stateChanged(プロバイダ) ローカル VoIP ハンドシェイク - .connecting、.connected(ローカル)、.disconnected、.error(...)。 サーバーのステータスが届く前、エラーが表示される前、通話終了後のクリーンアップの前に表示されるオプションのステータス スピナー。
callReceived.status(サーバー) サーバーサイドのライフサイクル - .waiting、.connecting、.connected、.onHold、.interrupted、.ended。 接続フリップ、通話タイマーの開始、エージェント割り当て UI、転送またはエスカレーションのオーバーレイ、通話終了フロー。

通話ステータスとサーバーサイドの状態

SDK が提供するもの: 各 Call ペイロードのサーバー駆動型 CallStatus 列挙型。呼び出しがライフサイクルのどの段階にあるか(connecting、waiting、connected、onHold、interrupted、ended など)を記述します。

構築するもの: CallStatus から通話画面のユーザー向けの状態(着信中、キューで待機中、接続済み、保留中、中断、終了)へのマッピング。

実装例

各 callReceived エミッションから call.status をオンにし、一致する UI 状態をレンダリングします。

func updateCallDetails(_ call: Call) {
    switch call.status {
    case .connecting:
        renderConnectingState()
    case .waiting:
        renderWaitingInQueueState(estimatedWait: call.estimatedWait)
    case .connected:
        renderConnectedState(agent: call.agent)
    case .onHold:
        renderOnHoldState()
    case .interrupted:
        renderInterruptedState()
    case .ended, .failed:
        renderEndedState(reason: call.endReason)
    @unknown default:
        break
    }
}

通話中のコントロール(ミュート、スピーカー、保留)

SDK が提供するもの: callService の読み取り専用プロパティ(isMuted、isSpeakerEnabled、isOnHold)と、各状態を切り替えるアクション(setMuted、setSpeakerEnabled、setOnHold)。

作成するもの: SDK のアクションに接続され、現在の状態を反映する、通話 UI のミュート、スピーカー、保留ボタン。

実装例

callService から現在の状態を読み取ってボタンを初期化し、タップで切り替えて更新します。

// Read current state
muteButton.isSelected = CCAI.shared.callService?.isMuted ?? false
speakerButton.isSelected = CCAI.shared.callService?.isSpeakerEnabled ?? false
holdButton.isSelected = CCAI.shared.callService?.isOnHold ?? false

// Toggle from your UI handlers
func onMuteTapped() {
    let next = !(CCAI.shared.callService?.isMuted ?? false)
    CCAI.shared.callService?.setMuted(next)
    muteButton.isSelected = next
}

func onSpeakerTapped() {
    let next = !(CCAI.shared.callService?.isSpeakerEnabled ?? false)
    CCAI.shared.callService?.setSpeakerEnabled(next)
    speakerButton.isSelected = next
}

func onHoldTapped() {
    let next = !(CCAI.shared.callService?.isOnHold ?? false)
    CCAI.shared.callService?.setOnHold(next)
    holdButton.isSelected = next
}

中断された通話を再開する

PSTN の中断(携帯電話への着信など)によってアクティブな CCAI 通話が一時停止すると、SDK はセッションを維持し、interruptionDetected を出力します。割り込みが終了すると、アプリは通話を再開できます。

SDK が提供するもの: 進行中の通話を検索する getLastCallInProgress()(アプリの再起動後も含む)、通話をフォアグラウンドに戻す resumeCall(_:)。

構築するもの: UI の再開アフォーダンス(通常はバナー、または割り込み終了後の自動再開)と、通話画面に戻るナビゲーション。

実装例

getLastCallInProgress で進行中の通話を検索し、再開して、通話画面に戻ります。

func resumeIfInterrupted() async {
    guard let call = try? await CCAI.shared.callService?.getLastCallInProgress() else {
        return
    }
    do {
        try await CCAI.shared.callService?.resumeCall(call)
        navigateToCallScreen(call)
    } catch {
        showCallResumeError(error)
    }
}

仮想エージェントからのエスカレーション

SDK が提供するもの: canEscalate(allowSkipVirtualAgent:) は callService 自体ではなく、CallResponse(callService.callReceived によって出力されるモデル)のメソッドです。現在の通話が、通話の現在の仮想エージェントのステータスに基づいて、人間のエージェントへのエスカレーションの対象となるかどうかを報告します。

構築するもの: 最新の callReceived 排出量を "current call" 状態として保持し、[Talk to a person] ボタンの可視性を currentCall?.canEscalate(...) にバインドします。allowSkipVirtualAgent 引数は、呼び出しレスポンス自体から個別に取得するメニュー構成値です。本番環境で true をハードコードしないでください。

実装例

最新の Call を保存されたプロパティに保持し、それに対して canEscalate を呼び出します。メニュー構成から allowSkipVirtualAgent を解決します。

// Held from the most recent `callReceived` emission
private var currentCall: Call?

// `allowSkipVirtualAgent` is fetched separately from menu configuration
// it is not derived from the CallResponse.
let allowSkip = menuConfiguration.allowSkipVirtualAgent
let allowed = currentCall?.canEscalate(allowSkipVirtualAgent: allowSkip) ?? false
talkToAgentButton.isHidden = !allowed

ボイスメール

SDK が提供するもの: callService の startVoicemail(_ request: VoicemailRequest) と、プラットフォームが最初にボイスメールを提供した理由(営業時間外のフォールバック、容量超過のフォールバック、一時的なリダイレクトなど)を説明する VoicemailReason 列挙型。

構築するもの: UI のボイスメール エントリ ポイント(通常は VoiceCallChannel.voicemailReason が入力されたとき、または通話ライフサイクルがボイスメールの結果に解決されたときに表示されます)と、録音 UI 自体。

実装例

voicemailReason が設定されている場合は、ボイスメール ボタンを表示し、VoicemailRequest を使用して startVoicemail を呼び出します。

public enum VoicemailReason: String, Decodable {
    case afterHourDeflection
    case overCapacityDeflection
    case temporaryRedirection
}

func offerVoicemail(for menu: QueueMenu) async {
    guard let voice = menu.channels?.voiceCall,
          voice.voicemailReason != nil else {
        return
    }
    do {
        try await CCAI.shared.callService?.startVoicemail(
            VoicemailRequest(menuId: menu.id)
        )
    } catch {
        showVoicemailError(error)
    }
}

待ち時間の削減

キューが開いているにもかかわらず、待ち時間が管理者が設定したしきい値を超えている場合、プラットフォームは代替パス(通常はコールバックのスケジュール設定または PSTN の転送)を提案できます。

SDK が提供するもの: 提案された代替案を説明する CallDeflection ペイロード。アクティブな通話の callService で getCallDeflection(callId:) を使用して取得できます。また、プラットフォームは、待機中に転送が可能になった場合、deflectionOffered パブリッシャーを介して同じペイロードを送信します。別の CompanyResponse.preventDirectPstnCall フラグは、フォールバック UI で PSTN の直接ダイヤルを非表示にするかどうかを示します。

構築するもの: ユーザーの選択を尊重する転換プロンプト(「予想待ち時間は 12 分です。代わりにコールバックをスケジュールしますか?」など)と分岐ロジック。

実装例

getLastCallInProgress でアクティブな通話を検索し、getCallDeflection(callId:) で提案された転送を取得して、CompanyResponse.preventDirectPstnCall と組み合わせてプロンプトを表示します。

func evaluateWaitTimeDeflection() async {
    guard let currentCall = try? await CCAI.shared.callService?.getLastCallInProgress() else {
        return
    }
    let deflection = try? await CCAI.shared.callService?.getCallDeflection(
        callId: currentCall.id
    )
    guard let offer = deflection else { return }
    let company = try? await CCAI.shared.companyService?.get()
    let allowDirectPstn = company?.preventDirectPstnCall != true
    presentWaitTimeDeflection(offer, allowDirectPstn: allowDirectPstn)
}

音声メッセージ(システム アナウンス)

SDK が提供するもの: キュー用に管理者が構成した音声メッセージ(「すべてのエージェントが対応中です」など)を解決する audibleMessageService。デフォルトでは、通話が対応する状態になると、SDK はこれらのメッセージを自動的に再生します。

構築内容: デフォルト モードでは何も構築しません。アナウンスを自分でレンダリングする場合は(字幕テキストと独自のオーディオ プレーヤーなど)、playAudibleMessages = false で通話モジュールを初期化し、resolveMessages(menuId:) を直接呼び出します。

実装例

SDK で再生されるパスのデフォルトのイニシャライザを使用するか、playAudibleMessages = false を設定してメッセージを自分で解決し、独自の UI で字幕をレンダリングして音声を再生します。

// Option A default: SDK plays audible messages automatically.
CCAI.shared.initializeCall(CallOptions())

// Option B your app renders the announcements manually.
CCAI.shared.initializeCall(CallOptions(playAudibleMessages: false))
let messages = try await CCAI.shared.audibleMessageService?.resolveMessages(
    menuId: menu.id
)
for message in messages ?? [] {
    renderCaption(message.text)
    playAudio(message.audioURL)
}

詳細CallOptions

CallOptions は、デフォルトの通話エクスペリエンスをオプトアウトする必要があるアプリ向けに、少数の切り替えを公開します。

  • playAudibleMessages: Bool - false の場合、SDK はシステム アナウンスを再生しません。audibleMessageService を使用して自分でレンダリングします。

  • callKitEnabled: Bool - false の場合、SDK は着信または発信の組み込み CallKit 画面を表示しません。iOS システム UI に依存するのではなく、アプリ独自のアプリ内着信通話 UI をレンダリングする必要がある場合に、これを使用します。

実装例

通話モジュールを初期化するときに、切り替えを CallOptions に渡します。

// Fully custom in-app call experience
CCAI.shared.initializeCall(
    CallOptions(
        playAudibleMessages: false,
        callKitEnabled: false
    )
)

画面共有

画面共有を使用すると、サポート エージェントがお客様の画面を表示して、問題のトラブルシューティングを行うことができます。 Google Cloud プロジェクトでは、次の 2 つの画面共有モードがサポートされています。

  • アプリ内共有: エージェントは、特定のアプリ内で発生していることのみを確認できます。

  • デバイス全体の共有(オプション): エージェントは、iOS のホーム画面や他のアプリなど、ユーザーのデバイス全体を確認できます。これには、Apple の ReplayKit を使用した高度な iOS 構成が必要です。

SDK が提供するもの: セッションの作成と管理、状態の変化の処理、同意リクエストの処理を行う画面共有サービス。

構築するもの: 初期化構成、ユーザーの同意を求める UI プロンプト、(デバイス全体をサポートする場合)組み込みの iOS ブロードキャスト拡張機能。

画面共有サービスは、セッションのライフサイクル全体(create、activate、end、clear(iOS のみ))のメソッドと、構成メソッド(updateOptions、enableRemoteControl、enableFullDeviceSharing)を提供します。次のサブセクションでは、コア統合フローについて説明します。

すべての画面共有メソッドの完全なメソッド シグネチャとパラメータの詳細については、Headless Mobile SDK - iOS API リファレンスをご覧ください。

画面共有を初期化して構成する

エージェントが画面共有をリクエストする前に、特定の画面共有ライセンスキーを使用してサービスを初期化し、構成する必要があります。

import com.ccaiplatform.ccaikit.CCAI
import com.ccaiplatform.ccaikit.initializeScreenShare
import com.ccaiplatform.ccaikit.models.screenShare.ScreenShareOptions

// Minimal domain defaults to your instance's configured provider
CCAI.initializeScreenShare(
    context = this,
    options = ScreenShareOptions(
        key = "YOUR_COMPANY_KEY"
    )
)

// If your instance or provider requires an explicit domain:
// CCAI.initializeScreenShare(
//     context = this,
//     options = ScreenShareOptions(
//         key = "YOUR_COMPANY_KEY",
//         domain = "your_subdomain.ccaiplatform.com"
//     )
// )

画面共有の利用資格を確認する

画面共有機能を有効にする前に、現在のチャットで利用可能かどうかを確認します。

let isChatSupportingScreenShare = CCAI.shared.screenShareService != nil
    && chat?.isSupportingScreenShare == true

画面共有リクエストを処理する

screenShareService を使用して画面共有リクエスト処理を実装します。ScreenShareRequest を作成し、非同期レスポンスを処理します。

func requestScreenShare(isFromRemote: Bool) async {
    guard let chatId = currentChatId else { return }
    guard let screenShareService = CCAI.shared.screenShareService else {
        handleError(ScreenShareError.serviceNotAvailable, message: "Request Screen Share")
        return
    }

    // Track whether this session is agent-initiated
    screenShareInitiatedFrom = isFromRemote ? .agent : .endUser

    if !isFromRemote {
        await sendScreenShareMessage(event: .screenShareRequestedFromEndUser)
    }

    do {
        let response = try await screenShareService.create(
            request: ScreenShareRequest(
                communicationId: chatId,
                communicationType: .chat,
                initiatedFrom: isFromRemote ? .agent : .endUser
            )
        )
        await sendScreenShareMessage(event: .screenShareCodeGenerated, response: response)
    } catch {
        await sendScreenShareMessage(event: .screenShareFailed)
        handleError(error, message: "Request screen share error")
    }
}

画面共有の状態変更を処理する

サービス パブリッシャーを介して画面共有の状態とリクエストを監視します。セッションを作成またはアクティブ化する前にサブスクライブして、UI がすべてのトランジションに応答できるようにします。

CCAI.shared.screenShareService?.statePublisher
    .receive(on: DispatchQueue.main)
    .sink { state in
        currentScreenShareSessionState = state
        if state == .authorizing, screenShareInitiatedFrom == .agent {
            Task {
                do {
                    try await handleStartSession(isAccepted: true)
                } catch {
                    handleError(error, message: "Failed to start screen share")
                }
            }
        }
    }
    .store(in: &cancellables)

CCAI.shared.screenShareService?.requestPublisher
    .receive(on: DispatchQueue.main)
    .sink { request in
        switch request {
        case .session:
            if screenShareInitiatedFrom == .endUser {
                showScreenSharePrompt(.startSession)
            }
        case .remoteControl:
            showScreenSharePrompt(.remoteControl)
        @unknown default:
            break
        }
    }
    .store(in: &cancellables)

ScreenShareServiceState 列挙型は、.none、.pending、.authorizing、.active、.ended を通じてセッションの進行状況を追跡します。リクエスト パブリッシャーは、セッション リクエストとリモコン リクエストを発行します。アプリは、これらのリクエストをユーザー向けの同意プロンプトに変換する必要があります。

デバイス全体の画面共有(高度な設定)

エージェントが自社以外のアプリケーションの画面を表示できるようにするには、Apple ブロードキャスト アップロード拡張機能を実装する必要があります。これにより、iOS は画面をシステム全体でキャプチャし、動画フレームをGoogle Cloud プロジェクト SDK に安全に渡すことができます。

ブロードキャスト拡張機能のターゲットを追加する

  • Xcode プロジェクトを開きます。

  • [ファイル] > [新規] > [ターゲット]… に移動します。

  • [Broadcast Upload Extension] を選択します。

  • ターゲットの名前を入力します。

  • [UI 拡張機能を含める] をオフにします。

  • ターゲットを作成し、バンドル ID をメモします。

  • ブロードキャスト拡張機能のターゲット SDK を iOS 12.0 以降に変更します。

キーチェーン共有を設定する

アプリとアプリ拡張機能は、独自のキーチェーン グループを使用して iOS キーチェーンでシークレットを共有する必要があります。

  • Xcode で、両方のターゲットの [Signing & Capabilities] タブに移動します。

  • キーチェーン共有機能を追加します。

  • 両方のターゲットのキーチェーン グループに io.cobrowse を追加します。

メインアプリの Info.plist を更新する

拡張機能のバンドル ID をアプリの Info.plist に追加します(拡張機能の Info.plist ではありません)。

<key>CBIOBroadcastExtension</key>
<string>your.app.extension.bundle.ID.here</string>

CobrowseSDK をブロードキャスト拡張機能のターゲットに追加する

Xcode で、ブロードキャスト拡張機能のターゲットを選択した状態で、[Frameworks and Libraries] の下にある [+] ボタンを選択し、拡張機能のターゲットに CobrowseSDK を追加します。

拡張機能ハンドラを実装する

Xcode は、先ほど作成したターゲットに SampleHandler.swift ファイルを追加します。ファイルの内容を次のように置き換えて、SDK の ReplayKit 拡張機能クラスから継承するようにします。

import CobrowseSDK

class SampleHandler: CobrowseIOReplayKitExtension {
    // The Google Cloud project module automatically handles ReplayKit lifecycle methods
}

構築と実行

これで、アプリをビルドして実行する準備が整いました。フルデバイス機能は実機でのみ利用可能で、iOS シミュレータでは動作しません。

すべてが正しく設定されていれば、青い丸いアイコンを選択すると、ブロードキャスト拡張機能を選択する画面が表示されます。

iOS SwiftUI の画面共有に関する制限

  • 主要なインタラクティブ要素を UIKit でラップする - リモートでクリックする必要がある領域については、UIViewRepresentable または UIViewControllerRepresentable を使用して、UIKit コントロール(UIButton など)としてラップします。これにより、Cobrowse の UIKit パスを使用してリモートクリックが確実に機能します。

  • カスタム タッチ処理でリモート タッチを転送する - UIKit で置き換えられない SwiftUI 領域では、Cobrowse のカスタム タッチ コールバックを使用して、リモート タッチイベントを SwiftUI ロジックに転送します。実装では、カスタム UIView またはジェスチャー認識ツールを使用してコールバックを処理し、イベントを SwiftUI にブリッジします(UIViewRepresentable と Coordinator、通知、クロージャを使用)。

  • 商品レベルのガイダンスまたは代替を提供する - SwiftUI 画面に、エージェントは閲覧のみ可能、ユーザーはローカルでタップする必要があることを明確に表示するか、閲覧権限を維持しながら、これらのページでのリモート制御権限を自動的に制限します。

UIKit ラッパーの実装例

struct RemoteControlButton: UIViewRepresentable {
    let title: String
    let action: () -> Void

    func makeUIView(context: Context) -> UIButton {
        let button = UIButton(type: .system)
        button.setTitle(title, for: .normal)
        button.addTarget(
            context.coordinator,
            action: #selector(Coordinator.buttonTapped),
            for: .touchUpInside
        )
        return button
    }

    func updateUIView(_ uiView: UIButton, context: Context) {
        uiView.setTitle(title, for: .normal)
    }

    func makeCoordinator() -> Coordinator {
        Coordinator(action: action)
    }

    class Coordinator: NSObject {
        let action: () -> Void

        init(action: @escaping () -> Void) {
            self.action = action
        }

        @objc func buttonTapped() {
            action()
        }
    }
}

// Usage in SwiftUI
struct ContentView: View {
    var body: some View {
        VStack {
            Text("This screen supports remote control")
            RemoteControlButton(title: "Clickable Button") {
                print("Button tapped remotely or locally")
            }
        }
    }
}

スケジュール設定された通話

スケジュールされた通話を使用すると、エンドユーザーはインスタント通話のキューで待つのではなく、将来の音声通話を予約できます。iOS ヘッドレス SDK では、キューとチャンネルのメタデータを使用して、アプリにスケジュール設定のエントリ ポイントを表示するかどうかを決定します。

機能の検出

SDK が提供するもの: 選択したキューが将来の通話の予約をサポートしているかどうかを示す VoiceCallChannel の scheduleEnabled フラグ。インスタント(ライブ)音声通話が利用可能かどうかには依存しません。

作成するもの: スケジューリング エントリ ポイントを表示する前にこのフラグを確認するロジック。

実装例

キューの音声通話チャネルで scheduleEnabled を確認します。voiceCall != nil をプロキシとして使用しないでください。キューは、スケジュールされた通話に対応していなくても、インスタント音声通話に対応できます。逆も同様です。

func setupScheduledCallEntryPoint(for menu: QueueMenu) {
    guard let voiceChannel = menu.channels?.voiceCall else {
        // No voice channel at all hide both instant and scheduled call buttons
        hideCallNowButton()
        hideScheduleCallButton()
        return
    }

    // Instant voice call always show if voiceCall channel exists
    showCallNowButton()

    // Scheduled call check scheduleEnabled explicitly
    if voiceChannel.scheduleEnabled == true {
        showScheduleCallButton()
    } else {
        hideScheduleCallButton()
    }
}

データモデルのリファレンス

// VoiceCallChannel.swift
public struct VoiceCallChannel: Decodable {
    // ...
    public let scheduleEnabled: Bool?  // true if scheduled calls are supported
    // ...
}

// ChannelType.swift
public enum ChannelType {
    case scheduleCall(deflectionType: DeflectionType?)
    // ...
}

QueueMenu.getEnabledChannels() から返された有効なチャンネルのリストで .scheduleCall を確認することもできます。

利用可能な時間枠を取得する

ヘッドレス通話サービスは、選択したキューで利用可能な予約時間を取得できます。アプリがカレンダーまたは時間選択ツールの UI を所有している。

SDK が提供するもの: 選択したキューで利用可能なスロットのタイムスタンプ。既存のスケジュールされた呼び出しの再スケジュールをサポートするオプション。

構築するもの: カレンダー、時間選択ツール、タイムゾーンの表示、空の状態の処理、再試行の動作。

実装例

キュー メニュー ID を指定して getScheduledTimeSlots を呼び出します。再スケジュールするときは、既存のスケジュール設定されたコール ID を渡して、サービスが適切な空き状況を返せるようにします。

let slots = try await CCAI.shared.callService?.getScheduledTimeSlots(
    menuId: menu.id,
    callIdForRescheduling: nil
) ?? []

既存の予約済み通話のスケジュールを変更する場合は、既存の通話 ID を渡して、サービスが適切な空き状況を返せるようにします。

let slots = try await CCAI.shared.callService?.getScheduledTimeSlots(
    menuId: menu.id,
    callIdForRescheduling: existingCallId
) ?? []

通話のスケジュールを設定する

ユーザーが時間帯を選択したら、callService を使用して予約通話を作成します。

SDK が提供するもの: 選択したスロットを予約し、スケジュール設定された通話レコードを返す createScheduledCall API。

作成する内容: E.164 電話番号の検証、確認 UI、スケジュールされた通話 ID のローカル永続性、スケジューリング エラーの復元。

実装例

選択したスロット、電話番号、キュー ID、RecordingPermission.notAsked を ScheduledCallRequest で渡します。

let response = try await CCAI.shared.callService?.createScheduledCall(
    ScheduledCallRequest(
        menuId: menu.id,
        phoneNumber: userPhoneNumber,
        scheduleTime: selectedSlot,
        recordingPermission: .notAsked,
        callIdForRescheduling: nil,
        customData: nil,
        ticketId: nil
    )
)
saveScheduledCallId(response?.id)

電話番号は +14155551234 などの E.164 形式にする必要があります。

スケジュール設定された通話をリスケジュールする

スケジュールを変更するには、既存のスケジュール設定された通話 ID を callIdForRescheduling として渡します。

SDK が提供するもの: 同じタイムスロットと作成 API。既存の予約を識別するために callIdForRescheduling が使用されます。

作成するもの: "change time" UI、保存されたスケジュール設定された通話 ID のローカル ルックアップ、新しい予約の作成後の確認ステータスの更新。

実装例

ユーザーが新しいスロットを選択したら、既存の通話 ID を createScheduledCall に渡します。

let response = try await CCAI.shared.callService?.createScheduledCall(
    ScheduledCallRequest(
        menuId: menu.id,
        phoneNumber: userPhoneNumber,
        scheduleTime: newSelectedSlot,
        recordingPermission: .notAsked,
        callIdForRescheduling: existingCallId,
        customData: nil,
        ticketId: nil
    )
)
saveScheduledCallId(response?.id)

スケジュール設定した通話をキャンセルする

ユーザーが予定されている通話をキャンセルした場合は、cancelScheduledCall を呼び出して、ローカルに保存されている通話 ID をクリアします。

SDK が提供するもの: スケジュールされた呼び出し ID のキャンセル API。

構築するもの: 確認プロンプト、キャンセル成功またはエラー UI、ローカルに保存された今後の通話の状態のクリーンアップ。

実装例

保存した ID を使用して cancelScheduledCall(callId:) を呼び出し、アプリのストレージから ID を削除します。

try await CCAI.shared.callService?.cancelScheduledCall(callId: existingCallId)
clearScheduledCallId()

アプリの再起動後に今後の通話の状態の提供、リスケジュール、キャンセルなどの操作を行う場合は、スケジュール設定された通話の ID をアプリに保持します。

メール

SDK が提供するもの: その特定のキュー用に構成された宛先メールアドレスと、管理者がユーザーに表示させたい指示(「口座番号を記載してください」など)。

作成するもの: メール作成画面と、その完了を追跡するデリゲート。独自のカスタムフォームを作成することも、Apple の組み込みの MFMailComposeViewController を使用することもできます。

実装例

このコードは、SDK からサポートのメールアドレスと手順を取得します。iOS の組み込みメール作成ツールが開き、MFMailComposeViewControllerDelegate を使用して、ユーザーが [送信] または [キャンセル] を選択した瞬間をリッスンします。

import UIKit
import MessageUI

class SupportViewController: UIViewController, MFMailComposeViewControllerDelegate {
    // 1. Trigger the email flow
    func openEmailComposer(for menu: QueueMenu) {
        guard let emailChannel = menu.channels?.email else { return }

        if MFMailComposeViewController.canSendMail() {
            let mail = MFMailComposeViewController()
            mail.mailComposeDelegate = self

            // Use the metadata provided by the SDK
            mail.setToRecipients([emailChannel.email].compactMap { $0 })
            mail.setMessageBody(emailChannel.instructionMessage ?? "", isHTML: false)
            present(mail, animated: true)
        } else {
            showError("Mail services are not configured on this device.")
        }
    }

    // 2. Track the outcome using Apple's delegate
    func mailComposeController(
        _ controller: MFMailComposeViewController,
        didFinishWith result: MFMailComposeResult,
        error: Error?
    ) {
        controller.dismiss(animated: true)

        switch result {
        case .sent:
            print("Email successfully sent!")
        case .cancelled:
            print("User cancelled the email.")
        case .saved:
            print("Email saved as draft.")
        case .failed:
            print("Email failed to send: \(error?.localizedDescription ?? "Unknown error")")
        @unknown default:
            break
        }
    }
}

SDK が提供するもの: 管理者ポータルで設定されたとおりの URL(会社のヘルプセンター、払い戻しポリシー、パートナー アプリなど)とその表示タイトルのリスト。

作成するもの: ユーザーがリンクを選択したときに、組み込みのアプリ内ブラウザで開くか、Safari アプリに送信するかして、リンクを実行するロジック。

実装例

このヘルパーは URL 文字列を受け取り、Apple のアプリ内ブラウザに表示します。

import SafariServices

func openHelpCenterLink(_ urlString: String) {
    guard let url = URL(string: urlString) else { return }
    let safariViewController = SFSafariViewController(url: url)
    present(safariViewController, animated: true)
}

iOS では、ExternalDeflectionLink に最上位の url はありません。リンクは内部の links: [ExternalDeflection]? 配列内にあり、有効なエントリごとに 1 つのボタンがチャンネル メニューに追加されます。配列を反復処理し、enabled フラグが true ではないエントリをスキップします。

func setupDeflectionLinks(for queueMenu: QueueMenu) {
    // Clear any previously-rendered buttons
    helpCenterStackView.arrangedSubviews.forEach { $0.removeFromSuperview() }

    guard let links = queueMenu.channels?.externalDeflectionLink?.links,
          !links.isEmpty else {
        helpCenterStackView.isHidden = true
        return
    }

    helpCenterStackView.isHidden = false

    for link in links where link.enabled == true {
        let button = UIButton(type: .system)
        button.setTitle(link.displayName, for: .normal)
        button.addAction(UIAction { [weak self] _ in
            self?.openHelpCenterLink(link.url)
        }, for: .touchUpInside)
        helpCenterStackView.addArrangedSubview(button)
    }
}

ExternalDeflectionLink は enabled: Bool? と links: [ExternalDeflection]? を公開します。各 ExternalDeflection は、独自の url と displayName を持ちます。QueueMenu.getEnabledChannels() が使用されている場合、SDK は有効なリンクごとに 1 つの .externalDeflection(url:displayName:) エントリを出力します。そのため、links を直接反復処理しても、有効なチャンネルの出力を反復処理しても、同じボタンのセットが生成されます。