Unity SDK

This page describes how to use the Game Chat Unity SDK.

Requirements

The specifications required to use the Game Chat Unity SDK are as follows.

• Minimum specifications: 2018.4.0 or later (If you need support for the lower version of Unity, then make an inquiry through Contact us.)

• If you are a user of Unity editor in the 2019.4.X/2020.3.X/2021.1.X version, then make sure to use a version at or above 2019.4.29f1/2020.3.15f2/2021.1.16f1 respectively (versions where the Unity editor bug is fixed when building the AAB version).

Install SDK and configure environment

The following describes how to download Game Chat Unity SDK and configure a project in Unity.

1. Click the Settings > Download SDK menus, in that order, and then click Download Unity SDK.

2. Run Unity, and create a project.

3. In Unity, click the Assets > Import Package > Custom Package... menus, in that order.

4. Open the "GameChatUnitySDK_xxxxxxxx" file downloaded in the dashboard.

5. Select all files in the package, and then click the [Import] button.

6. Save the project.

Authentication

Reset Game Chat instance

To initialize Game Chat instances using the Game Chat project ID, use the code below.

GameChat.initialize(PROJECT_ID);

// When using in the Singapore region
GameChat.setRegion("sg");
GameChat.initialize(PROJECT_ID);

ID	type	desc
PROJECT_ID	string	Project ID

Connect to Game Chat socket server

The following describes how to connect to a Game Chat socket server.

1. Use the chat user ID to access a Game Chat socket server.

   • In a Game Chat project, the chat user ID is a unique value.

2. Get the token value for using the API.

   • The token value renewed can be viewed after GameChat.connect.

3. After acquiring the token value, check if the chat user information is renewed for the currently connected device.

   • The member data received with the GameChat.connect's callback is renewed data.

Use the following code to connect to the Game Chat socket server.

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

    if(Exception != null)
    {
        // Error handling
        return;
    }
});

ID	type	desc
USER_ID	string	Chat user's unique ID

Remove Game Chat server connection

To remove the connection with the Game Chat socket server, use the following code.

GameChat.disconnect();

Chat user information update

Use the following code to save and update the chat user information after a successful connect.

Edit nickname

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

ID	type	desc
USER_ID	string	Chat user's unique ID
NickName	string	Chat user's nickname

Edit profile URL

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

ID	type	desc
USER_ID	string	Chat user's unique ID
ProfileUrl	string	Chat user's ProfileUrl

Subscribe and unsubscribe to channel

Use the following code to subscribe or unsubscribe to a specific channel.

GameChat.subscribe(CHANNEL_ID);

GameChat.unsubscribe(CHANNEL_ID);

ID	type	desc
CHANNEL_ID	string	Channel ID

Send message

Use the following code to send a message to a specific channel.

GameChat.sendMessage(CHANNEL_ID, MESSAGE);

ID	type	desc
CHANNEL_ID	string	Channel ID
MESSAGE	string	Message text to send

When @[User ID] space [Message content] is entered for the MESSAGE parameter

@user_id message content

In the above case, if the username has a history of being logged in, the "mentions" information from the message details is the user ID.

Register and remove event

Use the following code to register or remove a custom handler for events received from a Game Chat socket server.

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

public delegate void onConnectedCallback(string data);
public onConnectedCallback onConnected;
//Callback regarding "connect" events

public delegate void onDisconnectedCallback(string reason);
public onDisconnectedCallback onDisconnected;
//Callback regarding "disconnect" events

public delegate void onMessageReceivedCallback(Message message);
public onMessageReceivedCallback onMessageReceived;
//Callback regarding "message" events

public delegate void onUserAddedCallback(UserInfo userinfo);
public onUserAddedCallback onUserAdded;
//Callback regarding "usedAdded" events

public delegate void onUserRemovedCallback(Message message);
public onUserRemovedCallback onUserRemoved;
//Callback regarding "userRemoved" events

public delegate void onErrorReceivedCallback(string result, GameChatException exception);
public onErrorReceivedCallback onErrorReceived;
//Callback regarding "error" events

Exceptions

The public class for exceptions occurring while using the Game Chat API is as follows.

public class GameChatException
{
    // Detail Error Code
   
    // Unknown error
    public static readonly int CODE_UNKNOWN_ERROR           = 0;
    // Initialization failed
    public static readonly int CODE_NOT_INITALIZE           = 1;
    // Invalid parameter
    public static readonly int CODE_INVAILD_PARAM           = 2;  
    // Errors occurred from the socket server
    public static readonly int CODE_SOCKET_SERVER_ERROR     = 500;
    //Errors occurred from the socket
    public static readonly int CODE_SOCKET_ERROR = -501;
    // Network connection error or timeout occurred
    public static readonly int CODE_SERVER_NETWORK_ERROR    = 4002;
    // Error occurred when parsing data received from the server
    public static readonly int CODE_SERVER_PARSING_ERROR    = 4003;

    // For HTTP errors, the status code is sent as the response code. (400, 403 ...)

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

Client API

Subscribe to channel

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	Unique ID
channel_id	string	Channel ID
user_id	string	Chat user's unique ID
created_at	string	Creation date

Import channel subscription list

Use the following code to import the subscription data of a specific channel in the form of a list.

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

