# Unity SDK

## Requirements <a href="#undefined" id="undefined"></a>

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](https://www.ncloud.com/support/question).)
* 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 <a href="#sdk" id="sdk"></a>

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 <a href="#undefined" id="undefined"></a>

### Reset Game Chat instance <a href="#gamechat" id="gamechat"></a>

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

```csharp
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.

```csharp
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.

```csharp
GameChat.disconnect();
```

### Chat user information update <a href="#undefined" id="undefined"></a>

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

**Edit nickname**

```csharp
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**

```csharp
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.

```csharp
GameChat.subscribe(CHANNEL_ID);

GameChat.unsubscribe(CHANNEL_ID);
```

| ID          | type   | desc       |
| ----------- | ------ | ---------- |
| CHANNEL\_ID | string | Channel ID |

## Send message <a href="#undefined" id="undefined"></a>

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

```csharp
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

```csharp
@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.

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

```csharp
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 <a href="#undefined" id="undefined"></a>

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

```csharp

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 <a href="#undefined" id="undefined"></a>

#### **Subscription Data Class (per Unit)**

```csharp
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.

```csharp
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 <a href="#undefined" id="undefined"></a>

#### **Channel Data Class (per Unit)**

```csharp
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.

```csharp
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.

```csharp
//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
});
```

```csharp
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 <a href="#undefined" id="undefined"></a>

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](https://api.ncloud-docs.com/docs/en/game-gamechat).

### Messenger <a href="#undefined" id="undefined"></a>

#### **(Received) Message Data Class (per Unit)**

```csharp
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.

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

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

#### **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](https://www.ncloud.com/product/aiService/papagoTranslation) service.

**(Received) Translation Data Class (per Unit)**

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

<table><thead><tr><th width="163">ID</th><th width="126">type</th><th>desc</th></tr></thead><tbody><tr><td>detectLang</td><td>string</td><td>Source language code</td></tr><tr><td>lang</td><td>string</td><td>Target language code</td></tr><tr><td>translated</td><td>bool</td><td>Success or failure of translation</td></tr><tr><td>message</td><td>string</td><td>Content of result message (JSON string)</td></tr></tbody></table>

> Note
>
> For more information on source language codes and target language codes, see the [Papago Text Translation API Guide](https://api.ncloud-docs.com/docs/en/ai-naver-papagonmt-translation).

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

<table><thead><tr><th width="195">ID</th><th width="118">type</th><th>desc</th></tr></thead><tbody><tr><td>CHANNEL_ID</td><td>string</td><td>Channel ID</td></tr><tr><td>SORCE_LANG</td><td>string</td><td>Language name of the text to send ("auto": detected automatically)<br>See the <a href="https://api.ncloud-docs.com/docs/en/ai-naver-papagonmt-translation">API Guide</a></td></tr><tr><td>TARTGET_LANG</td><td>string</td><td>Language code of the text (to receive the translation)<br>(Multiple entries allowed with "," E.g., "en, fr, th")<br>See the <a href="https://api.ncloud-docs.com/docs/en/ai-naver-papagonmt-translation">Papago Text Translation API Guide</a></td></tr><tr><td>TEXT</td><td>string</td><td>Text to send</td></tr></tbody></table>

### Chat user

**(Received) Member Data Class (per Unit)**

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

<table><thead><tr><th width="152">ID</th><th width="124">type</th><th>desc</th></tr></thead><tbody><tr><td>id</td><td>string</td><td>Chat user's unique ID</td></tr><tr><td>project_id</td><td>string</td><td>Game Chat project ID that logged in</td></tr><tr><td>nickname</td><td>string</td><td>Chat user's nickname</td></tr><tr><td>profile_url</td><td>string</td><td>Profile image URL</td></tr><tr><td>country</td><td>string</td><td>Country connected</td></tr><tr><td>remoteip</td><td>string</td><td>Connection IP</td></tr><tr><td>adid</td><td>string</td><td>Advertisement identifier</td></tr><tr><td>device</td><td>string</td><td>Connected device's environment</td></tr><tr><td>network</td><td>string</td><td>Connected network's type (Cellular, Wi-Fi)</td></tr><tr><td>version</td><td>string</td><td>Version of the app connected</td></tr><tr><td>model</td><td>string</td><td>Connected device's model</td></tr><tr><td>logined_at</td><td>string</td><td>Login date</td></tr><tr><td>created_at</td><td>string</td><td>Chat user creation date</td></tr><tr><td>updated_at</td><td>string</td><td>Chat user information renewed date</td></tr></tbody></table>

#### **Chat user information update**

You can update the user information of a chat server.

```csharp

// 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.

```csharp
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>**

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

...
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.gamechat.me/basics/game-chat-v2/game-chat-english/getting-started-with-game-chat/unity-sdk.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.