Unity SDK

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

요구 사양

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

  • 최소 사양: 2018.4.0 이상 (하위 버전의 Unity 지원이 필요할 경우 'cs@nbase.io' 이메일로 문의해 주십시오. )

  • 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);

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;
    }
});

Game Chat 서버 연결 해제

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

GameChat.disconnect();

채팅 사용자 정보 업데이트

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

닉네임 수정

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

Profile URL 수정

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

채널 구독 및 구독 해제

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

GameChat.subscribe(CHANNEL_ID);

GameChat.unsubscribe(CHANNEL_ID);

메시지 송신

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

GameChat.sendMessage(CHANNEL_ID, MESSAGE);

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;
}

채널 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;
}

채널 목록 가져오기

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

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

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

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

채널 데이터 가져오기

채널 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
});

채널 생성 및 삭제

프로젝트 내 새로운 채널을 생성 및 삭제하려면 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;
}

메시지 목록 가져오기

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

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
    }
});

메시지 번역

자동 번역 기능이 활성화되어 있을 경우, 임의의 텍스트를 지정한 언어로 번역할 수 있습니다. 자동 번역 기능은 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 = "";
}

참고

출발 언어 코드와 도착 언어 코드에 대한 설명은 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
    }
});

채팅 사용자

(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 = "";
}

채팅 사용자 정보 업데이트

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


// 채팅 사용자 닉네임 업데이트
// 닉네임 허용 문자열은 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
});

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];

...
PreviousGame Chat 운영 및 관리NextOpenAPI

Last updated