快速实现消息发送和接收

本文介绍如何使用声网 SDK 快速实现云信令。

消息发送与接收流程

登录 RTM 系统

登录 RTM 系统包括以下流程：

1. 客户端向你的业务服务器请求 Token。
2. 你的业务服务器返回 Token。
3. 客户端使用获得的 Token 登录 RTM。

发送和接收点对点消息

发送和接收点对点消息包括以下流程：

1. 客户端 A 发送点对点消息到 RTM 服务器。
2. RTM 服务器将消息发送到客户端 B。客户端 B 收到点对点消息。

发送和接收频道消息

发送和接收频道消息包括以下流程：

1. 客户端 A 创建并加入频道。
2. 客户端 B 和 C 均加入同一个频道。
3. 客户端 A 创建消息实例并调用频道消息发送方法发送到 RTM 服务器。
4. RTM 服务器发送频道消息给客户端 B 和 C。客户端 B 和 C 收到频道消息。

前提条件

• Unity 2017 或更高版本。
• Android、iOS、Windows、macOS 设备或模拟器。
• 有效的声网开发者账号。
• 如果你的网络环境部署了防火墙，请根据应用企业防火墙限制打开相关端口。

操作步骤

1. 创建声网项目

参考以下步骤创建一个声网项目：

1. 进入声网控制台的项目管理页面。
2. 在项目管理页面，点击创建按钮。
3. 在弹出的对话框内输入项目名称、使用场景，依次选择场景标签和鉴权机制。其中鉴权机制推荐选择安全模式，调试模式的安全性较低。
4. 点击提交按钮。新建的项目会显示在项目管理页中。

2. 获取 App ID

声网会给每个项目自动分配一个 App ID 作为项目唯一标识。

在声网控制台的项目管理页面，找到你的项目，点击 App ID 右侧的 图标，即可获取项目的 App ID。

3. 获取 App 证书

参考以下步骤获取 App 证书：

1. 在声网控制台的项目管理页面，找到你的项目，点击配置。
   

2. 点击主要证书下面的复制图标，即可获取项目的 App 证书。
   

4. 生成 Token

为提高项目的安全性，声网推荐使用 Token 对即将登录 RTM 系统的用户进行鉴权。

为了方便测试，声网服务器提供部署签发 RTM Token 的功能。参考以下步骤获取 RTM Token：

1. 访问 Token-Builder。
2. 输入 App ID、App 证书和用于登录 RTM 系统的用户 ID，其中用户 ID 需要你自行设置，例如 test。输入后，生成的 RTM Token 会直接显示在界面上，选中复制即可。后续调用 login 时，请确保填入的用户 ID 与生成 RTM Token 时填入的用户 ID 一致。

5. 创建 Unity 项目

1. 在 Unity 中选择 File > New Project。
2. 选择 2D 作为模板。设置项目名称和位置，点击创建。创建完成后，Unity 会显示项目编辑界面。

6. 集成 SDK

方法一：导入资源包

1. 前往 GitHub 下载最新版本的声网 RTM Unity 资源包。
2. 在 Unity Editor 中，选择 Assets > Import Package > Custom Package。
3. 选择声网 RTM Unity 资源包，点击打开。
4. 取消勾选不需要的插件（默认勾选 SDK 包含的所有插件）。然后点击 Import。
   

方法二：手动复制 SDK 文件

1. 前往 SDK 下载页面，在云信令 (原 RTM) SDK 中下载最新版本的声网 RTM SDK，然后解压。

2. 将 SDK 包内 libs 下的 Rtm-Scripts 文件夹拷贝到项目路径的 Assets 文件夹下。

3. 将 SDK 包内 libs/Plugins 路径下的如下文件，拷贝到项目的对应路径下：

   开发平台	文件或文件夹	项目路径
   Android	Plugins/Android	/Assets/Plugins/Android/
   iOS	Plugins/iOS	/Assets/Plugins/iOS
   macOS	Plugins/macOS	/Assets/Plugins/macOS
   Windows	Plugins/x86	/Assets/Plugins/x86
   Windows	Plugins/x86_64	/Assets/Plugins/x86_64

7. 创建用户界面

在 Unity 中创建以下用户界面元素：

Canvas

• Panel : 包含主要操作界面。
  • Text: 标题文字，App ID 字段和 Token 字段。
  • InputField: 发送端和接收端的用户 ID，点对点消息内容，频道名，频道消息内容。
  • Button: 登录，登出，发送点对点消息，加入频道，发送频道消息，离开频道。
• ScrollView: 显示消息记录与状态变更记录。

8. 添加界面脚本

在 scene 中创建一个空的 GameObject，命名为 MessageManager。在 GameObject 中添加两个 script:

