Chat SDK 초기화
기능 설명
Chat SDK의 각 기능을 사용하기 전에 반드시 초기화해야 합니다.
초기화
SDK를 초기화하려면 다음과 같은 단계를 수행해야 합니다.
1. SDKAppID를 준비합니다.
2.
TencentCloudChat.create를 호출하여 SDK를 초기화합니다.3. SDK 이벤트를 모니터링합니다.
아래에서는 단계별로 자세히 설명해 드리겠습니다.
SDKAppID 준비
정확한 SDKAppID를 가져야만 초기화를 할 수 있습니다.
SDKAppID는 Tencent Cloud IM 서비스에서 고객 계정을 구분하기 위한 유일한 식별자입니다. 저희는 각 독립적인 App에 대해 모두 하나의 새로운 SDKAppID를 신청하시는 것을 권장합니다. 상이한 SDKAppID 사이의 메시지는 자연적으로 격리되어 서로 교환할 수 없습니다.
Chat Console에서 모든 SDKAppID를 확인하시고,
Create Applicaion 버튼을 클릭하여 새로운 SDKAppID를 생성할 수 있습니다.
초기화 인터페이스 호출
인터페이스
TencentCloudChat.create(options);
매개변수 options은 Object 유형이며, 이에 포함되는 속성 값은 다음과 같습니다.
Name | Type | Description |
SDKAppID | Number | Chat 애플리케이션의 SDKAppID |
proxyServer | String | undefined | WebSocket 서버 프록시 주소(미니 프로그램 플랫폼은 IP 주소 사용이 지원 안 됨) |
예시
// v2.x의 SDK를 이미 통합했고, 프로젝트 코드를 최대한 적게 변경하면서 V3으로 업그레이드하시려면 계속하여 TIM을 사용할 수 있습니다.// import TIM from '@tencentcloud/chat';import TencentCloudChat from '@tencentcloud/chat';import TIMUploadPlugin from 'tim-upload-plugin';import TIMProfanityFilterPlugin from 'tim-profanity-filter-plugin';let options = {SDKAppID: 0 // 액세스할 때 당신의 Chat 애플리케이션 SDKAppID로 0을 대체해야 합니다.};// SDK 인스턴스를 생성하며, `TencentCloudChat.create()` 방법은 동일한 `SDKAppID`에 대해 동일한 인스턴스만 반환합니다.let chat = TencentCloudChat.create(options); // SDK 인스턴스는 일반적으로 chat로 나타냅니다.chat.setLogLevel(0); // 일반 레벨의 경우, 로그량이 많으므로 액세스할 때 사용하는 것을 권장합니다.// chat.setLogLevel(1); // release 레벨의 경우, SDK가 핵심 정보를 출력하므로 생산 환경에서 사용하는 것을 권장합니다.// Tencent Cloud Chat 업로드 플러그인chat.registerPlugin({'tim-upload-plugin': TIMUploadPlugin});// Tencent Cloud Chat 로컬 심사 플러그인 등록chat.registerPlugin({'tim-profanity-filter-plugin': TIMProfanityFilterPlugin});
이벤트 모니터링
SDK_READY
SDK가 ready 상태로 들어갈 때 트리거되며, 액세스 측에서는 이 이벤트를 모니터링하고, 그 다음 SDK의 메시지 송신 등을 위한 API를 호출하여 SDK의 각 기능을 사용할 수 있습니다.
let onSdkReady = function(event) {let message = chat.createTextMessage({to: 'user1',conversationType: 'C2C',payload: { text: 'Hello world!' }});chat.sendMessage(message);};chat.on(TencentCloudChat.EVENT.SDK_READY, onSdkReady);
SDK_NOT_READY
SDK가 not ready 상태일 때 트리거되면, 액세스 측은 SDK의 메시지 송신 등 기능을 사용할 수 없게 됩니다. 사용을 재개하려면 액세스 측은 login 인터페이스를 호출하여 SDK를 ready 상태로 구동해야 합니다.
let onSdkNotReady = function(event) {// chat.login({userID: 'your userID', userSig: 'your userSig'});};chat.on(TencentCloudChat.EVENT.SDK_NOT_READY, onSdkNotReady);
MESSAGE_RECEIVED
SDK는 푸시된 1대1 채팅, 그룹 채팅, 그룹 알림, 그룹 시스템 알림의 새 메시지를 수신하며, 액세스 측은 event.data를 순회함으로써 메시지 목록 데이터를 획득하고 페이지에 렌더링할 수 있습니다.
let onMessageReceived = function(event) {// event.data - Message 객체를 저장하기 위한 배열 - [Message]};chat.on(TencentCloudChat.EVENT.MESSAGE_RECEIVED, onMessageReceived);
MESSAGE_MODIFIED
SDK는 메시지가 수정되었다는 알림을 받고, 메시지 송신측은 event.data를 순회함으로써 메시지 목록 데이터를 획득하고 페이지에 있는 동일 ID 메시지의 내용을 업데이트할 수 있습니다.
사용예:
1. 1대1 채팅 사용자 또는 그룹 구성원이 【Hello World】라는 메시지를 보내고 화면에 올린 후 SDK가 이 메시지가 제3자에 의해 콜백되어 수정되었다는 알림을 받으면(예를 들어 【Hello China】로 수정되었고, 상대 측 또는 다른 구성원은 【Hello China】를 수신함), 이때 SDK는 이 이벤트를 트리거합니다.
2. 액세스 측은 이벤트 콜백에서 수정된 메시지를 순회하고, 페이지에 있는 동일 ID 메시지의 내용을 대체하는데, 【Hello World】를 【Hello China】로 대체한 후 다시 렌더링하여 표시합니다.
let onMessageModified = function(event) {// event.data - 수정된 Message 객체를 저장하기 위한 배열 - [Message]};chat.on(TencentCloudChat.EVENT.MESSAGE_MODIFIED, onMessageModified);
MESSAGE_REVOKED
SDK가 메시지가 철회되었다는 알림을 받으면, 액세스 측은 event.data를 순회함으로써 철회된 메시지 목록 데이터를 획득하고 페이지에 렌더링하며, 예를 들어 1대1 채팅 대화 내에는 ‘상대방이 메시지를 철회했습니다’라고 표시되고, 그룹 채팅 내에는 ‘XXX가 메시지를 철회했습니다’라고 표시될 수 있습니다.
let onMessageRevoked = function(event) {// event.data - Message 객체를 저장하기 위한 배열 - [Message] - 각 Message 객체의 isRevoked 속성 값은 true임};chat.on(TencentCloudChat.EVENT.MESSAGE_REVOKED, onMessageRevoked);
MESSAGE_READ_BY_PEER
SDK가 상대 측이 메시지를 읽었다는 알림을 수신하면, 메시지 수신 측이 setMessageRead를 호출하여 읽음을 성공적으로 보고한 후 메시지 수신 측은 이 이벤트를 수신하게 됩니다. 액세스 측은 event.data를 순회함으로써 상대 측에서 읽은 메시지 목록 데이터를 획득하고 페이지에 렌더링하며, 예를 들어 1대1 채팅 대화 내에서 자신이 발송한 메시지를 ‘읽지 않음’ 상태에서 ‘읽음’ 상태로 변경할 수 있습니다.
let onMessageReadByPeer = function(event) {// event.data - Message 객체를 저장하기 위한 배열 - [Message] - 각 Message 객체의 isPeerRead 속성 값은 true임};chat.on(TencentCloudChat.EVENT.MESSAGE_READ_BY_PEER, onMessageReadByPeer);
MESSAGE_READ_RECEIPT_RECEIVED
let onMessageReadReceiptReceived = function(event) {// event.data - 메시지 읽음 확인 정보를 저장하기 위한 배열const readReceiptInfoList = event.data;readReceiptInfoList.forEach((item) => {const { groupID, userID, messageID, readCount, unreadCount, isPeerRead } = item;// messageID - 메시지 ID// userID - C2C 메시지 수신 측// isPeerRead - C2C 메시지 상대 측의 읽음 여부// groupID - 그룹 ID// readCount - 그룹 메시지 읽은 인원수// unreadCount - 그룹 메시지 읽지 않은 인원수const message = chat.findMessage(messageID);if (message) {if (message.conversationType === TencentCloudChat.TYPES.CONV_C2C) {if (message.readReceiptInfo.isPeerRead === true) {// 상대 측 읽음}} else if (message.conversationType === TencentCloudChat.TYPES.CONV_GROUP) {if (message.readReceiptInfo.unreadCount === 0) {// 전부 읽음} else {// message.readReceiptInfo.readCount - 최신 메시지 읽음 수// 어느 그룹 구성원이 이 메시지를 읽었는지 조회하시려면 [getGroupMessageReadMemberList] 인터페이스를 사용하십시오.}}}});}chat.on(TencentCloudChat.EVENT.MESSAGE_READ_RECEIPT_RECEIVED, onMessageReadReceiptReceived);
MESSAGE_EXTENSIONS_UPDATED
SDK가 메시지 확장 업데이트 알림을 수신하고, setMessageExtensions 호출하여 성공적으로 설정하면 자신과 상대 측 사용자(C2C) 또는 그룹 구성원(Group)은 모두 이 이벤트를 수신하게 됩니다.
let onMessageExtensionsUpdated = function(event) {const { messageID, extensions } = event.data;// messageID - 메시지 ID// extensions - 메시지 확장 정보extensions.forEach((item) => {const { key, value } = item;// key - 메시지 확장 key// value - 메시지 확장 key에 대응되는 value 값});};chat.on(TencentCloudChat.EVENT.MESSAGE_EXTENSIONS_UPDATED, onMessageExtensionsUpdated);
MESSAGE_EXTENSIONS_DELETED
SDK가 메시지 확장 삭제 알림을 수신하고 deleteMessageExtensions를 호출하여 성공적으로 삭제하면, 자신과 상대 측 사용자(C2C) 또는 그룹 구성원(Group)은 모두 이 이벤트를 수신하게 됩니다.
let onMessageExtensionsDeleted = function(event) {const { messageID, keyList } = event.data;// messageID - 메시지 ID// keyList - 삭제된 메시지 확장 key 목록keyList.forEach((key) => {// console.log(key)});};chat.on(TencentCloudChat.EVENT.MESSAGE_EXTENSIONS_DELETED, onMessageExtensionsDeleted);
CONVERSATION_LIST_UPDATED
대화 목록 업데이트인 경우, event.data는 Conversation 객체를 포함하는 배열입니다.
let onConversationListUpdated = function(event) {console.log(event.data); // Conversation 인스턴스를 포함하는 배열};chat.on(TencentCloudChat.EVENT.CONVERSATION_LIST_UPDATED, onConversationListUpdated);
TOTAL_UNREAD_MESSAGE_COUNT_UPDATED
대화의 읽지 않은 총 수 업데이트인 경우, event.data는 현재 1대1 채팅 및 그룹 채팅 대화의 읽지 않은 총 수입니다.
주의:
1. 읽지 않은 총 수에서 알림 음소거로 설정된 대화의 읽지 않은 수를 뺍니다.
2. 읽지 않은 총 수는 시스템 대화의 읽지 않은 수를 계산하지 않습니다.
let onTotalUnreadMessageCountUpdated = function(event) {console.log(event.data); // 현재 1대1 채팅과 그룹 채팅 대화의 읽지 않은 총 수};chat.on(TencentCloudChat.EVENT.TOTAL_UNREAD_MESSAGE_COUNT_UPDATED, onTotalUnreadMessageCountUpdated);
CONVERSATION_GROUP_LIST_UPDATED
대화 그룹 업데이트 시 트리거됩니다(예: 대화 그룹 생성, 대화 그룹 삭제, 대화 그룹 리네임).
let onConversationGroupListUpdated = function(event) {console.log(event.data); // 전체 대화 그룹 이름 목록}chat.on(TencentCloudChat.EVENT.CONVERSATION_GROUP_LIST_UPDATED, onConversationGroupListUpdated);
CONVERSATION_IN_GROUP_UPDATED
대화 그룹 내의 대화 업데이트 시 트리거됩니다(예를 들어 대화를 그룹에 추가하거나 그룹에서 대화를 삭제함).
let onConversationInGroupUpdated = function(event) {const { groupName, conversationList } = event.data;// groupName - 대화 그룹 이름// conversationList - 그룹 내의 대화 목록}chat.on(TencentCloudChat.EVENT.CONVERSATION_IN_GROUP_UPDATED, onConversationInGroupUpdated);
GROUP_LIST_UPDATED
SDK 그룹 목록 업데이트 시 트리거되며, 액세스 측은 event.data를 순회함으로써 그룹 목록 데이터를 획득하고 페이지에 렌더링합니다.
let onGroupListUpdated = function(event) {console.log(event.data);// Group 인스턴스를 포함하는 배열};chat.on(TencentCloudChat.EVENT.GROUP_LIST_UPDATED, onGroupListUpdated);
GROUP_ATTRIBUTES_UPDATED
그룹 속성 업데이트 시 트리거되며, 액세스 측은 event.data를 통해 업데이트 후의 그룹 속성 데이터를 획득할 수 있습니다.
let onGroupAttributesUpdated = function(event) {const groupID = event.data.groupID // 그룹 IDconst groupAttributes = event.data.groupAttributes // 업데이트 후의 그룹 속성console.log(event.data);};chat.on(TencentCloudChat.EVENT.GROUP_ATTRIBUTES_UPDATED, onGroupAttributesUpdated);
GROUP_COUNTER_UPDATED
SDK가 그룹 카운터 업데이트 알림을 수신하면, 자신과 기타 그룹 구성원은 모두 이 이벤트를 수신하게 됩니다.
let onGroupCounterUpdated = function(event) {const { groupID, key, value } = event.data;// groupID - 그룹 ID// key - 그룹 카운터 key// value - 그룹 카운터 key에 대응되는 value};chat.on(TencentCloudChat.EVENT.GROUP_COUNTER_UPDATED, onGroupCounterUpdated);
TOPIC_CREATED
화제 생성 시 트리거됩니다.
let onTopicCreated = function(event) {const groupID = event.data.groupID // 화제 소속 커뮤니티 IDconst topicID = event.data.topicID // 화제 IDconsole.log(event.data);};chat.on(TencentCloudChat.EVENT.TOPIC_CREATED, onTopicCreated);
TOPIC_DELETED
화제 삭제 시 트리거됩니다.
let onTopicDeleted = function(event) {const groupID = event.data.groupID // 화제 소속 커뮤니티 IDconst topicIDList = event.data.topicIDList // 삭제된 화제 ID 목록console.log(event.data);};chat.on(TencentCloudChat.EVENT.TOPIC_DELETED, onTopicDeleted);
TOPIC_UPDATED
화제 정보 업데이트 시 트리거됩니다.
let onTopicUpdated = function(event) {const groupID = event.data.groupID // 화제 소속 커뮤니티 IDconst topic = event.data.topic // 화제 정보console.log(event.data);};chat.on(TencentCloudChat.EVENT.TOPIC_UPDATED, onTopicUpdated);
PROFILE_UPDATED
자신 또는 친구의 정보가 변경될 때 트리거되며, event.data는 Profile 객체를 포함하는 배열입니다.
let onProfileUpdated = function(event) {console.log(event.data); // Profile 객체를 포함하는 배열};chat.on(TencentCloudChat.EVENT.PROFILE_UPDATED, onProfileUpdated);
USER_STATUS_UPDATED
구독한 사용자 또는 친구의 상태(온라인 상태 또는 사용자 정의 상태)가 변경될 때 트리거됩니다.
let onUserStatusUpdated = function(event) {console.log(event.data);const userStatusList = event.data;userStatusList.forEach((item) => {const { userID, statusType, customStatus } = item;// userID - 사용자 ID// statusType - 사용자 상태로 열거 값 및 설명은 다음과 같습니다.// TencentCloudChat.TYPES.USER_STATUS_UNKNOWN - 미지// TencentCloudChat.TYPES.USER_STATUS_ONLINE - 온라인// TencentCloudChat.TYPES.USER_STATUS_OFFLINE - 오프라인// TencentCloudChat.TYPES.USER_STATUS_UNLOGINED - 미로그인// customStatus - 사용자 정의 상태})};chat.on(TencentCloudChat.EVENT.USER_STATUS_UPDATED, onUserStatusUpdated);
BLACKLIST_UPDATED
SDK 블록리스트 목록 업데이트 시 트리거됩니다.
let onBlacklistUpdated = function(event) {console.log(event.data); // 나의 블록리스트 목록으로, 구조는 사용자 userID를 포함하는 배열입니다.};chat.on(TencentCloudChat.EVENT.BLACKLIST_UPDATED, onBlacklistUpdated);
FRIEND_LIST_UPDATED
친구 목록 업데이트 시 트리거됩니다.
let onFriendListUpdated = function(event) {console.log(event.data);}chat.on(TencentCloudChat.EVENT.FRIEND_LIST_UPDATED, onFriendListUpdated);
FRIEND_GROUP_LIST_UPDATED
친구 그룹 목록 업데이트 시 트리거됩니다.
let onFriendGroupListUpdated = function(event) {console.log(event.data);}chat.on(TencentCloudChat.EVENT.FRIEND_GROUP_LIST_UPDATED, onFriendGroupListUpdated);
FRIEND_APPLICATION_LIST_UPDATED
SDK 친구 신청 목록 업데이트 시 트리거됩니다.
let onFriendApplicationListUpdated = function(event) {// friendApplicationList - 친구 신청 목록 - [FriendApplication]// unreadCount - 친구 신청 읽지 않은 수const { friendApplicationList, unreadCount } = event.data;// 나에게 보내온 친구 신청(즉 타인이 나에게 친구 추가를 신청함)const applicationSentToMe = friendApplicationList.filter((friendApplication) => {return friendApplication.type === TencentCloudChat.TYPES.SNS_APPLICATION_SENT_TO_ME});// 내가 보낸 친구 추가 신청(즉 내가 타인에게 친구 추가를 신청함)const applicationSentByMe = friendApplicationList.filter((friendApplication) => {return friendApplication.type === TencentCloudChat.TYPES.SNS_APPLICATION_SENT_BY_ME});};chat.on(TencentCloudChat.EVENT.FRIEND_APPLICATION_LIST_UPDATED, onFriendApplicationListUpdated);
KICKED_OUT
사용자가 퇴출당해 로그아웃될 때 트리거됩니다.
let onKickedOut = function(event) {console.log(event.data.type);// TencentCloudChat.TYPES.KICKED_OUT_MULT_ACCOUNT(Web 측, 동일 계정, 다중 페이지 로그인으로 인해 퇴출당함)// TencentCloudChat.TYPES.KICKED_OUT_MULT_DEVICE(동일 계정, 다중 기기 로그인으로 인해 퇴출당함)// TencentCloudChat.TYPES.KICKED_OUT_USERSIG_EXPIRED(서명 만료)// TencentCloudChat.TYPES.KICKED_OUT_REST_API(REST API kick 인터페이스 퇴출)};chat.on(TencentCloudChat.EVENT.KICKED_OUT, onKickedOut);
NET_STATE_CHANGE
네트워크 상태가 변경되었습니다.
let onNetStateChange = function(event) {// event.data.state 현재 네트워크 상태로, 열거 값 및 설명은 다음과 같습니다.// TencentCloudChat.TYPES.NET_STATE_CONNECTED - 접속된 네트워크// TencentCloudChat.TYPES.NET_STATE_CONNECTING// 연결 중. 네트워크 지터가 발생할 가능성이 높으며, SDK가 다시 시도합니다. 액세스 측에서는 이 상태에 따라 ‘현재 네트워크 상태가 불안정합니다’ 또는 ‘연결 중’이라고 알릴 수 있습니다.// TencentCloudChat.TYPES.NET_STATE_DISCONNECTED// 네트워크에 접속하지 않았습니다. 액세스 측에서는 이 상태에 따라 ‘현재 네트워크를 사용할 수 없습니다’라고 알릴 수 있습니다. SDK는 여전히 재시도하며, 사용자의 네트워크가 복원되면 SDK는 메시지를 자동으로 동기화합니다.};chat.on(TencentCloudChat.EVENT.NET_STATE_CHANGE, onNetStateChange);
역초기화
SDK 인스턴스를 폐기합니다. SDK는 먼저 logout하고, 그 다음 WebSocket 긴 연결을 끊고 자원을 해제합니다.
chat.destroy();