Unity SDK

Game Chat Unity SDK 사용 방법에 대해 설명합니다.

요구 사양

Game Chat Unity SDK를 사용하기 위한 요구 사양은 다음과 같습니다.

• 최소 사양: 2018.4.0 이상 (하위 버전의 Unity 지원이 필요할 경우 '[e-mail]' 이메일로 문의해 주십시오. )

• 2019.4.X / 2020.3.X / 2021.1.X 버전의 Unity 에디터 사용자는 2019.4.29f1 이상 / 2020.3.15f2 이상 / 2021.1.16f1 이상 버전을 사용해 주십시오(AAB 버전 빌드 시 Unity 에디터 버그 수정 버전).

SDK 설치 및 환경 구성

Game Chat Unity SDK를 다운로드하고 Unity에서 프로젝트를 구성하는 방법은 다음과 같습니다.

1. Game Chat 대시보드 > 설정 > SDK 다운로드 메뉴를 차례대로 클릭한 후 Unity SDK 다운로드를 클릭해 주십시오.

2. Unity 프로그램을 실행한 후 프로젝트를 생성해 주십시오.

3. Unity에서 Assets > Import Package > Custom Package... 메뉴를 차례대로 클릭해 주십시오.

4. 대시보드에서 다운로드한 'GameChatUnitySDK_xxxxxxxx' 파일을 불러와 주십시오.

5. 패키지에 있는 모든 파일을 선택한 후 [Import] 버튼을 클릭해 주십시오.

6. 프로젝트를 저장해 주십시오.

인증

Game Chat 인스턴스 초기화

Game Chat 프로젝트 아이디를 활용하여 GameChat 인스턴스를 초기화하려면 아래 코드를 사용해 주십시오.

GameChat.initialize(PROJECT_ID);

// 싱가폴 리전 사용 시
GameChat.setRegion("sg");
GameChat.initialize(PROJECT_ID);

ID	type	desc
PROJECT_ID	string	프로젝트 아이디

Game Chat 소켓 서버 연결

Game Chat 소켓 서버에 연결하는 방법은 다음과 같습니다.

1. 채팅 사용자 아이디를 사용하여 Game Chat 소켓 서버에 접속해 주십시오.

   • Game Chat 프로젝트에서 채팅 사용자 아이디는 고유한 값입니다.

2. API를 사용하기 위한 토큰값을 획득해 주십시오.

   • GameChat.connect 이후에 갱신된 토큰값을 확인할 수 있습니다.

3. 토큰값을 획득한 후 현재 접속 디바이스에 대한 채팅 사용자 정보가 갱신되었는지 확인해 주십시오.

   • GameChat.connect의 콜백으로 전달받는 Member는 갱신된 데이터입니다.

GameChat 소켓 서버에 연결하려면 아래 코드를 사용해 주십시오.

GameChat.connect(USER_ID,  (Member User, GameChatException Exception)=> 
{

    if(Exception != null)
    {
        // Error 핸들링
        return;
    }
});

ID	type	desc
USER_ID	string	채팅 사용자 고유 아이디

Game Chat 서버 연결 해제

Game Chat 소켓 서버와의 연결을 해제하려면 아래 코드를 사용해 주십시오.

GameChat.disconnect();

채팅 사용자 정보 업데이트

connect 성공이 후 채팅 사용자 정보를 저장하고 업데이트하려면 아래 코드를 사용해 주십시오.

닉네임 수정

GameChat.setNickname(USER_ID, NickName, (member, exception) =>
{
    if (exception != null)
    {
        // Error 핸들링
        return;
    }
    
});

ID	type	desc
USER_ID	string	채팅 사용자 고유 아이디
NickName	string	채팅 사용자 닉네임

Profile URL 수정

GameChat.setProfileUrl(USER_ID, ProfileUrl, (member, exception) =>
{
    if (exception != null)
    {
        // Error 핸들링
        return;
    }
    
});

ID	type	desc
USER_ID	string	채팅 사용자 고유 아이디
ProfileUrl	string	채팅 사용자 ProfileUrl

채널 구독 및 구독 해제

특정 채널에 Subscribe하거나 Unsubscribe하려면 아래 코드를 사용해 주십시오.

GameChat.subscribe(CHANNEL_ID);

GameChat.unsubscribe(CHANNEL_ID);

ID	type	desc
CHANNEL_ID	string	채널 아이디

메시지 송신

특정 채널에 메시지를 보내려면 아래 코드를 사용해 주십시오.

GameChat.sendMessage(CHANNEL_ID, MESSAGE);

