IMLib SDK for Unity3D 开发指南

    下载 SDK

    下载融云 Unity3D SDK

    创建项目及导入 SDK

    参照下图路径,将下载的融云 SDK 导入到自已的项目中 RongCloud.unitypackage 如图:

    image

    导入中,选择里面所有的文件:

    image

    iOS 项目设置

    生成 iOS 项目,在生成的 Xcode 项目里需要单独添加一下 libsqliteCoreTelephony.framework 如图:

    image
    注:iOS 10 下相关权限问题,请参考适配 iOS 10 的注意事项。 HTTPS 相关设置请参考 ATS 设置说明

    Android 项目设置

    导入 SDK 后,在 Plugins/Android/ 目录下,可以看到 AndroidManifest :

    image

    如果您需要新写 Activity ,请注意上图红框中的包名要保持一致,以保证推送消息的正确接收。并且需要 import io.rong.imlib.JniHelper ; 同时在 onCreate 中加入以下代码:

    JniHelper.init(this);
    

    网络事件监听配置:

    <receiver android:name="io.rong.imlib.NetworkDealer$NetworkStatusReceiver">
        <intent-filter>
            <action android:name="android.net.conn.CONNECTIVITY_CHANGE" />
        </intent-filter>
    </receiver>
    

    推送事件接收器配置(可选,如果您不需要此功能时可删除):

    <receiver
        android:name="io.rong.push.notification.PushMessageReceiver"
        android:permission="rong.permission.push.com.rong.app">
        <intent-filter>
            <action android:name="io.rong.push.intent.action.message" />
        </intent-filter>
    </receiver>
    
    <service
        android:name="io.rong.push.PushService"
        android:process="io.rong.push">
        <intent-filter>
            <category android:name="android.intent.category.DEFAULT" />
            <action android:name="io.rong.push" />
        </intent-filter>
    </service>
    
    <receiver
        android:name="io.rong.push.PushReceiver"
        android:process="io.rong.push">
        <intent-filter>
            <action android:name="io.rong.push.intent.action.HeartBeat" />
        </intent-filter>
        <intent-filter>
            <action android:name="android.net.conn.CONNECTIVITY_CHANGE" />
        </intent-filter>
        <intent-filter>
            <action android:name="android.intent.action.BOOT_COMPLETED" />
        </intent-filter>
        <intent-filter>
            <action android:name="android.intent.action.USER_PRESENT"/>
            <action android:name="android.intent.action.ACTION_POWER_CONNECTED"/>
            <action android:name="android.intent.action.ACTION_POWER_DISCONNECTED"/>
        </intent-filter>
    </receiver>
    

    SDK 所需权限:

    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
    <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
    <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
    <uses-permission android:name="android.permission.RECORD_AUDIO" />
    <uses-permission android:name="android.permission.READ_PHONE_STATE" />
    <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
    

    SDK 接口说明

    SDK 文件目录说明

    • 所有与融云交互的 API 接口都在 RongIMAPI.cs 文件中。
    • Model 文件夹定义了会话和消息的 model ,内置了文本和图片以及语音消息类型。
    • Listener 文件夹定义了监听连接状态接收消息的方法。
    • Callback 文件夹定义了调用 API 接口的各种回调,可以根据 API 接口定义的参数来生成并传入对应的 callback。

    初始化

    初始化 SDK ,传入您从融云开发者后台申请的 Appkey ,初始化方法只需要调用一次:

    RongIMAPI.GetInstance().InitRongCloud(appkey);
    

    连接融云

    连接融云调用 ConnectRongCloud 方法传入从融云获取的用户的 Token 和生成 Token 对应的用户 Id

    RongIMAPI.GetInstance().ConnectRongCloud(token,userId);
    
    TokenuserId 对应的身份标识,详细请参见用户服务

    监听连接状态

    监听连接状态的类需要继承实现 IRCConnectStatusObserver 接口,并把这个类加入监听列表中:

    RCConnectionStatusListener.AddObserver(this);
    

    监听接收消息

    监听接收消息的类需要继承实现 IRCRecivedMessageObserver 接口,并把这个类加入监听列表中:

    RCMessageListener.AddObserver(this);
    

    实例代码

    以下为连接状态监听接收消息监听的代码示例:

    public class Test :MonoBehaviour,IRCConnectStatusObserver,IRCRecivedMessageObserver {
    
        // Use this for initialization
        void Start() {
            RongIMAPI.GetInstance().InitRongCloud(appkey);
            RCConnectionStatusListener.AddObserver(this);
            RCMessageListener.AddObserver(this);
            RongIMAPI.GetInstance().ConnectRongCloud(token,userId);
    
        }
        public void OnConnectStatusChanged(ConnectionStatus status){
            Debug.Log ("----------------"+status);
        }
    
        public void OnRecivedMessage(RCMessage message){
        }
    
        // Update is called once per frame
        void Update() {
    
        }
    }
    

    发送消息

    在私聊频道中发送一条文本消息,示例如下:

    RCTextMessageContent msg = new RCTextMessageContent("veasdf", "asdfasdf");
            RCSendMessageCallback cb = new RCSendMessageCallback();
            cb.onSendSuccessCallback = () => {
                result = string.Format("发送消息成功 targetId = {0}",targetId);
                Debug.Log("RYM cb.sendSuccessCallback");
            };
            cb.onSendFailureCallback = (MessageErrorCode code ) => {
                result = string.Format("发送消息失败 code = {0}",code);
                Debug.Log("RYM cb.onSendFailureCallback");
            };
            RongIMAPI.GetInstance().SendMessage(ConversationType.ConversationType_PRIVATE, targetId, msg,null, null, cb);
    

    对于普通的聊天应用,是有会话概念的,需要显示所有的会话记录。但对于游戏可能就不需要聊天列表,只需要一个世界频道(公共聊天室)、一个公会频道(群组),和私聊频道。游戏需要记住各个会话的类型和 targetId (目标 Id)。

    会话类型 ConversationType

    • 私聊: ConversationType_PRIVATE
    • 讨论组: ConversationType_DISCUSSION
    • 聊天到: ConversationType_CHATROOM
    • 群组: ConversationType_GROUP
    • 公众号: ConversationType_APPSERVICE
    • 系统: ConversationType_SYSTEM

    自定义消息

    SDK 内置的消息类型如不足以满足用户多样的需要,可通过自定义消息的方法来扩展消息,满足用户的各种需求。

    自定义消息,继承 RCMessageContent 类,并实现其以下方法:

    /// 实现此方法,在方法里实现把消息序列化为json字符串
    public abstract string Serialize();
    
    /// 实现此方法,在方法里实现把json字符串解析成对应的消息
    public abstract RCMessageContent Unserialize(string json);
    
    /// 返回消息的objectname(消息是靠这个字段来区分类型)
    public abstract string GetObjectName();
    
    /// 返回消息的属性(这个属性代表消息的特性,是否存储,是否计数,是否状态消息。。)
    public abstract MessagePsersistent GetPersistentFlag();
    

    自定义消息示例

    using System;
    using System.Runtime.Serialization.Formatters;
    using System.Runtime.Serialization;
    using UnityEngine;
    using RCloud;
    
    public class SimpleMessage : RCMessageContent
    {
        private string m_test;
    
        public String Test
        {
            get { return m_test; }
            set { m_test = value; }
        }
    
        public SimpleMessage()
        {
        }
    
        public SimpleMessage(string content)
        {
            m_test = content;
        }
    
        public override string Serialize()
        {
            RCJSONClass jsonClass = new RCJSONClass();
            jsonClass.Add("Test", new RCJSONData(m_test));
            string json = jsonClass.ToJSON();
            Debug.Log("SimpleMessage Serialize = " + json);
            return json;
        }
    
        public override RCMessageContent Unserialize(string json)
        {
            Debug.Log("SimpleMessage Serialize = " + json);
            RCJSONClass jsonClass = RCJSON.Parse(json).AsObject;
            SimpleMessage msg = new SimpleMessage(jsonClass["Test"]);
            return msg;
        }
    
        public override string GetObjectName()
        {
            return "XX:Test";
        }
        //消息特性,不存储不计数
        public override MessagePsersistent GetPersistentFlag()
        {
            return MessagePsersistent.MessagePersistent_NONE;
        }
    }
    

    注册自定义消息

    自定义消息需要在 initRongCloud 之后注册,示例代码如下:

    RongIMAPI.GetInstance().RegisterMessageContent(new SimpleMessage());
    

    接收消息

    收到消息之后 SDK 会回调注册的监听接收消息的代理,触发代理中实现的 IRCRecivedMessageObserver 接口的 OnRecivedMessage 方法。

    如果收到消息是 SDK 内置的消息类型或者是您已经注册的自定义类型的消息会返回的 message 中的 content 就是对应的消息实体,如果是未注册的类型 content 会返回 RCUnknownMessageContent