# Amazon IVS Chat 시작하기
Amazon Interactive Video Service(IVS) Chat은 라이브 비디오 스트림과 함께 사용할 수 있는 관리형 라이브 채팅 기능입니다. (IVS 챗은 비디오 스트림 없이도 사용할 수 있습니다.) 채팅룸을 생성하고 사용자 간 채팅 세션을 활성화할 수 있습니다.
Amazon IVS Chat을 사용하면 라이브 비디오와 함께 맞춤형 채팅 경험을 구축하는 데 집중할 수 있습니다. 인프라를 관리하거나 채팅 워크플로의 구성 요소를 개발하고 구성할 필요가 없습니다. Amazon IVS Chat은 확장 가능하고 안전하고 안정적이며 비용 효율적입니다.
Amazon IVS Chat은 시작과 끝으로 라이브 비디오 스트림 참가자 간 메시징을 용이하게 하는 데 가장 적합합니다.
이 문서의 나머지 부분에서는 Amazon IVS Chat을 사용하여 첫 번째 채팅 애플리케이션을 구축하는 단계를 안내합니다.
**예:** 다음과 같은 데모 앱을 사용할 수 있습니다(토큰 생성을 위한 샘플 클라이언트 앱 3개와 백엔드 서버 앱 1개).
+ [Amazon IVS Chat 웹 데모](https://github.com/aws-samples/amazon-ivs-chat-web-demo)
+ [Amazon IVS Chat for Android 데모](https://github.com/aws-samples/amazon-ivs-chat-for-android-demo)
+ [Amazon IVS Chat for iOS 데모](https://github.com/aws-samples/amazon-ivs-chat-for-ios-demo)
+ [Amazon IVS Chat 데모 백엔드](https://github.com/aws-samples/amazon-ivs-chat-web-demo/tree/main/serverless)
**중요:** 24개월 동안 새로운 연결이나 업데이트가 없는 채팅룸은 자동으로 삭제됩니다.
**Topics**
+ [1단계: 초기 설정 수행](getting-started-chat-create-account.md)
+ [2단계: 채팅룸 생성](getting-started-chat-create-room.md)
+ [3단계: 채팅 토큰 생성](getting-started-chat-auth.md)
+ [4단계: 첫 번째 메시지 전송 및 수신](getting-started-chat-send-and-receive.md)
+ [5단계: 서비스 할당량 한도 확인(선택 사항)](getting-started-chat-check-service-quota.md)
# 1단계: 초기 설정 수행
계속하려면 먼저 다음을 수행해야 합니다.
1. AWS 계정을 생성합니다.
1. 루트 및 관리 사용자를 설정합니다.
1. AWS IAM(Identity and Access Management) 권한을 설정합니다. 아래에 지정된 정책을 사용합니다.
위의 모든 것에 대한 구체적인 단계는 **Amazon IVS 사용 설명서의 [IVS 지연 시간이 짧은 스트리밍 시작하기](https://docs.aws.amazon.com/ivs/latest/LowLatencyUserGuide/getting-started.html)를 참조하세요. **중요**: ‘3단계: IAM 권한 설정’에 IVS 챗을 위한 다음 정책을 사용합니다.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ivschat:CreateChatToken",
"ivschat:CreateLoggingConfiguration",
"ivschat:CreateRoom",
"ivschat:DeleteLoggingConfiguration",
"ivschat:DeleteMessage",
"ivschat:DeleteRoom",
"ivschat:DisconnectUser",
"ivschat:GetLoggingConfiguration",
"ivschat:GetRoom",
"ivschat:ListLoggingConfigurations",
"ivschat:ListRooms",
"ivschat:ListTagsForResource",
"ivschat:SendEvent",
"ivschat:TagResource",
"ivschat:UntagResource",
"ivschat:UpdateLoggingConfiguration",
"ivschat:UpdateRoom"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"servicequotas:ListServiceQuotas",
"servicequotas:ListServices",
"servicequotas:ListAWSDefaultServiceQuotas",
"servicequotas:ListRequestedServiceQuotaChangeHistoryByQuota",
"servicequotas:ListTagsForResource",
"cloudwatch:GetMetricData",
"cloudwatch:DescribeAlarms"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"logs:CreateLogDelivery",
"logs:GetLogDelivery",
"logs:UpdateLogDelivery",
"logs:DeleteLogDelivery",
"logs:ListLogDeliveries",
"logs:PutResourcePolicy",
"logs:DescribeResourcePolicies",
"logs:DescribeLogGroups",
"s3:PutBucketPolicy",
"s3:GetBucketPolicy",
"iam:CreateServiceLinkedRole",
"firehose:TagDeliveryStream"
],
"Resource": "*"
}
]
}
```
------
# 2단계: 채팅룸 생성
Amazon IVS Chat 채팅방에 구성 정보(예: 최대 메시지 길이)가 연결됩니다.
이 섹션의 지침은 콘솔 또는 AWS CLI를 사용하여 채팅룸을 설정하고(메시지 검토 및/또는 로깅 메시지를 위한 선택적 설정 포함) 채팅룸을 만드는 방법을 보여줍니다.
# IVS 채팅룸 생성을 위한 콘솔 지침
이러한 단계는 초기 룸 설정부터 시작하여 최종 룸 생성으로 끝나는 단계로 나뉩니다.
메시지를 검토하도록 방을 설정할 수도 있습니다. 예를 들어 메시지 내용 또는 메타데이터를 업데이트하거나, 메시지를 거부하여 전송되지 않도록 하거나, 원본 메시지가 전달되도록 할 수 있습니다. [방 메시지 검토 설정(선택 사항)](#create-room-console-review-messages)에서 이를 다룹니다.
또한 메시지가 로그되도록 방을 설정할 수도 있습니다. 예를 들어 채팅룸으로 메시지를 보내는 경우 Amazon S3 버킷, Amazon CloudWatch 또는 Amazon Kinesis Data Firehose에 대한 메시지를 로그할 수 있습니다. [메시지 로그 검토 설정(선택 사항)](#create-room-console-log-messages)에서 이를 다룹니다.
## 초기 방 설정
1. [Amazon IVS Chat 콘솔](https://console.aws.amazon.com/ivs/chat)을 엽니다.
([AWS Management Console](https://console.aws.amazon.com/)을 통해 Amazon IVS 콘솔에 액세스할 수도 있습니다.)
1. 탐색 모음에서 **리전 선택** 드롭다운을 사용하여 리전을 선택합니다. 이 리전에 새 방이 생성됩니다.
1. **시작하기** 상자(오른쪽 위)에서 **Amazon IVS Chat Room**을 선택합니다. **방 생성** 창이 나타납니다.
![\[채팅룸 생성.\]](http://docs.aws.amazon.com/ko_kr/ivs/latest/ChatUserGuide/images/Chat_Create_Room.png)
1. **설정**에서 **방 이름**(선택 사항)을 지정합니다. 방 이름은 고유하지 않지만 이를 통해 방 ARN(Amazon 리소스 이름) 이외의 방을 구분할 수 있습니다.
1. **설정 > 방 구성**에서 **기본 구성**을 수락하거나 **사용자 지정 구성**을 선택한 다음 **최대 메시지 길이** 및/또는 **최대 메시지 속도**를 구성합니다.
1. 메시지를 검토하려면 아래의 [방 메시지 검토 설정(선택 사항)](#create-room-console-review-messages)으로 계속합니다. 그렇지 않으면 건너뛰고(즉, **메시지 검토 핸들러 > 비활성화됨** 수락) [최종 방 생성](#create-room-console-final)으로 바로 진행합니다.
## 방 메시지 검토 설정(선택 사항)
1. **메시지 검토 핸들러**에서 **AWS Lambda로 처리**를 선택합니다. **메시지 검토 핸들러** 섹션이 확장되어 추가 옵션이 표시됩니다.
1. 핸들러가 유효한 응답을 반환하지 않거나, 오류가 발생하거나, 제한 시간을 초과하는 경우 **대체 결과**를 메시지 **허용** 또는 **거부**로 구성합니다.
1. 기존 **Lambda 함수**를 지정하거나 **Lambda 함수 생성**을 사용하여 새 함수를 생성합니다.
lambda 함수는 채팅룸과 동일한 AWS 계정 및 동일한 AWS 리전에 있어야 합니다. Amazon Chat SDK 서비스에 lambda 리소스를 호출할 수 있는 권한을 부여해야 합니다. 선택한 lambda 함수에 대해 리소스 기반 정책이 자동으로 생성됩니다. 권한에 대한 자세한 내용은 [Amazon IVS Chat에 대한 리소스 기반 정책](security-iam.md#security-chat-policy-examples)을 참조하세요.
## 메시지 로그 설정(선택 사항)
1. **메시지 로깅**에서 **채팅 메시지 자동 로그**를 선택합니다. **메시지 로깅** 섹션이 확장되어 추가 옵션이 표시됩니다. 기존 로깅 구성을 이 방에 추가하거나 **로깅 구성 생성**을 선택하여 새 로깅 구성을 생성할 수 있습니다.
1. 기존 로깅 구성을 선택하면 드롭다운 메뉴가 나타나고 이미 생성한 로깅 구성이 모두 다 표시됩니다. 목록에서 하나를 선택하면 채팅 메시지가 이 대상에 자동으로 로그됩니다.
1. **로깅 구성 생성**을 선택하면 새 로깅 구성을 생성하고 사용자 지정할 수 있는 모달 창이 나타납니다.
1. 선택적으로 **로깅 구성 이름**을 지정합니다. 방 이름과 같은 로깅 구성 이름은 고유하지 않지만 이를 통해 로깅 구성 ARN 이외의 로깅 구성을 구분할 수 있습니다.
1. **대상**에서 **CloudWatch 로그 그룹**, **Kinesis firehose 전송 스트림**이나 **Amazon S3 버킷**을 선택하여 로그할 대상을 선택합니다.
1. 대상에 따라 기존 **CloudWatch 로그 그룹**, **Kinesis firehose 전송 스트림**이나 **Amazon S3 버킷**을 사용하거나 새로운 것을 생성하는 옵션을 선택합니다.
1. 검토 후 **생성**을 선택하여 고유한 ARN으로 새 로깅 구성을 생성합니다. 그러면 새 로깅 구성이 채팅룸에 자동으로 연결됩니다.
## 최종 방 생성
1. 검토 후 **채팅룸 생성**을 선택하여 고유한 ARN으로 새 채팅룸을 생성합니다.
# IVS 채팅룸 생성을 위한 CLI 지침
이 문서에서는 AWS CLI를 사용하여 Amazon IVS Chat 채팅방을 생성하는 데 관련된 단계를 안내합니다.
## 채팅룸 생성
AWS CLI를 사용하여 채팅룸을 생성하는 방법은 고급 옵션이며, 먼저 시스템에 CLI를 다운로드하고 구성해야 합니다. 자세한 내용은 [AWS 명령줄 인터페이스 사용 설명서](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-welcome.html)를 참조하세요.
1. 채팅 `create-room` 명령을 실행하고 선택적 이름을 전달합니다.
```
aws ivschat create-room --name test-room
```
1. 그러면 새 채팅룸이 반환됩니다.
```
{
"arn": "arn:aws:ivschat:us-west-2:123456789012:room/g1H2I3j4k5L6",
"id": "string",
"createTime": "2021-06-07T14:26:05-07:00",
"maximumMessageLength": 200,
"maximumMessageRatePerSecond": 10,
"name": "test-room",
"tags": {},
"updateTime": "2021-06-07T14:26:05-07:00"
}
```
1. `arn` 필드를 기록해 둡니다. 이는 클라이언트 토큰을 생성하고 채팅룸에 연결하는 데 필요합니다.
## 로깅 구성 설정(선택 사항)
채팅룸 생성과 마찬가지로 AWS CLI를 사용하여 로깅 구성을 설정하는 것은 고급 옵션이며, 먼저 컴퓨터에 CLI를 다운로드하고 구성해야 합니다. 자세한 내용은 [AWS 명령줄 인터페이스 사용 설명서](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-welcome.html)를 참조하세요.
1. 채팅 `create-logging-configuration` 명령을 실행하고 선택적 이름과 Amazon S3 버킷을 가리키는 대상 구성을 이름별로 전달합니다. 이 Amazon S3 버킷은 로깅 구성을 생성하기 전에 존재해야 합니다. (Amazon S3 버킷 생성에 대한 자세한 내용은 [Amazon S3 설명서](https://docs.aws.amazon.com/AmazonS3/latest/userguide/create-bucket-overview.html)를 참조하세요.)
```
aws ivschat create-logging-configuration \
--destination-configuration s3={bucketName=demo-logging-bucket} \
--name "test-logging-config"
```
1. 그러면 새 로깅 구성이 반환됩니다.
```
{
"Arn": "arn:aws:ivschat:us-west-2:123456789012:logging-configuration/ABcdef34ghIJ",
"createTime": "2022-09-14T17:48:00.653000+00:00",
"destinationConfiguration": {
"s3": {"bucketName": "demo-logging-bucket"}
},
"id": "ABcdef34ghIJ",
"name": "test-logging-config",
"state": "ACTIVE",
"tags": {},
"updateTime": "2022-09-14T17:48:01.104000+00:00"
}
```
1. `arn` 필드를 기록해 둡니다. 채팅룸에 로깅 구성을 연결하려면 이 정보가 필요합니다.
1. 새 채팅룸을 생성하는 경우`create-room` 명령을 실행하고 로깅 구성 `arn`을 전달합니다.
```
aws ivschat create-room --name test-room \
--logging-configuration-identifiers \
"arn:aws:ivschat:us-west-2:123456789012:logging-configuration/ABcdef34ghIJ"
```
1. 기존 채팅룸을 업데이트하는 경우`update-room` 명령을 실행하고 로깅 구성 `arn`을 전달합니다.
```
aws ivschat update-room --identifier \
"arn:aws:ivschat:us-west-2:12345689012:room/g1H2I3j4k5L6" \
--logging-configuration-identifiers \
"arn:aws:ivschat:us-west-2:123456789012:logging-configuration/ABcdef34ghIJ"
```
# 3단계: 채팅 토큰 생성
채팅 참가자가 채팅룸에 접속하여 메시지를 보내고 받기 시작하려면 채팅 토큰을 만들어야 합니다. 채팅 토큰은 채팅 클라이언트를 인증하고 권한을 부여하는 데 사용됩니다.
이 다이어그램은 IVS 채팅 토큰을 생성하기 위한 워크플로를 보여줍니다.
![\[새로 생성된 채팅룸에 대해 클라이언트를 인증하고 권한을 부여합니다.\]](http://docs.aws.amazon.com/ko_kr/ivs/latest/ChatUserGuide/images/Chat_Getting_Started_Auth.png)
위에 표시된 것처럼 클라이언트 애플리케이션은 서버 측 애플리케이션에 토큰을 요청하고 서버 측 애플리케이션은 AWS SDK 또는 [SigV4](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_aws-signing.html) 서명 요청을 사용하여 CreateChatToken을 호출합니다. AWS 자격 증명은 API를 호출하는 데 사용되므로 토큰은 클라이언트 측 애플리케이션이 아닌 안전한 서버 측 애플리케이션에서 생성되어야 합니다.
토큰 생성을 보여주는 백엔드 서버 애플리케이션은 [Amazon IVS Chat 데모 백엔드](https://github.com/aws-samples/amazon-ivs-chat-web-demo/tree/main/serverless)에서 사용할 수 있습니다.
*세션 지속* 시간은 설정된 세션이 자동으로 닫히기 전에 활성 상태를 유지할 수 있는 시간을 나타냅니다. 즉, 세션 지속 시간은 새 토큰이 생성되고 새 연결이 설정되기 전에 클라이언트가 채팅룸에 연결된 상태를 유지할 수 있는 기간입니다. 선택 사항으로, 토큰 생성 중 세션 기간을 지정할 수 있습니다.
각 토큰은 최종 사용자에 대한 연결을 설정하는 데 한 번만 사용할 수 있습니다. 연결이 닫히면 연결을 다시 설정하기 전에 새 토큰을 만들어야 합니다. 토큰 자체는 응답에 포함된 토큰 만료 타임스탬프까지 유효합니다.
최종 사용자가 채팅룸에 연결하려는 경우 클라이언트는 서버 애플리케이션에 토큰을 요청해야 합니다. 서버 애플리케이션은 토큰을 생성하여 클라이언트에 다시 전달합니다. 최종 사용자를 위해 필요에 따라 토큰을 만들어야 합니다.
채팅 인증 토큰을 만들려면 아래 지침을 따르세요. 채팅 토큰을 생성할 때 요청 필드를 사용하여 채팅 최종 사용자 및 최종 사용자의 메시징 기능에 대한 데이터를 전달합니다. 자세한 내용은 **IVS Chat API Reference의 [CreateChatToken](https://docs.aws.amazon.com//ivs/latest/ChatAPIReference/API_CreateChatToken.html)을 참조하세요.
## AWS SDK 지침
AWS SDK를 사용하여 채팅룸을 생성하는 방법은 고급 옵션이며, 먼저 애플리케이션에 SDK를 다운로드하고 구성해야 합니다. 다음은 JavaScript를 사용하는 AWS SDK에 대한 지침입니다.
**중요:** 이 코드는 서버 측에서 실행되어야 하며 해당 출력은 클라이언트에 전달되어야 합니다.
**전제 조건**: 아래 코드 샘플을 사용하려면 애플리케이션에 AWS JavaScript SDK를 로드해야 합니다. 자세한 내용은 [JavaScript용 AWS SDK 시작하기](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/getting-started.html)를 참조하세요.
```
async function createChatToken(params) {
const ivs = new AWS.Ivschat();
const result = await ivs.createChatToken(params).promise();
console.log("New token created", result.token);
}
/*
Create a token with provided inputs. Values for user ID and display name are
from your application and refer to the user connected to this chat session.
*/
const params = {
"attributes": {
"displayName": "DemoUser",
}",
"capabilities": ["SEND_MESSAGE"],
"roomIdentifier": "arn:aws:ivschat:us-west-2:123456789012:room/g1H2I3j4k5L6",
"userId": 11231234
};
createChatToken(params);
```
## CLI 지침
AWS CLI를 사용하여 채팅 토큰을 생성하는 방법은 고급 옵션이며, 먼저 시스템에 CLI를 다운로드하고 구성해야 합니다. 자세한 내용은 [AWS 명령줄 인터페이스 사용 설명서](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-welcome.html)를 참조하세요. 참고: AWS CLI를 사용하여 토큰을 생성하는 것은 테스트 목적에 적합하지만, 프로덕션 용도의 경우 AWS SDK를 사용하여 서버 측에서 토큰을 생성하는 것이 좋습니다(위 지침 참조).
1. 클라이언트의 방 식별자 및 사용자 ID와 함께 `create-chat-token` 명령을 실행합니다. `"SEND_MESSAGE"`, `"DELETE_MESSAGE"`, `"DISCONNECT_USER"` 기능을 포함합니다. 필요에 따라 이 채팅 세션에 대한 세션 기간(분) 및/또는 사용자 지정 속성(메타데이터)을 포함합니다. 이러한 필드는 아래에 표시되지 않습니다.
```
aws ivschat create-chat-token --room-identifier "arn:aws:ivschat:us-west-2:123456789012:room/g1H2I3j4k5L6" --user-id "11231234" --capabilities "SEND_MESSAGE"
```
1. 그러면 클라이언트 토큰이 반환됩니다.
```
{
"token": "abcde12345FGHIJ67890_klmno1234PQRS567890uvwxyz1234.abcd12345EFGHI67890_jklmno123PQRS567890uvwxyz1234abcde12345FGHIJ67890_klmno1234PQRS567890uvwxyz1234abcde",
"sessionExpirationTime": "2022-03-16T04:44:09+00:00",
"tokenExpirationTime": "2022-03-16T03:45:09+00:00"
}
```
1. 이 토큰을 저장합니다. 이는 채팅룸에 연결하고 메시지를 전송하거나 수신하는 데 필요합니다. 해당 세션이 종료되기 전에 다른 채팅 토큰을 생성해야 합니다(`sessionExpirationTime`으로 표시됨).
# 4단계: 첫 번째 메시지 전송 및 수신
클라이언트 토큰을 사용하여 채팅룸에 연결하고 첫 번째 메시지를 전송합니다. 샘플 JavaScript 코드는 아래에 나와 있습니다. IVS 클라이언트 SDK도 사용할 수 있습니다. [채팅 SDK: Android 안내서](chat-sdk-android.md), [채팅 SDK: iOS 안내서](chat-sdk-ios.md) 및 [채팅 SDK: JavaScript 안내서](chat-sdk-js.md)를 참조하세요.
**리전 서비스:** 아래 샘플 코드는 '지원되는 선택 리전'을 나타냅니다. Amazon IVS Chat은 요청 시 사용할 수 있는 리전 엔드포인트를 제공합니다. Amazon IVS Chat Messaging API의 경우 리전 엔드포인트의 일반 구문은 다음과 같습니다.
+ wss://edge.ivschat..amazonaws.com
예를 들어 wss://edge.ivschat.us-west-2.amazonaws.com은 미국 서부(오레곤) 리전의 엔드포인트입니다. 지원되는 리전 목록은 [AWS 일반 참조](https://docs.aws.amazon.com/general/latest/gr/ivs.html)의 *Amazon IVS 페이지*에서 Amazon IVS Chat 정보를 참조하세요.
```
/*
1. To connect to a chat room, you need to create a Secure-WebSocket connection
using the client token you created in the previous steps. Use one of the provided
endpoints in the Chat Messaging API, depending on your AWS region.
*/
const chatClientToken = "GENERATED_CHAT_CLIENT_TOKEN_HERE";
const socket = "wss://edge.ivschat.us-west-2.amazonaws.com"; // Replace “us-west-2” with supported region of choice.
const connection = new WebSocket(socket, chatClientToken);
/*
2. You can send your first message by listening to user input
in the UI and sending messages to the WebSocket connection.
*/
const payload = {
"Action": "SEND_MESSAGE",
"RequestId": "OPTIONAL_ID_YOU_CAN_SPECIFY_TO_TRACK_THE_REQUEST",
"Content": "text message",
"Attributes": {
"CustomMetadata": "test metadata"
}
}
connection.send(JSON.stringify(payload));
/*
3. To listen to incoming chat messages from this WebSocket connection
and display them in your UI, you must add some event listeners.
*/
connection.onmessage = (event) => {
const data = JSON.parse(event.data);
displayMessages({
display_name: data.Sender.Attributes.DisplayName,
message: data.Content,
timestamp: data.SendTime
});
}
function displayMessages(message) {
// Modify this function to display messages in your chat UI however you like.
console.log(message);
}
/*
4. Delete a chat message by sending the DELETE_MESSAGE action to the WebSocket
connection. The connected user must have the "DELETE_MESSAGE" permission to
perform this action.
*/
function deleteMessage(messageId) {
const deletePayload = {
"Action": "DELETE_MESSAGE",
"Reason": "Deleted by moderator",
"Id": "${messageId}"
}
connection.send(deletePayload);
}
```
축하합니다. 모두 설정되었습니다. 이제 메시지를 전송하거나 수신할 수 있는 간단한 채팅 애플리케이션이 생겼습니다.
# 5단계: 서비스 할당량 한도 확인(선택 사항)
채팅룸은 Amazon IVS 라이브 스트림과 함께 확장되어 모든 시청자가 채팅 대화에 참여할 수 있습니다. 그러나 모든 Amazon IVS 계정에는 동시 채팅 참가자 수와 메시지 전달 속도에 대한 제한이 있습니다.
*특히 대규모 스트리밍 이벤트를 계획하고 있는 경우 한도가 적절한지 확인하고 필요한 경우 한도를 늘려달라고 요청하세요*. 자세한 내용은 [Service Quotas (Low-Latency Streaming)](https://docs.aws.amazon.com/ivs/latest/LowLatencyUserGuide/service-quotas.html), [Service Quotas (Real-Time Streaming)](https://docs.aws.amazon.com/ivs/latest/RealTimeUserGuide/service-quotas.html) 및 [서비스 할당량(챗)](service-quotas.md)을 참조하세요.