ID	type	desc
CHANNEL_ID	string	채널 아이디
MESSAGE	string	전송 메시지 텍스트

MESSAGE 파라미터에 @[유저아이디] 공백 [메시지 내용]으로 입력 시

@user_id 메시지본문

위 케이스에서 유저아이디가 로그인된 이력이 있는 경우에 메시지 상세 정보 중 mentions의 정보는 유저아이디입니다.

이벤트 등록 및 해제

Game Chat 소켓 서버로부터 수신되는 이벤트에 대해, 커스텀 핸들러를 등록하거나 해제하려면 아래 코드를 사용해 주십시오.

GameChat.dispatcher.(EVENT_NAME) += (CALLBACK_FUNCTION);

public delegate void onConnectedCallback(string data);
public onConnectedCallback onConnected;
//'connect' Event에 대한, callback

public delegate void onDisconnectedCallback(string reason);
public onDisconnectedCallback onDisconnected;
//'disconnect' Event에 대한, callback

public delegate void onMessageReceivedCallback(Message message);
public onMessageReceivedCallback onMessageReceived;
//'message' Event에 대한, callback

public delegate void onUserAddedCallback(UserInfo userinfo);
public onUserAddedCallback onUserAdded;
//'userAdded' Event에 대한, callback

public delegate void onUserRemovedCallback(Message message);
public onUserRemovedCallback onUserRemoved;
//'userRemoved' Event에 대한, callback

public delegate void onErrorReceivedCallback(string result, GameChatException exception);
public onErrorReceivedCallback onErrorReceived;
//'error' Event에 대한, callback

예외 사항

Game Chat API 사용 중에 발생하는 Exception에 대한 공통 처리 Class는 다음과 같습니다.

public class GameChatException
{
    // Detail Error Code
   
    // 알 수 없는 Error
    public static readonly int CODE_UNKNOWN_ERROR           = 0;
    // 초기화 실패
    public static readonly int CODE_NOT_INITALIZE           = 1;
    // 파라미터가 올바르지 않은 경우
    public static readonly int CODE_INVAILD_PARAM           = 2;  
    // 소켓서버로부터 발생한 오류
    public static readonly int CODE_SOCKET_SERVER_ERROR     = 500;
    //소켓으로부터 발생한 오류
    public static readonly int CODE_SOCKET_ERROR = -501;
    // 네트워크 연결 오류 및 타임아웃 발생 시
    public static readonly int CODE_SERVER_NETWORK_ERROR    = 4002;
    // 서버에서 받은 데이터를 파싱할 때 오류
    public static readonly int CODE_SERVER_PARSING_ERROR    = 4003;

    // HTTP 에러의 경우, 해당 상태코드가 응답코드로 전달됩니다. (400, 403 ...)

    // Error Code
    public int code { get; set; }
    // Error Message
    public string message { get; set; }
}

Client API

채널 구독

Subscription Data Class (per Unit)

public class Subscription
{
    public string id;
    public string channel_id;
    public string user_id;
    public string created_at;
}

ID	type	desc
id	string	유니크 아이디
channel_id	string	채널 아이디
user_id	string	채팅 사용자 고유 아이디
created_at	string	생성 일자

채널 Subscription 목록 가져오기

특정 채널의 Subscription 데이터를 목록 형태로 가져오려면 아래 코드를 사용해 주십시오.

GameChat.getSubscriptions(CHANNEL_ID, OFFSET, LIMIT, (List<Subscription> Subscriptions, GameChatException Exception) => {

    if(Exception != null)
    {
        // Error 핸들링
        return;
    }

    foreach(Subscription elem in Subscriptions)
    {
        //handling each subscription instance
    }
}));

채널

Channel Data Class (per Unit)

public class Channel
{
    public string id;
    public string project_id;
    public string unique_id;
    public string name;
    public string user_id;
    public string created_at;
    public string updated_at;
}

ID	type	desc
id	string	채널 아이디(unique)
project_id	string	프로젝트 아이디
unique_id	string	개발사에서 설정 가능한 채널 아이디 (unique)
name	string	채널 이름
user_id	string	(채널 생성한) 채팅 사용자 아이디
created_at	string	생성 일자
updated_at	string	갱신 일자

채널 목록 가져오기

프로젝트의 채널 데이터를 목록 형태로 가져오려면 아래 코드를 사용해 주십시오.

GameChat.getChannels(OFFSET, LIMIT, (List<Channel> Channels, GameChatException Exception) => {

    if(Exception != null)
    {
        // Error 핸들링
        return;
    }

    foreach(Channel elem in Channels)
    {
        //handling each channelInfo instance
    }
});