• MessageManager.cs: 发送和接收消息的基本逻辑。
• MessageDisplay.cs: 在用户界面上显示消息和状态变更。

MessageManager.cs

using System.Collections.Generic;
using UnityEngine;
using UnityEngine.UI;


using agora_rtm;

namespace io.agora.rtm.quickstart
{
    public class MessageManager : MonoBehaviour
    {


        // 序列化字段，可用于在 Unity Editor 中填入 App ID 和 Token
        [Header("Agora Properties")]
        [SerializeField]
        private string appId = "";
        [SerializeField]
        private string token = "";
        // 序列化字段，可用于在 Unity Editor 中连接 Unity 对象和脚本变量
        [Header("Application Properties")]

        [SerializeField] InputField userNameInput, channelNameInput;
        [SerializeField] InputField channelMsgInputBox;
        [SerializeField] InputField peerUserBox;
        [SerializeField] InputField peerMessageBox;
        [SerializeField] MessageDisplay messageDisplay;


        private RtmClient rtmClient = null;
        private RtmChannel channel;

        private RtmClientEventHandler clientEventHandler;
        private RtmChannelEventHandler channelEventHandler;
        private RtmCallEventHandler callEventHandler;

        string _userName = "";
        string UserName {
            get { return _userName; }
            set {
                _userName = value;
                PlayerPrefs.SetString("RTM_USER", _userName);
                PlayerPrefs.Save();
            }
        }

        string _channelName = "";
        string ChannelName
        {
            get { return _channelName; }
            set {
                _channelName = value;
                PlayerPrefs.SetString("RTM_CHANNEL", _channelName);
                PlayerPrefs.Save();
            }
        }

        agora_rtm.SendMessageOptions _MessageOptions = new agora_rtm.SendMessageOptions() {
                    enableOfflineMessaging = true,
                    enableHistoricalMessaging = true
        };

        private void Awake()
        {
            userNameInput.text = PlayerPrefs.GetString("RTM_USER", "");
            channelNameInput.text = PlayerPrefs.GetString("RTM_CHANNEL", "");


        }

        // 初始化
        void Start()
        {
            clientEventHandler = new RtmClientEventHandler();
            channelEventHandler = new RtmChannelEventHandler();
            callEventHandler = new RtmCallEventHandler();

            rtmClient = new RtmClient(appId, clientEventHandler);
#if UNITY_EDITOR
            rtmClient.SetLogFile("./rtm_log.txt");
#endif

            clientEventHandler.OnQueryPeersOnlineStatusResult = OnQueryPeersOnlineStatusResultHandler;
            clientEventHandler.OnLoginSuccess = OnClientLoginSuccessHandler;
            clientEventHandler.OnLoginFailure = OnClientLoginFailureHandler;
            clientEventHandler.OnMessageReceivedFromPeer = OnMessageReceivedFromPeerHandler;

            channelEventHandler.OnJoinSuccess = OnJoinSuccessHandler;
            channelEventHandler.OnJoinFailure = OnJoinFailureHandler;
            channelEventHandler.OnLeave = OnLeaveHandler;
            channelEventHandler.OnMessageReceived = OnChannelMessageReceivedHandler;

        }

        void OnApplicationQuit()
        {
            if (channel != null)
            {
                channel.Dispose();
                channel = null;
            }
            if (rtmClient != null)
            {
                rtmClient.Dispose();
                rtmClient = null;
            }
        }
        // 登录系统
        public void Login()
        {
            UserName = userNameInput.text;

            if (string.IsNullOrEmpty(UserName) || string.IsNullOrEmpty(appId))
            {
                Debug.LogError("We need a username and appId to login");
                return;
            }

            rtmClient.Login(token, UserName);
        }
        // 登出系统
        public void Logout()
        {
            messageDisplay.AddTextToDisplay(UserName + " logged out of the rtm", Message.MessageType.Info);
            rtmClient.Logout();
        }

        // 加入频道
        public void JoinChannel()
        {
            ChannelName = channelNameInput.GetComponent<InputField>().text;
            channel = rtmClient.CreateChannel(ChannelName, channelEventHandler);
            ShowCurrentChannelName();
            channel.Join();
        }
        // 离开频道
        public void LeaveChannel()
        {
            messageDisplay.AddTextToDisplay(UserName + " left the chat", Message.MessageType.Info);
            channel.Leave();
        }
        // 发送频道消息
        public void SendMessageToChannel()
        {
            string msg = channelMsgInputBox.text;
            string peer = "[channel:" + ChannelName + "]";

            string displayMsg = string.Format("{0}->{1}: {2}", UserName, peer, msg);

            messageDisplay.AddTextToDisplay(displayMsg, Message.MessageType.PlayerMessage);
            channel.SendMessage(rtmClient.CreateMessage(msg));
        }
        // 发送点对点消息
        public void SendPeerMessage()
        {
            string msg = peerMessageBox.text;
            string peer = peerUserBox.text;

            string displayMsg = string.Format("{0}->{1}: {2}", UserName, peer, msg);
            messageDisplay.AddTextToDisplay(displayMsg, Message.MessageType.PlayerMessage);

            rtmClient.SendMessageToPeer(
                peerId: peer,
                message: rtmClient.CreateMessage(msg),
                options: _MessageOptions
           );

            peerMessageBox.text = "";
        }



