# IVS 聊天功能客户端消息收发 SDK：Android 指南
Amazon Interactive Video（IVS）Chat 客户端消息收发 Android SDK 提供界面，可让您在使用 Android 的平台上轻松整合我们的 [IVS Chat 消息收发 API](https://docs.aws.amazon.com//ivs/latest/chatmsgapireference/welcome.html)。
`com.amazonaws:ivs-chat-messaging` 软件包实现了本文档中所描述的接口。
**IVS 聊天功能客户端消息收发 Android SDK 的最新版本：**1.1.0（[发布说明](https://docs.aws.amazon.com//ivs/latest/ChatUserGuide/release-notes.html#jan31-23)）
**参考文档：**有关 Amazon IVS Chat 客户端消息收发 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 聊天功能客户端消息收发 Android SDK 入门
在开始之前，应该熟悉 [Amazon IVS Chat 入门](getting-started-chat.md)。
## 添加程序包
将 `com.amazonaws:ivs-chat-messaging` 添加到 `build.gradle` 依赖项：
```
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) 通信。使用[官方亚马逊云科技库](https://aws.amazon.com/developer/tools/)从服务器访问 Amazon IVS API。这些库可以从 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 聊天功能客户端消息收发 Android SDK
本文档将引导您完成使用 Amazon IVS 聊天功能客户端消息收发 Android SDK 涉及的步骤。
## 初始化聊天室实例
创建 `ChatRoom` 类的实例。此操作需要传递 `regionOrUrl`（通常是托管聊天室的 AWS 区域）和 `tokenProvider`（上一步中创建的令牌获取方法）。
```
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() `lifecycle 方法中执行此操作，以确保在应用程序从后台恢复时保持连接状态。
```
room.connect()
```
SDK 将尝试与聊天室建立连接，该聊天室是使用从服务器收到的聊天令牌进行编码的。如果失败，它将尝试重新连接聊天室实例中指定的次数。
## 在聊天室中执行操作
`ChatRoom` 类包含发送和删除消息以及与其他用户断开连接的操作。这些操作接受可选的回调参数，该参数允许您获取请求确认或拒绝通知。
### 发送消息
对于此请求，您必须使用聊天令牌对 `SEND_MESSAGE` 功能进行编码。
触发发送消息请求：
```
val request = SendMessageRequest("Test Echo")
room.sendMessage(request)
```
要获得请求的确认/拒绝，请提供回调作为第二个参数：
```
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 功能。
触发删除消息请求：
```
val request = DeleteMessageRequest(messageId, "Some delete reason")
room.deleteMessage(request)
```
要获得请求的确认/拒绝，请提供回调作为第二个参数：
```
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)
```
要获得请求的确认/拒绝，请提供回调作为第二个参数：
```
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 连接将在短时间后停止工作，因此我们建议您在从后台状态转换为其他状态/转换为后台状态时手动连接/断开连接。为此，请将 `onResume()` 生命周期方法中有关 Android `Activity` 或 `Fragment` 的 `room.connect()` 调用与 `onPause()` 生命周期方法中的 `room.disconnect()` 调用相匹配。