IVS Chat Client Messaging JavaScript SDK 사용

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

채팅 룸 인스턴스 초기화

ChatRoom 클래스의 인스턴스를 만듭니다. 인스턴스 생성을 위해regionOrUrl(채팅룸이 호스팅되는 AWS 리전) 및tokenProvider(토큰 가져오기 메서드는 다음 단계에서 생성)를 통과해야 합니다.

const room = new ChatRoom({
  regionOrUrl: 'us-west-2',
  tokenProvider: tokenProvider,
});

토큰 공급자 함수

백엔드에서 채팅 토큰을 가져오는 비동기(asynchronous) 토큰 공급자 함수를 생성합니다.

type ChatTokenProvider = () => Promise<ChatToken>;

함수는 매개 변수를 받지 않아야 하며 채팅 토큰 객체가 포함된 Promise를 반환해야 합니다.

type ChatToken = {
  token: string;
  sessionExpirationTime?: Date;
  tokenExpirationTime?: Date;
}

이 함수는 ChatRoom 객체를 초기화하는 데 필요하므로 아래의 내용 중<token> 및<date-time> 필드에 백엔드에서 받은 값을 입력하세요.

// You will need to fetch a fresh token each time this method is called by
// the IVS Chat Messaging SDK, since each token is only accepted once.
function tokenProvider(): Promise<ChatToken> {
  // Call your backend to fetch chat token from IVS Chat endpoint: 
  // e.g. const token = await appBackend.getChatToken()
  return {
    token: "<token>",
    sessionExpirationTime: new Date("<date-time>"),
    tokenExpirationTime: new Date("<date-time>")
  }
}

반드시 ChatRoomtokenProvider 생성자에 전달하세요. ChatRoom은 연결이 중단되거나 세션이 만료되면 토큰을 새로 고침 합니다. ChatRoom에서 자동으로 토큰을 처리하므로 토큰을 다른 곳에 저장하는 데 tokenProvider를 사용하지 마세요.

이벤트 수신

다음으로 채팅룸 이벤트를 구독하여 대화방에서 전달되는 메시지와 이벤트뿐만 아니라 라이프사이클 이벤트를 수신하세요.

/**
* Called when room is establishing the initial connection or reestablishing
* connection after socket failure/token expiration/etc
*/
const unsubscribeOnConnecting = room.addListener('connecting', () => { });

/** Called when connection has been established. */
const unsubscribeOnConnected = room.addListener('connect', () => { });

/** Called when a room has been disconnected. */
const unsubscribeOnDisconnected = room.addListener('disconnect', () => { });

/** Called when a chat message has been received. */
const unsubscribeOnMessageReceived = room.addListener('message', (message) => {
 /* Example message:
  * {
  *   id: "5OPsDdX18qcJ",
  *   sender: { userId: "user1" },
  *   content: "hello world",
  *   sendTime: new Date("2022-10-11T12:46:41.723Z"),
  *   requestId: "d1b511d8-d5ed-4346-b43f-49197c6e61de"
  * }
  */
});

/** Called when a chat event has been received. */
const unsubscribeOnEventReceived = room.addListener('event', (event) => {
 /* Example event:
  * {
  *   id: "5OPsDdX18qcJ",
  *   eventName: "customEvent,
  *   sendTime: new Date("2022-10-11T12:46:41.723Z"),
  *   requestId: "d1b511d8-d5ed-4346-b43f-49197c6e61de",
  *   attributes: { "Custom Attribute": "Custom Attribute Value" }
  * }
  */
});

/** Called when `aws:DELETE_MESSAGE` system event has been received. */
const unsubscribeOnMessageDelete = room.addListener('messageDelete', (deleteMessageEvent) => {
 /* Example delete message event:
  * {
  *   id: "AYk6xKitV4On",
  *   messageId: "R1BLTDN84zEO",
  *   reason: "Spam",
  *   sendTime: new Date("2022-10-11T12:56:41.113Z"),
  *   requestId: "b379050a-2324-497b-9604-575cb5a9c5cd",
  *   attributes: { MessageID: "R1BLTDN84zEO", Reason: "Spam" }
  * }
  */
});

/** Called when `aws:DISCONNECT_USER` system event has been received. */
const unsubscribeOnUserDisconnect = room.addListener('userDisconnect', (disconnectUserEvent) => {
 /* Example event payload:
  * {
  *   id: "AYk6xKitV4On",
  *   userId": "R1BLTDN84zEO",
  *   reason": "Spam",
  *   sendTime": new Date("2022-10-11T12:56:41.113Z"),
  *   requestId": "b379050a-2324-497b-9604-575cb5a9c5cd",
  *   attributes": { UserId: "R1BLTDN84zEO", Reason: "Spam" }
  * }
  */
});

