# 《IVS 聊天用戶端傳訊 SDK：Android 版指南》
Amazon Interactive Video (IVS) Chat 用戶端傳訊 Android 版開發套件的介面可讓您輕鬆使用 Android 來整合我們平台上的 [IVS 聊天傳訊 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 聊天功能用戶端傳訊 Android 版開發套件中最重要方法的資訊，請參閱參考文件，網址為 [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 level 21) 或更高版本。
# 開始使用 IVS 聊天功能用戶端傳訊 Android SDK
在開始使用之前，請先詳閱 [Amazon IVS 聊天功能入門](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) 通訊的端點才能進行此整合。使用[官方 AWS 程式庫](https://aws.amazon.com/developer/tools/)從您的伺服器存取 Amazon IVS API。透過公開套件就可以使用這些程式庫，而且有多種程式語言可供選用；例如 node.js 和 Java。
接下來，建立一個可與 [Amazon IVS 聊天功能 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() ` 生命週期方法中這樣做，以確保它在應用程式從背景中恢復時保持連線。
```
room.connect()
```
開發套件會試圖連線至聊天室，而該聊天室是以從伺服器收到的聊天權杖加以編碼。如果失敗，它會試圖重新連線，直至達到在聊天室執行個體中指定的次數為止。
## 在聊天室中執行動作
`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 連線就會停止運作，因此建議您在從背景狀態來回轉換時手動連線/中斷連線。若要這樣做，則 Android `Activity` 或 `Fragment` 上 `onResume()` 生命週期方法中的 `room.connect()` 呼叫必須與 `onPause()` 生命週期方法中的 `room.disconnect()` 呼叫相符。