        void ShowCurrentChannelName()
        {
            ChannelName = channelNameInput.GetComponent<InputField>().text;
            Debug.Log("Channel name is " + ChannelName);
        }


        void OnQueryPeersOnlineStatusResultHandler(int id, long requestId, PeerOnlineStatus[] peersStatus, int peerCount, QUERY_PEERS_ONLINE_STATUS_ERR errorCode)
        {
            if (peersStatus.Length > 0)
            {
                Debug.Log("OnQueryPeersOnlineStatusResultHandler requestId = " + requestId +
                " peersStatus: peerId=" + peersStatus[0].peerId +
                " online=" + peersStatus[0].isOnline +
                " onlinestate=" + peersStatus[0].onlineState);
                messageDisplay.AddTextToDisplay("User " + peersStatus[0].peerId + " online status = " + peersStatus[0].onlineState, Message.MessageType.Info);
            }
        }
        // 加入频道成功回调
        void OnJoinSuccessHandler(int id)
        {
            string msg = "channel:" + ChannelName + " OnJoinSuccess id = " + id;
            Debug.Log(msg);
            messageDisplay.AddTextToDisplay(msg, Message.MessageType.Info);

        }
        // 加入频道失败回调
        void OnJoinFailureHandler(int id, JOIN_CHANNEL_ERR errorCode)
        {
            string msg = "channel OnJoinFailure  id = " + id + " errorCode = " + errorCode;
            Debug.Log(msg);
            messageDisplay.AddTextToDisplay(msg, Message.MessageType.Error);
        }
        // 登录成功回调
        void OnClientLoginSuccessHandler(int id)
        {
            string msg = "client login successful! id = " + id;
            Debug.Log(msg);
            messageDisplay.AddTextToDisplay(msg, Message.MessageType.Info);
        }
        // 登录失败回调
        void OnClientLoginFailureHandler(int id, LOGIN_ERR_CODE errorCode)
        {
            string msg = "client login unsuccessful! id = " + id + " errorCode = " + errorCode;
            Debug.Log(msg);
            messageDisplay.AddTextToDisplay(msg, Message.MessageType.Error);
        }
        // 离开频道回调
        void OnLeaveHandler(int id, LEAVE_CHANNEL_ERR errorCode)
        {
            string msg = "client onleave id = " + id + " errorCode = " + errorCode;
            Debug.Log(msg);
            messageDisplay.AddTextToDisplay(msg, Message.MessageType.Info);
        }
        // 收到频道消息回调
        void OnChannelMessageReceivedHandler(int id, string userId, TextMessage message)
        {
            Debug.Log("client OnChannelMessageReceived id = " + id + ", from user:" + userId + " text:" + message.GetText());
            messageDisplay.AddTextToDisplay(userId + ": " + message.GetText(), Message.MessageType.ChannelMessage);
        }
        // 收到点对点消息回调
        void OnMessageReceivedFromPeerHandler(int id, string peerId, TextMessage message)
        {
            Debug.Log("client OnMessageReceivedFromPeer id = " + id + ", from user:" + peerId + " text:" + message.GetText());
            messageDisplay.AddTextToDisplay(peerId + ": " + message.GetText(), Message.MessageType.PeerMessage);
        }
        // 加入频道回调
        void OnMemberJoinedHandler(int id, RtmChannelMember member)
        {
            string msg = "channel OnMemberJoinedHandler member ID=" + member.GetUserId() + " channelId = " + member.GetChannelId();
            Debug.Log(msg);
            messageDisplay.AddTextToDisplay(msg, Message.MessageType.Info);
        }
        // 离开频道回调
        void OnMemberLeftHandler(int id, RtmChannelMember member)
        {
            string msg = "channel OnMemberLeftHandler member ID=" + member.GetUserId() + " channelId = " + member.GetChannelId();
            Debug.Log(msg);
            messageDisplay.AddTextToDisplay(msg, Message.MessageType.Info);
        }

        // 发送消息结果回调
        void OnSendMessageResultHandler(int id, long messageId, PEER_MESSAGE_ERR_CODE errorCode)
        {
            string msg = string.Format("Sent message with id:{0} MessageId:{1} errorCode:{2}", id, messageId, errorCode);
            Debug.Log(msg);
            messageDisplay.AddTextToDisplay(msg, errorCode == PEER_MESSAGE_ERR_CODE.PEER_MESSAGE_ERR_OK ? Message.MessageType.Info : Message.MessageType.Error);
        }

