> ## Documentation Index
> Fetch the complete documentation index at: https://docs-agents.fpt.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# モバイル SDK

> 2 つの公式 SDK で、Live Chat の画面を Android と iOS のアプリに組み込みます

Android と iOS の SDK は、Live Chat チャネルのチャット画面をそのままアプリの中に表示します。どちらも WebView の薄いラッパーで、依存ライブラリを持たず、受け取るパラメータは 3 つだけです。残りはすべて Console の設定から来ます。

<Info icon="mobile-screen">
  SDK は Web ウィジェットと設定を共有します。先に [Live Chat チャネル](/ja/live-chat-channel) に従って Web ウィジェットのチャネルを設定し、設定タブから `connectionKey` を取得してください。
</Info>

## 初期化の 3 つのパラメータ

| パラメータ | 説明 | 必須 |
| - | - | - |
| `appOrigin` | チャットアプリのアドレス。パスを含めて `https://console-agents.fpt.ai/chat-widget` | 必須 |
| `connectionKey` | ウェブサイトチャネルの接続キー。たとえば `wgt_abc123` | 必須 |
| `locale` | 言語。`vi`、`en`、`ja`、`id`、`zh` | 任意 |

<Warning>
  `appOrigin` は `/chat-widget` のパスを必ず残してください。ルートドメインだけを渡すと、WebView はルートにあるアプリを読み込んでしまい、チャット画面が真っ白になります。
</Warning>

<Warning>
  ウェブサイトと違い、モバイル SDK は Console の **既定の言語** を読みません。`locale` を空にすると、チャット画面は常にベトナム語になります。端末の言語を `locale` に渡して、顧客が使っている言語に合わせてください。
</Warning>

## 動作要件

| 項目 | Android | iOS |
| - | - | - |
| 最低バージョン | Android 7.0 (API 24) | iOS 14 |
| 依存関係 | なし。Kotlin ランタイムのみ | なし |
| 必須の宣言 | `INTERNET`。SDK がライブラリのマニフェストで宣言するので、追加は不要です | `Info.plist` に `NSPhotoLibraryUsageDescription` と `NSCameraUsageDescription`。下の警告を参照 |

## SDK パッケージの入手

SDK は公開リポジトリではなく、インストール用のパッケージとしてお渡しします。プラットフォームごとに 1 つ、合計 2 つのアーカイブを受け取るので、使うほうだけを取り出してください。

<CardGroup cols={2}>
  <Card title="fpt-agent-chat-1.0.0-android.zip" icon="android">
    展開し、中の `android/maven` フォルダをプロジェクトにコピーします。たとえば `libs/fpt-agent-chat/maven` へ。隣の `android/chat-1.0.0.aar` は単体のビルドで、Maven リポジトリを追加できないプロジェクト向けです。
  </Card>

  <Card title="fpt-agent-chat-1.0.0-ios.zip" icon="apple">
    展開し、`ios/FptAgentChat.xcframework` をターゲットにドラッグします。
  </Card>
</CardGroup>

<Warning>
  macOS では Finder か `unzip` コマンドで展開し、展開したフォルダを再度 zip に固め直さないでください。`.xcframework` はバンドルなので、別のツールで固め直すと中のリンクが壊れ、Xcode が読み解きにくいエラーを出します。
</Warning>

<Note>
  各アーカイブには、そのプラットフォームの手順を並べた `README.md` が同梱されています。
</Note>

### ライブラリの宣言 - Android

```kotlin theme={null}
// settings.gradle.kts - パッケージに同梱された Maven リポジトリを指す
dependencyResolutionManagement {
    repositories {
        maven { url = uri("$rootDir/libs/fpt-agent-chat/maven") }
        google()
        mavenCentral()
    }
}
```

```kotlin theme={null}
// app モジュールの build.gradle.kts
implementation("vn.fptsmartcloud.agent:chat:1.0.0")
```

### ライブラリの宣言 - iOS

`ios/FptAgentChat.xcframework` をターゲットにドラッグし、**Frameworks, Libraries, and Embedded Content** に **Embed & Sign** で並んでいることを確かめます。

## Android

### チャット画面を全画面で開く

```kotlin theme={null}
val config = FptChatConfig(
    appOrigin     = "https://console-agents.fpt.ai/chat-widget",
    connectionKey = "wgt_abc123",
    locale        = "ja"
)
FptChat.open(context, config)
```

### 既存の画面にチャットを埋め込む

```kotlin theme={null}
val chat = findViewById<FptChatView>(R.id.chat)
chat.load(config)
```

### FptChatView を自分で配置するときに必要なこと

`FptChatActivity` はファイル選択をすでに配線済みです。自分の画面に `FptChatView` を置く場合は、自分で配線する必要があります。配線しないと添付ボタンを押しても何も起きず、コールバックが宙に浮いたままになるので、2 回目も反応しません。

