Unity SDK

以下介绍Game Chat Unity SDK的使用方法。

配置要求

使用Game Chat Unity SDK时的配置要求如下。

• 最低配置：2018.4.0以上 （如需获得低版本Unity的支持，请在 '[email protected]' 进行咨询。 )

• 2019.4.X/2020.3.X/2021.1.X版本的Unity编辑器用户请使用2019.4.29f1以上/2020.3.15f2以上/2021.1.16f1以上版本（构建AAB版本时存在的Unity编辑器漏洞被修复的版本）。

验证

重置Game Chat实例

如需使用Game Chat项目ID重置Game Chat实例，请使用下列代码：

GameChat.initialize(PROJECT_ID);

// 使用新加坡区域时
GameChat.setRegion("sg");
GameChat.initialize(PROJECT_ID);

ID	type	desc
PROJECT_ID	string	项目ID

连接Game Chat Socket服务器

连接Game Chat Socket服务器的方法如下：

1. 使用聊天用户ID访问Game Chat Socket服务器。

   • Game Chat项目中，聊天用户ID是唯一值。

2. 获取使用API所需的Token值。

   • 可查看GameChat.connect之后更新的Token值。

3. 获取Token值后确认当前访问设备的聊天用户信息是否已更新。

   • 通过回调GameChat.connect获取的会员信息为更新后的数据。

如需连接Game Chat Socket服务器，请使用下列代码：

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

    if(Exception != null)
    {
        // 错误处理
        return;
    }
});

ID	type	desc
USER_ID	string	聊天用户唯一ID

断开Game Chat服务器连接

如需断开与Game Chat Socket服务器的连接，请使用下列代码：

GameChat.disconnect();

更新聊天用户信息

连接成功后，如需保存并更新聊天用户信息，请使用下列代码。

修改昵称

GameChat.setNickname(USER_ID, NickName, (member, exception) =>
{
    if (exception != null)
    {
        // 错误处理
        return;
    }
    
});

ID	type	desc
USER_ID	string	聊天用户唯一ID
NickName	string	聊天用户昵称

修改简介URL

GameChat.setProfileUrl(USER_ID, ProfileUrl, (member, exception) =>
{
    if (exception != null)
    {
        // 错误处理
        return;
    }
    
});

ID	type	desc
USER_ID	string	聊天用户唯一ID
ProfileUrl	string	聊天用户ProfileURL

订阅和取消订阅频道

如需订阅或取消订阅特定频道，请使用下列代码：

GameChat.subscribe(CHANNEL_ID);

GameChat.unsubscribe(CHANNEL_ID);

ID	type	desc
CHANNEL_ID	string	频道ID

发送消息

如需向特定频道发送消息，请使用下列代码：

GameChat.sendMessage(CHANNEL_ID, MESSAGE);

ID	type	desc
CHANNEL_ID	string	频道ID
MESSAGE	string	发送的消息文本

在消息参数中输入@[玩家ID]空格[消息内容]时

@user_id消息正文

在上述用例中，如果玩家ID已有登录历史，消息详细信息中提及的信息即为玩家ID。

添加和解除事件

如需对从Game Chat Socket服务器接收的事件添加或解除自定义处理，请使用下列代码：

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

public delegate void onConnectedCallback(string data);
public onConnectedCallback onConnected;
对//“connect”事件的回调

public delegate void onDisconnectedCallback(string reason);
public onDisconnectedCallback onDisconnected;
对//“disconnect”事件的回调

public delegate void onMessageReceivedCallback(Message message);
public onMessageReceivedCallback onMessageReceived;
对//“message”事件的回调

public delegate void onUserAddedCallback(UserInfo userinfo);
public onUserAddedCallback onUserAdded;
对//“userAdded”事件的回调

public delegate void onUserRemovedCallback(Message message);
public onUserRemovedCallback onUserRemoved;
对//“userRemoved”事件的回调

public delegate void onErrorReceivedCallback(string result, GameChatException exception);
public onErrorReceivedCallback onErrorReceived;
对//“error”事件的回调

例外情形

下面是对使用Game Chat API过程中发生的例外情况采取的通用处理Class。

public class GameChatException
{
    // Detail Error Code
   
    // 未知错误
    public static readonly int CODE_UNKNOWN_ERROR           = 0;
    // 初始化失败
    public static readonly int CODE_NOT_INITALIZE           = 1;
    // 参数不正确时
    public static readonly int CODE_INVAILD_PARAM           = 2;  
    // Socket服务器发生错误
    public static readonly int CODE_SOCKET_SERVER_ERROR     = 500;
    // Socket发生错误
    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	唯一ID
channel_id	string	频道ID
user_id	string	聊天用户唯一ID
created_at	string	创建日期

导入频道订阅列表

如需以列表形式导入特定频道的订阅数据，请使用下列代码：

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