        // 链接状态变更回调
        void OnConnectionStateChangedHandler(int id, CONNECTION_STATE state, CONNECTION_CHANGE_REASON reason)
        {
            string msg = string.Format("connection state changed id:{0} state:{1} reason:{2}", id, state, reason);
            Debug.Log(msg);
            messageDisplay.AddTextToDisplay(msg, Message.MessageType.Info);
        }
    }

}

MessageDisplay.cs

using System.Collections.Generic;
using UnityEngine;
using UnityEngine.UI;

namespace io.agora.rtm.quickstart
{
    public class MessageDisplay : MonoBehaviour
    {
#pragma warning disable 0649
        [SerializeField] int maxMessages = 25;
        [SerializeField] GameObject chatPanel, textPrefab;
        [SerializeField] MessageColorStruct MessageColors;
        [SerializeField] List<Message> messageList = new List<Message>();
#pragma warning restore 0649

        private void Awake()
        {
        }
        // 将 Text 转化为 prefab 并添加到 ScrollView 的 Content 对象，从而实现文字的逐行显示
        public void AddTextToDisplay(string text, Message.MessageType messageType)
        {
            if (messageList.Count >= maxMessages)
            {
                Destroy(messageList[0].textObj.gameObject);
                messageList.Remove(messageList[0]);
            }

            Message newMessage = new Message();
            newMessage.text = text;

            GameObject newText = Instantiate(textPrefab, chatPanel.transform);
            newMessage.textObj = newText.GetComponent<Text>();
            newMessage.textObj.text = newMessage.text;
            newMessage.textObj.color = MessageTypeColor(messageType);
            messageList.Add(newMessage);
        }


        public void Clear()
        {

            foreach (Message msg in messageList) {
                Destroy(msg.textObj.gameObject);
            }
            messageList.Clear();
        }

        Color MessageTypeColor(Message.MessageType messageType)
        {
            Color color = MessageColors.infoColor;

            switch (messageType)
            {
                case Message.MessageType.PlayerMessage:
                    color = MessageColors.playerColor;
                    break;
                case Message.MessageType.ChannelMessage:
                    color = MessageColors.channelColor;
                    break;
                case Message.MessageType.PeerMessage:
                    color = MessageColors.peerColor;
                    break;
                case Message.MessageType.Error:
                    color = MessageColors.errorColor;
                    break;
            }

            return color;
        }
    }


    [System.Serializable]
    public class Message
    {
        public string text;
        public Text textObj;
        public MessageType messageType;

        public enum MessageType
        {
            Info,
            Error,
            PlayerMessage,
            ChannelMessage,
            PeerMessage
        }
    }

    [System.Serializable]
    public struct MessageColorStruct
    {
        public Color infoColor, errorColor, playerColor, peerColor, channelColor;
    }
}

9. 连接脚本与用户界面元素

1. 根据 MessageManager 中的属性选择相应的用户界面元素和脚本资源。
   • userNameInput ：选择本地用户 ID 的 InputField 对象。
   • channelNameInput ：选择频道名的 InputField 对象。
   • channelMsgInputBox ：选择频道消息的 InputField 对象。
   • peerUserBox ：选择远端用户 ID 的 InputField 对象。
   • peerMessageBox ：选择点对点消息内容的 InputField 对象。
   • messageDisplay ：选择 MessageManager 脚本。
2. 设置 MessageDisplay 对象的属性。
   • chatPanel：选择 ScrollView > Viewport 中的 Content 对象。建议勾选 Vertical Layout Group 和 Content Size Fitter 组件并做相应设置。
   • textPrefab：选择 asset 中的 prefab。你必须先自行创建一个 Text 类型的 prefab。
   • MessageColors：选择不同类型文字的颜色。
3. 设置 Button 的 OnClick 触发逻辑。每个 Button 在点击后都触发脚本中相应的方法。
   • 登录：MessageManager.Login
   • 发送点对点消息： MessageManager.SendPeerMessage
   • 登出： MessageManager.Logout
   • 加入频道：MessageManager.JoinChannel
   • 发送频道消息： MessageManager.SendMessageToChannel
   • 离开频道： MessageManager.LeaveChannel

运行项目

1. 在 MessageManager 对象的 Agora Properties 字段中填入 App ID 和 Token。
2. 点击 File 菜单栏，通过 Build Settings 设置你需要运行的设备。
3. 点击 Unity 主界面上方的 Play 按钮直接运行示例项目，或点击菜单栏 File > Build And Run 编译运行示例项目。你会在设备上看到如下画面。