# IVS Chat Client SDK: Android 설명서
<a name="chat-sdk-android"></a>

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 챗 클라이언트 메시징 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의 [https://github.com/aws-samples/amazon-ivs-chat-for-android-demo](https://github.com/aws-samples/amazon-ivs-chat-for-android-demo)에서 Android 샘플 리포지토리를 참조하세요.

**플랫폼 요구 사항:** 개발 환경에는 Android 5.0(API 레벨 21) 이상이 필요합니다.

# IVS Chat Client Messaging Android SDK 시작하기
<a name="chat-android-getting-started"></a>

시작하기 전에 [Amazon IVS Chat 시작하기](getting-started-chat.md)의 내용을 숙지해야 합니다.

## 패키지 추가
<a name="chat-android-add-package"></a>

`com.amazonaws:ivs-chat-messaging`을 `build.gradle` 종속성에 추가합니다.

```
dependencies {
   implementation 'com.amazonaws:ivs-chat-messaging'
}
```

## Proguard 규칙 추가
<a name="chat-android-proguard-rules"></a>

R8/Proguard 규칙 파일(`proguard-rules.pro`)에 다음 항목을 추가합니다.

```
-keep public class com.amazonaws.ivs.chat.messaging.** { *; }
-keep public interface com.amazonaws.ivs.chat.messaging.** { *; }
```

## 백엔드 설정
<a name="chat-android-setup-backend"></a>

이 통합에는 [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 Chat API](https://docs.aws.amazon.com//ivs/latest/ChatAPIReference/Welcome.html)와 통신하는 서버 엔드포인트를 생성하고 토큰을 생성합니다.

## 서버 연결 설정
<a name="chat-android-setup-server"></a>

`ChatTokenCallback`을 파라미터로 사용하는 메서드를 생성하고 백엔드에서 채팅 토큰을 가져옵니다. 해당 토큰을 콜백의 `onSuccess` 메서드로 전달합니다. 오류가 발생한 경우 예외를 콜백의 `onError` 메서드로 전달합니다. 이는 다음 단계에서 기본 `ChatRoom` 엔터티를 인스턴스화하는 데 필요합니다.

아래에서는 `Retrofit` 호출을 사용하여 위 사항을 구현하는 샘플 코드를 확인할 수 있습니다.

```
// ...

private fun fetchChatToken(callback: ChatTokenCallback) {
    apiService.createChatToken(userId, roomId).enqueue(object : Callback<ChatToken> {
        override fun onResponse(call: Call<ExampleResponse>, response: Response<ExampleResponse>) {
            val body = response.body()
            val token = ChatToken(
                body.token,
                body.sessionExpirationTime,
                body.tokenExpirationTime
            )
            callback.onSuccess(token)
        }

        override fun onFailure(call: Call<ChatToken>, throwable: Throwable) {
            callback.onError(throwable)
        }
    })
}
// ...
```

# IVS Chat Client Messaging Android SDK 사용
<a name="chat-android-using-sdk"></a>

이 문서에서는 Amazon IVS Chat Client Messaging Android SDK 사용과 관련된 단계를 안내합니다.

## 채팅 룸 인스턴스 초기화
<a name="chat-android-initialize-room"></a>

`ChatRoom` 클래스의 인스턴스를 만듭니다. 채팅 룸이 호스팅된 AWS 리전인 `regionOrUrl`, 그리고 이전 단계에서 생성된 토큰 가져오기 메서드인 `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()
```

SDK는 서버에서 받은 채팅 토큰으로 인코딩된 채팅 룸과의 연결을 설정하려고 시도합니다. 실패하면 룸 인스턴스에 지정된 횟수만큼 다시 연결을 시도합니다.

## 채팅 룸에서 작업 수행
<a name="chat-android-room-actions"></a>

`ChatRoom` 클래스에는 메시지를 보내고 삭제하고 다른 사용자의 연결을 끊는 작업이 있습니다. 이러한 작업은 요청 확인 또는 거부 알림을 받을 수 있는 선택적 콜백 파라미터를 허용합니다.

### 메시지 전송
<a name="chat-android-room-actions-send-message"></a>

이 요청의 경우 채팅 토큰에 `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.
   }
})
```

### 메시지 삭제
<a name="chat-android-room-actions-delete-message"></a>

이 요청의 경우 채팅 토큰에 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.
   }
})
```

### 다른 사용자 연결 해제
<a name="chat-android-room-actions-disconnect-user"></a>

이 요청의 경우 채팅 토큰에 `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.
   }
})
```

## 채팅 룸 연결 해제
<a name="chat-android-disconnect-room"></a>

채팅 룸과의 연결을 해제하려면 룸 인스턴스에서 `disconnect()` 메서드를 호출합니다.

```
room.disconnect()
```

애플리케이션이 백그라운드 상태일 때 잠시 후 WebSocket 연결의 작동이 중지되므로 백그라운드 상태로 또는 백그라운드 상태에서 전환할 때 수동으로 연결하거나 연결을 해제하는 것이 좋습니다. 이를 위해 Android `room.connect()` 또는 `onResume()`에서 `Activity` 수명 주기 메서드의 `Fragment` 호출과 `room.disconnect()` 수명 주기 메서드의 `onPause()` 호출을 일치시킵니다.