    if(Exception != null)
    {
        // Error handling
        return;
    }

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

Channel

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	Channel ID (unique)
project_id	string	Project ID
unique_id	string	Channel ID that can be set by the developer (unique)
name	string	Channel name
user_id	string	Chat user ID (who created the channel)
created_at	string	Creation date
updated_at	string	Renewal date

Import channel list

Use the following code to import the channel data of a project in the form of a list.

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

    if(Exception != null)
    {
        // Error handling
        return;
    }

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

ID	type	desc
OFFSET	int	Start location of the channel to import from the list of all channels (index)
LIMIT	int	Number of channels to import

Import channel data

Use the following code to import channel data using the channel ID and unique ID.

//Put null in the CHANNEL_UNIQUE_ID parameter if you want to search only by CHANNEL_ID.

//If both the CHANNEL_ID and CHANNEL_UNIQUE_ID values exist, then it searches by prioritizing the CHANNEL_UNIQUE_ID value.

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

    if(Exception != null)
    {
        // Error handling
        return;
    }

    //handling channelInfo instance
});

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

    if(Exception != null)
    {
        // Error handling
        return;
    }

    //handling channelInfo instance
});

ID	type	desc
CHANNEL_ID	string	Channel ID (auto-generated)
CHANNEL_UNIQUE_ID	string	(Unique) channel ID (customization available)

Create and delete channel

You must use an open API to create or delete a new channel within a project. Due to security concerns, we recommend that you use an open API to create and update channels directly from Server to Server. For more information, see the Game Chat API Guide.

Messenger

(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	Message’s unique ID
channel_id	string	Channel ID
message_type	string	Message type
content	string	Content of message (JSON string)
mentions	string	Mention (tag)
created_at		string

Import message list

Use the following code to import the message data of a specific channel in the form of a list.

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

    if(Exception != null)
    {
        // Error handling
        return;
    }

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

ID	type	desc
CHANNEL_ID	string	Channel ID
OFFSET	string	Start location of the message to import from the list of all messages
LIMIT	string	Number of messages to import
SEARCH	string	Message search criterion key. E.g., content.text Perform a full scan when sending empty strings
QUERY	string	Message search value. Only complete matches can be searched. Perform a full scan when sending empty strings
SORT	string	Message sorting order (default: descending order - most recent comes first) (optional: ascending order)

Translate messages

If the automatic translation feature is activated, then arbitrary text can be translated into the specified language. The automatic translation feature can be used after integrating with the Papago Translation service.

(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	Source language code
lang	string	Target language code
translated	bool	Success or failure of translation
message	string	Content of result message (JSON string)

Note

For more information on source language codes and target language codes, see the Papago Text Translation API Guide.

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

    if(Exception != null)
    {
        // Error handling
        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 handling
        return;
    }

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

ID	type	desc
CHANNEL_ID	string	Channel ID
SORCE_LANG	string	Language name of the text to send ("auto": detected automatically) See the API Guide
TARTGET_LANG	string	Language code of the text (to receive the translation) (Multiple entries allowed with "," E.g., "en, fr, th") See the Papago Text Translation API Guide
TEXT	string	Text to send

Chat user

(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	Chat user's unique ID
project_id	string	Game Chat project ID that logged in
nickname	string	Chat user's nickname
profile_url	string	Profile image URL
country	string	Country connected
remoteip	string	Connection IP
adid	string	Advertisement identifier
device	string	Connected device's environment
network	string	Connected network's type (Cellular, Wi-Fi)
version	string	Version of the app connected
model	string	Connected device's model
logined_at	string	Login date
created_at	string	Chat user creation date
updated_at	string	Chat user information renewed date

Chat user information update

You can update the user information of a chat server.

// Chat user nickname update
// The strings allowed for nicknames are 2 to 128 characters in length, excluding whitespaces (spaces, tabs, and line breaks).
GameChat.setName(MEMBER_ID, NAME, (Member member, GameChatException Exception) => {

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

//Chat user profile image URL update
GameChat.setProfileUrl(MEMBER_ID, PROFILE_URL, (Member member, GameChatException Exception) => {

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

ID	type	desc
MEMBER_ID	string	Chat user's unique ID
NAME	string	Chat user's nickname or name
PROFILE	string	Profile image URL

GameChatExtension (Emoji, HyperLink)

This helper class facilitates easy handling of emojis and hyperlink text included in the received message.

• Since TMP_GameChatTextUGUI is an extension class of TextMeshPro, a built-in asset of Unity, you must use first use Package Manager to install TextMeshPro.

• The TextMeshPro asset is included as a built-in asset from Unity 2018.2 or later.

• The default output of emoji sprite sheets is available from Emoji v13.0 (Android). You can change and customize the sprite sheet.

namespace GameChatUnity.Extension
{
    public class TMP_GameChatTextUGUI : TextMeshProUGUI
    {
        public bool isHyperLinked { get; set; }    // Whether to process link-type addresses as hyperlinks (append html tag)
        public string LinkTextColor { get; set; }  // hyperlink text color
    }
}

<Example>

using GameChatUnity.Extension;

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

//Insert text through setMessage for hyperlink recognition and processing.
message.setMessage(MESSAGE_CONTENT);
message.color = Color.green;
message.isHyperLinked = true;

...

msgObject = Instantiate(msgObject) as GameObject;

...

// Manually implement the click event listener for hyperlinks.

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

...