채팅룸에 연결

기본 초기화의 마지막 단계는 WebSocket 연결을 설정하여 특정 룸에 연결하는 것입니다. 이를 위해 룸 인스턴스 내에서 connect() 메서드를 호출합니다.

room.connect();

SDK가 서버에서 받은 채팅 토큰으로 인코딩된 채팅룸과의 연결을 설정하려고 시도합니다.

connect()을 호출하면 룸이connecting 상태로 전환되어connecting 이벤트가 발생합니다. 룸이 성공적으로 연결되면connected 상태로 전환되고connect 이벤트가 발생합니다.

토큰을 가져오거나 WebSocket에 연결할 때 문제가 발생하여 연결 실패가 발생할 수 있습니다. 이 경우, 룸은maxReconnectAttempts 생성자 매개변수에 표시된 횟수까지 자동으로 다시 연결을 시도합니다. 재연결을 시도하는 동안에는 룸이connecting 상태이며 추가 이벤트가 발생하지 않습니다. 재연결 시도 횟수를 모두 소진하면 해당 룸이disconnected 상태로 전환되고 관련 연결 해제 이유가 포함된disconnect 이벤트가 발생합니다. disconnected 상태에서는 룸이 더 이상 연결을 시도하지 않습니다. 연결 프로세스를 트리거하려면 connect()를 다시 호출해야 합니다.

채팅룸에서 작업 수행

Amazon IVS Chat Messaging SDK는 메시지 전송, 메시지 삭제 및 다른 사용자 연결 해제를 위한 사용자 작업을 제공합니다. 이들 기능은 ChatRoom 인스턴스에서 사용할 수 있습니다. 요청 확인 또는 거부 수신을 허용하는 Promise 객체를 반환합니다.

메시지 전송

이 요청의 경우 채팅 토큰에 SEND_MESSAGE 기능이 인코딩되어 있어야 합니다.

메시지 전송 요청 트리거:

const request = new SendMessageRequest('Test Echo');
room.sendMessage(request);

요청에 대한 확인 또는 거부를 얻으려면 await 반환된 약속(promise)을 받거나 다음 then() 메서드를 사용하세요.

try {
  const message = await room.sendMessage(request);
  // Message was successfully sent to chat room
} catch (error) {
  // Message request was rejected. Inspect the `error` parameter for details.
}

메시지 삭제

이 요청의 경우 채팅 토큰에 DELETE_MESSAGE 기능이 인코딩되어 있어야 합니다.

조절 목적으로 메시지를 삭제하려면 다음deleteMessage() 메서드를 호출하십시오.

const request = new DeleteMessageRequest(messageId, 'Reason for deletion');
room.deleteMessage(request);

요청에 대한 확인 또는 거부를 얻으려면 await 반환된 약속(promise)을 받거나 다음 then() 메서드를 사용하세요.

try {
  const deleteMessageEvent = await room.deleteMessage(request);
  // Message was successfully deleted from chat room
} catch (error) {
  // Delete message request was rejected. Inspect the `error` parameter for details.
}

다른 사용자 연결 해제

이 요청의 경우 채팅 토큰에 DISCONNECT_USER 기능이 인코딩되어 있어야 합니다.

조절 목적으로 다른 사용자의 연결 해제disconnectUser():

const request = new DisconnectUserRequest(userId, 'Reason for disconnecting user');
room.disconnectUser(request);

요청에 대한 확인 또는 거부를 얻으려면 await 반환된 약속(promise)을 받거나 다음 then() 메서드를 사용하세요.

try {
  const disconnectUserEvent = await room.disconnectUser(request);
  // User was successfully disconnected from the chat room
} catch (error) {
  // Disconnect user request was rejected. Inspect the `error` parameter for details.
}

채팅룸 연결 해제

채팅룸과의 연결을 해제하려면 room 인스턴스에서 disconnect() 메서드를 호출하세요.

room.disconnect();

이 메서드를 호출하면 룸이 기본 WebSocket을 순서대로 닫습니다. 룸 인스턴스가disconnected 상태로 전환되고 disconnect 이유가 "clientDisconnect"로 설정된 연결 해제 이벤트가 발생합니다.