ID	type	desc
OFFSET	int	전체 채널 목록에서 가져올 채널의 시작 위치 (index)
LIMIT	int	가져올 채널 개수

채널 데이터 가져오기

채널 ID 및 UniqueID를 활용하여 채널 데이터를 가져오려면 아래 코드를 사용해 주십시오.

//CHANNEL_ID로만 Search 할 경우, CHANNEL_UNIQUE_ID 파라미터에 null을 넣어 주십시오.

//CHANNEL_ID와 CHANNEL_UNIQUE_ID값이 함께 존재하면 CHANNEL_UNIQUE_ID 값을 우선으로 Search합니다.

GameChat.getChannel(CHANNEL_ID, CHANNEL_UNIQUE_ID,  (Channel Channel, GameChatException Exception) => {

    if(Exception != null)
    {
        // Error 핸들링
        return;
    }

    //handling channelInfo instance
});

GameChat.getChannel(CHANNEL_UNIQUE_ID, (Channel Channel, GameChatException Exception) => {

    if(Exception != null)
    {
        // Error 핸들링
        return;
    }

    //handling channelInfo instance
});

ID	type	desc
CHANNEL_ID	string	채널 아이디 (auto generated)
CHANNEL_UNIQUE_ID	string	채널 (고유) 아이디 (customizing available)

채널 생성 및 삭제

프로젝트 내 새로운 채널을 생성 및 삭제하려면 Open API를 활용해야 합니다. 보안 문제로 인해 채널 생성, 업데이트 등을 Open API를 활용하여 Server to Server로 직접 생성 하시는걸 추천 드립니다. 자세한 내용은 Game Chat API 가이드{target="_blank"}를 참고해 주십시오.

메시지

(Received) Message Data Class (per Unit)

public class Message
{
    public class User
    {
        public string id;
        public string name;
        public string profile;
    }

    public string message_id;
    public string channel_id;
    public string message_type;
    public string content;

    public string[] mentions;
    public bool mentions_everyone;
    public User sender;
    public string created_at;
}

ID	type	desc
message_id	string	메시지 유니크 아이디
channel_id	string	채널 아이디
message_type	string	메시지 타입
content	string	메시지 내용 (json string)
mentions	string	멘션(태그)
created_at		string

메시지 목록 가져오기

특정 채널에 대한 메시지 데이터를 목록 형태로 가져오려면 아래 코드를 사용해 주십시오.

GameChat.getMessages(CHANNEL_ID, OFFSET, LIMIT, SEARCH, QUERY, SORT, (List<Message> Messages, GameChatException Exception) => {

    if(Exception != null)
    {
        // Error 핸들링
        return;
    }

    foreach(Message elem in Messages)
    {
        //handling each message instance
    }
});

ID	type	desc
CHANNEL_ID	string	채널 아이디
OFFSET	string	전체 메시지 목록에서 가져올 메시지의 시작 위치
LIMIT	string	가져올 메시지 개수
SEARCH	string	메시지 검색 기준 key. <예시> content.text 빈 문자열 전달 시, full scan
QUERY	string	메시지 검색 value. 완전 일치만 검색 가능. 빈 문자열 전달 시, full scan
SORT	string	메시지 정렬 순서 (default : desc - 가장 최근 순) (optional : asc)

메시지 번역

자동 번역 기능이 활성화되어 있을 경우, 임의의 텍스트를 지정한 언어로 번역할 수 있습니다. 자동 번역 기능은 Papago Translation{target="_blank"} 서비스와 연동한 후에 사용할 수 있습니다.

(Received) Translation Data Class (per Unit)

public class Translation
{
    public string detectLang = "";
    public string lang = "";
    public bool translated = false;
    public string message = "";
}

ID	type	desc
detectLang	string	출발 언어 코드
lang	string	도착 언어 코드
translated	bool	번역 성공 여부
message	string	결과 메시지 내용 (json string)

참고

출발 언어 코드와 도착 언어 코드에 대한 설명은 Papago Text Translation API 가이드{target="_blank"}를 참고해 주십시오.

GameChat.translateMessage(CHANNEL_ID, SORCE_LANG, TARTGET_LANG, TEXT, (List<Translation> Translations, GameChatException Exception) => {

    if(Exception != null)
    {
        // Error 핸들링
        return;
    }

    foreach(Translation elem in Translations)
    {
        //handling each Translation instance
    }
});

