# IVS Chat Client Messaging SDK: Android ガイド
Amazon Interactive Video (IVS) Chat Client Messaging Android SDK は、Android を使用するプラットフォームに [IVS チャットメッセージング API](https://docs.aws.amazon.com//ivs/latest/chatmsgapireference/welcome.html) を簡単に組み込むことができるインターフェイスを提供します。
`com.amazonaws:ivs-chat-messaging` パッケージは、このドキュメントで説明されているインターフェイスを実装します。
**IVS Chat Client Messaging Android SDK の最新バージョン: **1.1.0 ([リリースノート](https://docs.aws.amazon.com//ivs/latest/ChatUserGuide/release-notes.html#jan31-23))
**リファレンスドキュメント:** Amazon IVS Chat Client Messaging Android SDK で使用できる最も重要なメソッドについては、リファレンスドキュメント ([https://aws.github.io/amazon-ivs-chat-messaging-sdk-android/1.1.0/](https://aws.github.io/amazon-ivs-chat-messaging-sdk-android/1.1.0/)) を参照してください。
**サンプルコード:** GitHub の Android サンプルリポジトリ [(https://github.com/aws-samples/amazon-ivs-chat-for-android-demo)](https://github.com/aws-samples/amazon-ivs-chat-for-android-demo) を参照してください。
**プラットフォームの要件:** 開発には Android 5.0 (API レベル 21) 以上が必要です。
# IVS Chat Client Messaging Android SDK の開始方法
開始する前に、「[Amazon IVS Chat の開始方法](getting-started-chat.md)」を理解しておく必要があります。
## Package の追加
次の `build.gradle` 依存関係を `com.amazonaws:ivs-chat-messaging` に追加します。
```
dependencies {
implementation 'com.amazonaws:ivs-chat-messaging'
}
```
## ProGuard ルールの追加
R8/Proguard ルールファイル (`proguard-rules.pro`) に次のエントリを追加してください。
```
-keep public class com.amazonaws.ivs.chat.messaging.** { *; }
-keep public interface com.amazonaws.ivs.chat.messaging.** { *; }
```
## バックエンドのセットアップ
この統合には、[Amazon IVS API](https://docs.aws.amazon.com//ivs/latest/LowLatencyAPIReference/Welcome.html) と通信するサーバ上のエンドポイントが必要です。サーバーから Amazon IVS API へのアクセスに[公式の AWS ライブラリ](https://aws.amazon.com/developer/tools/)を使用します。これらはパブリックパッケージ (node.js や Java など) から、複数の言語でアクセスできます。
次に、[Amazon IVS Chat API](https://docs.aws.amazon.com//ivs/latest/ChatAPIReference/Welcome.html)と通信するサーバーエンドポイントを作成し、トークンを作成します。
## サーバー接続を設定する
`ChatTokenCallback` をパラメータとし、バックエンドからチャットトークンをフェッチするメソッドを作成します。そのトークンをコールバックの `onSuccess` メソッドに渡します。エラーが発生した場合、コールバックの `onError` メソッドへ例外を渡します。これは、次のステップでメイン `ChatRoom` エンティティをインスタンス化するために必要です。
以下に、`Retrofit` 呼び出しを使用して上記を実装するサンプルコードを示します。
```
// ...
private fun fetchChatToken(callback: ChatTokenCallback) {
apiService.createChatToken(userId, roomId).enqueue(object : Callback {
override fun onResponse(call: Call, response: Response) {
val body = response.body()
val token = ChatToken(
body.token,
body.sessionExpirationTime,
body.tokenExpirationTime
)
callback.onSuccess(token)
}
override fun onFailure(call: Call, throwable: Throwable) {
callback.onError(throwable)
}
})
}
// ...
```
# IVS Chat Client Messaging Android SDK を使用する
このドキュメントでは、Amazon IVS Chat Client Messaging Android SDK を使用するためのステップについて説明します。
## チャットルームインスタンスを初期化する
`ChatRoom` クラスのインスタンスを作成します。これには、通常、チャットルームがホストされている AWS リージョンである `tokenProvider` と、前のステップで作成されたトークン取得方法である `regionOrUrl` を渡す必要があります。
```
val room = ChatRoom(
regionOrUrl = "us-west-2",
tokenProvider = ::fetchChatToken
)
```
次に、チャットに関連したイベントのハンドラーを実装するリスナーオブジェクトを作成し、それを `room.listener` プロパティに割り当てます。
```
private val roomListener = object : ChatRoomListener {
override fun onConnecting(room: ChatRoom) {
// Called when room is establishing the initial connection or reestablishing connection after socket failure/token expiration/etc
}
override fun onConnected(room: ChatRoom) {
// Called when connection has been established
}
override fun onDisconnected(room: ChatRoom, reason: DisconnectReason) {
// Called when a room has been disconnected
}
override fun onMessageReceived(room: ChatRoom, message: ChatMessage) {
// Called when chat message has been received
}
override fun onEventReceived(room: ChatRoom, event: ChatEvent) {
// Called when chat event has been received
}
override fun onDeleteMessage(room: ChatRoom, event: DeleteMessageEvent) {
// Called when DELETE_MESSAGE event has been received
}
}
val room = ChatRoom(
region = "us-west-2",
tokenProvider = ::fetchChatToken
)
room.listener = roomListener // <- add this line
// ...
```
基本的な初期化の最後のステップは、WebSocket 接続を確立することによって特定のルームに接続することです。これを行うには、ルームインスタンス内の `connect()` メソッドを呼び出します。アプリがバックグラウンドから再開した場合に接続を維持するには、`onResume() ` ライフサイクルメソッドでこれを行うことをお勧めします。
```
room.connect()
```
SDK は、サーバーから受信したチャットトークンにエンコードされたチャットルームへの接続を確立しようとします。失敗した場合、ルームインスタンスで指定された回数だけ再接続を試みます。
## チャットルームでアクションを実行する
`ChatRoom` クラスには、メッセージの送信と削除、他のユーザーの接続解除を行うアクションがあります。これらのアクションは、リクエストの確認または拒否の通知を受け取ることができるオプションのコールバックパラメータを受け入れます。
### メッセージの送信
このリクエストには、チャットトークンにエンコードされた `SEND_MESSAGE` 機能が必要です。
send-message リクエストをトリガーする方法
```
val request = SendMessageRequest("Test Echo")
room.sendMessage(request)
```
リクエストの確認/拒否を取得するには、2 つ目のパラメータとして次のコールバックを指定します。
```
room.sendMessage(request, object : SendMessageCallback {
override fun onConfirmed(request: SendMessageRequest, response: ChatMessage) {
// Message was successfully sent to the chat room.
}
override fun onRejected(request: SendMessageRequest, error: ChatError) {
// Send-message request was rejected. Inspect the `error` parameter for details.
}
})
```
### メッセージの削除
このリクエストでは、チャットトークンに DELETE\$1MESSAGE 機能がエンコードされている必要があります。
delete-message リクエストをトリガーするには
```
val request = DeleteMessageRequest(messageId, "Some delete reason")
room.deleteMessage(request)
```
リクエストの確認/拒否を取得するには、2 つ目のパラメータとして次のコールバックを指定します。
```
room.deleteMessage(request, object : DeleteMessageCallback {
override fun onConfirmed(request: DeleteMessageRequest, response: DeleteMessageEvent) {
// Message was successfully deleted from the chat room.
}
override fun onRejected(request: DeleteMessageRequest, error: ChatError) {
// Delete-message request was rejected. Inspect the `error` parameter for details.
}
})
```
### 他のユーザーの接続を切断する
このリクエストには、チャットトークンにエンコードされた `DISCONNECT_USER` 機能が必要です。
モデレーションを目的として他のユーザーとの接続を切断するには
```
val request = DisconnectUserRequest(userId, "Reason for disconnecting user")
room.disconnectUser(request)
```
リクエストの確認/拒否を取得するには、2 つ目のパラメータとして次のコールバックを指定します。
```
room.disconnectUser(request, object : DisconnectUserCallback {
override fun onConfirmed(request: SendMessageRequest, response: ChatMessage) {
// User was disconnected from the chat room.
}
override fun onRejected(request: SendMessageRequest, error: ChatError) {
// Disconnect-user request was rejected. Inspect the `error` parameter for details.
}
})
```
## チャットルームの接続を切断する
チャットルームへの接続を閉じるには、ルームインスタンスで次の `disconnect()` メソッドを呼び出します。
```
room.disconnect()
```
アプリケーションがバックグラウンド状態になると、WebSocket 接続はしばらくすると機能しなくなります。バックグラウンド状態から移行またはバックグラウンド状態への移行時には、手動で接続/切断することをおすすめします。Android `Activity` または `Fragment` の `onResume()` ライフサイクルメソッドの `room.connect()` 呼び出しと、`onPause()` ライフサイクルメソッドの `room.disconnect()` 呼び出しを一致させます。