```kotlin theme={null}
private var pendingFiles: ValueCallback<Array<Uri>>? = null

chat.fileChooserHandler = { intent, callback ->
    pendingFiles?.onReceiveValue(null)   // 前のコールバックを宙に浮かせない
    pendingFiles = callback
    startActivityForResult(intent, REQ_FILES)
    true
}

override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
    super.onActivityResult(requestCode, resultCode, data)
    if (requestCode != REQ_FILES) return
    val cb = pendingFiles ?: return
    pendingFiles = null
    cb.onReceiveValue(
        if (resultCode == RESULT_OK && data?.data != null) arrayOf(data.data!!)
        else null
    )
}
```

<Note>
  `FptChatView` を載せる Activity には、`AndroidManifest.xml` で `android:windowSoftInputMode="adjustResize"` も必要です。これがないとキーボードが入力欄を覆います。`FptChatActivity` にはすでに付いています。
</Note>

### 戻るボタンを処理する

```kotlin theme={null}
override fun onBackPressed() {
    if (!chat.onBackPressed()) super.onBackPressed()
}
```

### ライフサイクル

```kotlin theme={null}
override fun onPause()   { chat.pause();   super.onPause() }
override fun onResume()  { super.onResume(); chat.resume() }
override fun onDestroy() { chat.release(); super.onDestroy() }
```

<Note>
  3 つのライフサイクルメソッドをすべて呼んでください。`release()` を飛ばすと、画面を閉じたあとも WebView が生き残り、メモリリークになります。
</Note>

## iOS

### 必須: Info.plist の 2 つのキー

チャット画面では顧客が添付を送れ、`chat.allow_attachments` は既定でオンなので、これは例外ではなく通常の経路です。`Info.plist` に `NSPhotoLibraryUsageDescription` か `NSCameraUsageDescription` が欠けていると、顧客が添付ボタンを押した瞬間に OS が **アプリを終了** させます。エラー表示ではなく終了です。顧客が読んで分かる文言で、両方とも宣言してください。

```xml theme={null}
<key>NSPhotoLibraryUsageDescription</key>
<string>会話で画像を送るために、写真ライブラリへのアクセスが必要です。</string>
<key>NSCameraUsageDescription</key>
<string>会話で写真を撮って送るために、カメラへのアクセスが必要です。</string>
```

### チャット画面を全画面で開く

```swift theme={null}
let config = FptChatConfig(
    appOrigin: "https://console-agents.fpt.ai/chat-widget",
    connectionKey: "wgt_abc123",
    locale: "ja"
)
try FptChat.present(from: self, config: config)
```

### 既存の画面にチャットを埋め込む

```swift theme={null}
let chat = FptChatView()
try chat.load(config)
```

### 外部リンクを開く

```swift theme={null}
chat.externalLinkHandler = { url in UIApplication.shared.open(url) }
```

### WebView の中で戻る

```swift theme={null}
if !chat.goBack() { navigationController?.popViewController(animated: true) }
```

## 覚えておくこと

<CardGroup cols={2}>
  <Card title="設定は Console にあります" icon="sliders">
    配色、あいさつ、質問の候補、添付の可否は、すべてウィジェットのカスタマイズタブから来ます。Console で変えればアプリにもすぐ反映され、再リリースは要りません。
  </Card>

  <Card title="言語は渡す必要があります" icon="language">
    ウェブとの唯一の違いです。端末のシステム言語を読んで `locale` に渡してください。
  </Card>

  <Card title="1 つのチャネルで複数の接点" icon="share-nodes">
    ウェブサイトとモバイルアプリは 1 つの `connectionKey` を共有するので、会話も設定も同じものになります。
  </Card>

  <Card title="チャネルを作り直すとキーも変わります" icon="key">
    ウェブサイトのチャネルを削除して作り直すと、新しい `connectionKey` が発行されます。配布済みのアプリは更新が必要です。
  </Card>
</CardGroup>

## リリース前チェックリスト

* Console で Web ウィジェットのチャネルを設定し、少なくとも一度保存した。
* `appOrigin` を Console から取得し、`/chat-widget` のパスが残っている。
* `connectionKey` が、使いたい Agent のチャネルのものと一致している。
* 端末の `locale` を渡している。SDK は Console の既定言語を読まないため。
* iOS: `Info.plist` に `NSPhotoLibraryUsageDescription` と `NSCameraUsageDescription` がある。ないと、顧客が添付ボタンを押した瞬間にアプリが終了します。
* Android で `FptChatView` を自分で配置した場合: `fileChooserHandler` と `onActivityResult` を配線し、Activity に `windowSoftInputMode="adjustResize"` を設定した。
* 開く、閉じる、戻るを何度か繰り返し、ライフサイクルの処理を確認した。
* 回線の弱い環境で試し、読み込み中の表示とエラーメッセージが意味の通るものか確認した。

<Info icon="table-list">
  添付のサイズ上限、許可される形式、共通のエラーコードは [技術付録](/ja/technical-appendix) にあります。
</Info>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.