GameChat.translateMessage(SORCE_LANG, TARTGET_LANG, TEXT, (List<Translation> Translations, GameChatException Exception) => {

    if(Exception != null)
    {
        // Error 핸들링
        return;
    }

    foreach(Translation elem in Translations)
    {
        //handling each Translation instance
    }
});

ID	type	desc
CHANNEL_ID	string	채널 아이디
SORCE_LANG	string	송신할 텍스트 언어명 (auto: 자동감지) API Guide{target="_blank"} 참고
TARTGET_LANG	string	(번역 수신할) 텍스트 언어 코드 (","로 구분하여 복수 입력 가능. <예시> "en, fr, th") Papago Text Translation API 가이드 {target="blank"} 참고
TEXT	string	송신할 텍스트

채팅 사용자

(Received) Member Data Class (per Unit)

public class Member
{
    public string id = "";
    public string project_id = "";
    public string nickname = "";
    public string profile_url = "";
    public string country = "";
    public string remoteip = "";
    public string adid = "";
    public string device = "";
    public string network = "";
    public string version = "";
    public string model = "";
    public string logined_at = "";
    public string created_at = "";
    public string updated_at = "";
}

ID	type	desc
id	string	채팅 사용자 고유 아이디
project_id	string	로그인한 Game Chat 프로젝트 아이디
nickname	string	채팅 사용자 닉네임
profile_url	string	프로필 이미지 URL
country	string	접속 국가
remoteip	string	접속 IP
adid	string	광고 식별자
device	string	접속 디바이스 환경
network	string	접속 네트워크 타입(CELLULAR, WIFI)
version	string	접속 앱 버전
model	string	접속 디바이스 모델
logined_at	string	로그인한 일자
created_at	string	채팅 사용자 생성 일자
updated_at	string	채팅 사용자 정보 갱신 일자

채팅 사용자 정보 업데이트

채팅 서버의 사용자 정보를 업데이트할 수 있습니다.

// 채팅 사용자 닉네임 업데이트
// 닉네임 허용 문자열은 whitespace(spaces, tabs, line breaks)를 포함하지 않는 2~128자입니다.
GameChat.setName(MEMBER_ID, NAME, (Member member, GameChatException Exception) => {

    if(Exception != null)
    {
        // Error 핸들링
        return;
    }
    //handling updated Member instance
});

//채팅 사용자 프로필 이미지 url 업데이트
GameChat.setProfileUrl(MEMBER_ID, PROFILE_URL, (Member member, GameChatException Exception) => {

    if(Exception != null)
    {
        // Error 핸들링
        return;
    }
    //handling updated Member instance
});

ID	type	desc
MEMBER_ID	string	채팅 사용자 고유 아이디
NAME	string	채팅 사용자 닉네임 혹은 이름
PROFILE	string	프로필 이미지 URL

GameChatExtension (Emoji, HyperLink)

수신 메시지에 포함된 Emoji와 HyperLink 텍스트를 쉽게 다룰 수 있도록 도와주는 Helper Class 입니다.

• TMP_GameChatTextUGUI는 Unity Built-In Asset인 TextMeshPro를 확장한 클래스이므로 먼저 Package Manager를 이용하여 TextMeshPro를 설치해야 합니다.

• TextMeshPro Asset의 경우, Unity 2018.2 이상의 버전부터 Built-In Asset으로 포함됩니다.

• Emoji Sprite Sheet의 경우, Emoji version 13(Android)를 기준으로 기본 출력되며 Sprite Sheet를 변경하여 커스터마이징이 가능합니다.

namespace GameChatUnity.Extension
{
    public class TMP_GameChatTextUGUI : TextMeshProUGUI
    {
        public bool isHyperLinked { get; set; }    // link 형태 주소를 hyperlink 처리 여부 (append html tag)
        public string LinkTextColor { get; set; }  // hyperlink text color
    }
}

<예시>

using GameChatUnity.Extension;

TMP_GameChatTextUGUI message = msgObject.GetComponent<TMP_GameChatTextUGUI>();

//hyperlink 인식 및 처리를 위해, text는 setMessage를 통해 넣어 주십시오.
message.setMessage(MESSAGE_CONTENT);
message.color = Color.green;
message.isHyperLinked = true;

...

msgObject = Instantiate(msgObject) as GameObject;

...

// hyperlink에 대한 click event listener는, 직접 구현해 주십시오.

//Handling with TMP_LinkInfo
TMP_LinkInfo linkInfoArr = message.textInfo.linkInfo[LINK_INDEX];

...