    if(Exception != null)
    {
        // 错误处理
        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	频道ID（唯一值）
project_id	string	项目ID
unique_id	string	开发公司可设置的频道ID（唯一值）
name	string	频道名称
user_id	string	（创建频道的）聊天用户ID
created_at	string	创建日期
updated_at	string	更新日期

导入频道列表

如需以列表形式导入项目的频道数据，请使用下列代码：

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

    if(Exception != null)
    {
        // 错误处理
        return;
    }

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

ID	type	desc
OFFSET	int	拟从全部频道列表导入的频道的开始位置（索引）
LIMIT	int	拟导入的频道数量

导入频道数据

如需使用频道ID和唯一ID导入频道数据，请使用下列代码：

仅使用//CHANNEL_ID搜索时，在CHANNEL_UNIQUE_ID参数中输入null。

//CHANNEL_ID和CHANNEL_UNIQUE_ID值同时存在时，优先搜索CHANNEL_UNIQUE_ID值。

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

    if(Exception != null)
    {
        // 错误处理
        return;
    }

    //handling channelInfo instance
});

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

    if(Exception != null)
    {
        // 错误处理
        return;
    }

    //handling channelInfo instance
});

ID	type	desc
CHANNEL_ID	string	频道ID（自动生成）
CHANNEL_UNIQUE_ID	string	频道（唯一）ID（可自定义）

创建和删除频道

如需在项目内创建和删除新的频道，应使用Open API。 考虑到安全问题，建议使用Open API通过Server to Server手动进行频道创建和更新等操作。 详细内容请参考Game Chat API指南。

消息

(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	消息的唯一ID
channel_id	string	频道ID
message_type	string	消息类型
content	string	消息内容（JSON字符串）
mentions	string	提及（标签）
created_at		string

导入消息列表

如需以列表形式导入特定频道的消息数据，请使用下列代码：

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

    if(Exception != null)
    {
        // 错误处理
        return;
    }

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

ID	type	desc
CHANNEL_ID	string	频道ID
OFFSET	string	拟从全部消息列表导入的消息的开始位置
LIMIT	string	拟导入的消息数量
SEARCH	string	消息搜索基准参数； <示例> content.text 传递空字符串时，全数扫描
QUERY	string	消息搜索值； 只能搜索完全一致的内容。 传递空字符串时，全数扫描
SORT	string	消息排列顺序（默认：降序 - 按最新排列）（可选项：升序）

翻译消息

自动翻译功能被激活的状态下，可将任意文本翻译成指定语言。 关联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字符串）

参考

关于源语言代码和目标语言代码的介绍，请参考Papago Text Translation API指南

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

    if(Exception != null)
    {
        // 错误处理
        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)
    {
        // 错误处理
        return;
    }

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

ID	type	desc
CHANNEL_ID	string	频道ID
SORCE_LANG	string	拟发送的文本语言名称（auto：自动检测） 参考API指南{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	聊天用户唯一ID
project_id	string	已登录的Game Chat项目ID
nickname	string	聊天用户昵称
profile_url	string	头像图片URL
country	string	访问国家
remoteip	string	访问IP
adid	string	广告标识符
device	string	访问设备环境
network	string	访问网络类型（移动数据、Wi-Fi）
version	string	访问的应用版本
model	string	访问设备型号
logined_at	string	登录日期
created_at	string	聊天用户创建日期
updated_at	string	聊天用户信息更新日期

更新聊天用户信息

可更新聊天服务器的用户信息。

// 更新聊天用户昵称
// 昵称可用的字符串长度为2~128个字符，不得包含空白字符（空格、制表符、换行符）。
GameChat.setName(MEMBER_ID, NAME, (Member member, GameChatException Exception) => {

    if(Exception != null)
    {
        // 错误处理
        return;
    }
    //handling updated Member instance
});

//更新聊天用户简介图片URL
GameChat.setProfileUrl(MEMBER_ID, PROFILE_URL, (Member member, GameChatException Exception) => {

    if(Exception != null)
    {
        // 错误处理
        return;
    }
    //handling updated Member instance
});

ID	type	desc
MEMBER_ID	string	聊天用户唯一ID
NAME	string	聊天用户昵称或姓名
PROFILE	string	头像图片URL

GameChatExtension (Emoji, HyperLink)

帮助开发人员轻松处理所接收消息中包含的表情符号和超链接文本的辅助类。

• TMP_GameChatTextUGUI是对Unity内置资源TextMeshPro进行扩展的类，因此须先使用Package Manager安装TextMeshPro。

• TextMeshPro资源在Unity 2018.2以上版本中以内置资源形式提供。

• 表情符号的精灵表单默认以Emoji 13版本（Android）为基准进行输出，可通过更改精灵表单进行自定义设置。

namespace GameChatUnity.Extension
{
    public class TMP_GameChatTextUGUI : TextMeshProUGUI
    {
        public bool isHyperLinked { get; set; }   // 是否对链接形式的地址进行超链接处理（添加HTML标签）
        public string LinkTextColor { get; set; }  // hyperlink text color
    }
}

<示例>

using GameChatUnity.Extension;

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

//为了识别并处理超链接，需使用setMessage输入文本。
message.setMessage(MESSAGE_CONTENT);
message.color = Color.green;
message.isHyperLinked = true;

...

msgObject = Instantiate(msgObject) as GameObject;

...

// 对于超链接的click event listener需直接构建。

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

...