Web SDK 开发指南

    特性介绍

    融云 Web IM SDK 版本在很多方面都进行了提升,下面从几个方面描述一下 SDK 的产品特性:

    轻巧稳定:

    • SDK 采用 TypeScript 语言开发,结构清晰、健壮
    • 即时通讯库尺寸小,只有 120 KB 左右
    • 扩展功能按需加载,支持声音播放Emoji 表情库

    功能丰富:

    • 支持多页面连接(需付费开通,开发环境免费开通
    • 支持会话列表漫游
    • 支持聊天历史记录漫游(需付费开通,开发环境免费开通

    兼容性:

    • 兼容各种环境:IE6 - IE11, Chrome, Firefox, Safari, Edge, QQ 浏览器, 微信浏览器, Electron, Android 浏览器 2.3.6 及以上
    • 支持两种连接:WebSocket 和 HTTP Long Polling
    • 支持 AMD, CMD

    扩展性:

    • 支持自定义消息
    • 支持自定义表情
    • 支持自定义存储方式

    提供开源的聊天界面:

    image
    image

    注册开发者帐号

    请前往融云官方网站注册开发者帐号。注册时需要提供真实的邮箱和手机号,以便接收重要通知。如果没有提供正确可用的邮箱和手机号,融云随时可能关闭应用。

    首先,开始创建第一个应用吧!

    创建应用

    注册后登录开发者后台即可创建应用。创建应用后才可进行 Web IM 集成开发

    每个应用都提供了生产环境和开发环境,两个环境的功能完全一致、数据完全隔离,分别有自己的 App Key / Secret,App Key / Secret是融云 SDK 连接服务器所必须的标识,请不要外泄。

    应用最终上线前,使用开发环境进行开发测试,上线申请通过后可获取生产环境的 App Key / Secret,替换后即可发布上线。

    image

    引入 SDK

    <script src="http(s)://cdn.ronghub.com/RongIMLib-2.2.6.min.js"></script>
    也可将 SDK 下载到本地使用,请不要做任何修改。

    Web SDK 源码,可了解具体实现逻辑,可查询错误代码信息
    使用 RequireJS 加载 SDK 示例
    引用本地 SDK 示例
    Web SDK 常用 API 调用示例

    编写代码

    获取 Token

    获取用户 Token 请参考 Server 开发指南用户服务

    userId 是用户在融云系统中唯一的身份 Id,可为任意数字或字符串,但必须保证全局唯一。

    name 是用户的显示名称,用在 Push 推送时显示用户的名称。

    portraitUri 是用户头像地址

    返回的 Token 格式为 mKmyKqTSf7aNDinwAFMnz7NXKILeV3X0+CCRBOxmtOApmvQjMathViWrePIfq0GuTu9jELQqsckv4AhfjCAKgQ==

    为了方便测试开发,开发者后台提供了 API 调试工具,可直接生成 Token。

    image

    连接融云服务器、设置消息监听

    1、默认只支持一个页面连接,一个页面里只能 init 一次,开通“多设备消息同步”即可支持多页面连接

    2、使用 AppKey 和 Token 开始初始化并连接服务器,通过消息监听 setOnReceiveMessageListener 接收所有类型新消息 示例代码

    3、SDK 目前没有自动重连机制,但提供了断开连接及重连方法 调用示例

    4、只有链接成功之后才可进行收发消息、获取会话列表等操作。

    发送消息

    发送消息必须在成功连接融云服务器之后进行,发送频率上限每秒最多 5 条、每分钟最多 6000 条。

    融云支持向单聊、群组及聊天室中发送文字消息、图片消息、语音消息、文件消息、地理位置消息以及自定义消息。

     // 发送消息相关参数说明
    var conversationtype = RongIMLib.ConversationType.PRIVATE;
     /*
     PRIVATE 为单聊、
     DISCUSSION 为讨论组、
     GROUP 为群组、
     CHATROOM 为聊天室、
     CUSTOMER_SERVICE 为客服、
     SYSTEM 为系统消息、
     APP_PUBLIC_SERVICE 为应用公众账号(应用内私有)、
     PUBLIC_SERVICE 为公众账号 (公有)
     */
    
     var targetId = "xxx"; // 目标 Id,根据不同的 ConversationType,可能是用户 Id、讨论组 Id、群组 Id。
    

    检测未读消息

    此方法用来查询当前传入 Token(表示一个用户)是否有未读的消息,只返回布尔值结果,不返回具体未读数,必须在执行初始化 SDK 方法 init 之后,连接融云服务器 connect 之前进行。

    //此接口必须在init()方法之后,连接融云服务器 connect 之前调用。
    RongIMClient.getInstance().hasRemoteUnreadMessages(token,{
        onSuccess:function(hasMessage){
            if(hasMessage){
                // 有未读的消息
            }else{
                // 没有未读的消息
            }
        },onError:function(err){
            // 错误处理...
        }
    });
    

    获取会话列表

    Web SDK 提供 getConversationList 来获取会话列表,此方法必须在执行初始化 SDK 方法 init 及连接融云服务器 connect 成功之后进行。

    在使用 getConversationList 方法前必须开通 单群聊消息云存储 功能。 此功能为付费功能, 开发环境下可免费使用,登录开发者后台,进入付费功能 -> 单群聊消息云存储中,即可开启使用。
     //请确保单群聊消息云存储服务开通,且开通后有过收发消息记录
     RongIMClient.getInstance().getConversationList({
        onSuccess: function(list) {
          console.log(list);
        },
        onError: function(error) {
           // do something...
        }
      },null);
    
      /*
      数据格式及使用说明:
      1:除了会话基本消息,每个会话会返回最新一条消息 latestMessage
      2:会话只返回发送者id=latestMessage.senderUserId,发送者信息需要从应用服务器获取
      3:因为性能原因不建议从服务器实时更新会话列表,建议开发者在本地维护会话列表和最新消息
      */
      {
        "conversationTitle": "",
        "conversationType": 2,
        "latestMessage": {
          "content": {},
          "conversationType": 2,
          "objectName": "RC:DizNtf",
          "messageDirection": 1,
          "messageId": "2_8894894",
          "receivedStatus": 1,
          "receivedTime": 1499242237476,
          "senderUserId": "user10",
          "sentTime": 1499238335281,
          "targetId": "9e6ea82e-caa1-467b-8ee5-02a9c2460196",
          "messageType": "DiscussionNotificationMessage",
          "messageUId": "5EH3-4C36-4BOC-FRFG",
          "offLineMessage": true
        },
        "latestMessageId": "2_8894894",
        "notificationStatus": 0,
        "objectName": "RC:DizNtf",
        "receivedStatus": 1,
        "sentTime": 1499238335281,
        "targetId": "9e6ea82e-caa1-467b-8ee5-02a9c2460196",
        "unreadMessageCount": 0
      }
    

    获取历史消息

    通过 getHistoryMessages 来帮助开发者获取历史消息纪录。此方法必须在执行初始化 SDK 方法 init 及连接融云服务器 connect 成功之后进行。

    在使用 getHistoryMessages 方法前必须开通 单群聊消息云存储 功能。 此功能为付费功能, 开发环境下可免费使用,登录开发者后台,进入付费功能 -> 单群聊消息云存储中,即可开启使用。

    单群聊消息云存储不支持聊天室消息云存储,拉取历史消息最多一次行拉取 20 条消息。拉取顺序按时间倒序拉取。

    拉取历史消息支持循环拉取(只有当 timestrap = null 时),具体逻辑:

    条件:历史记录为 45 条,每次拉取 20 条。
    第一次拉取 list 长度为 20,hasMsg 为 true。
    第二次拉取 list 长度为 20,hasMsg 为 true。
    第三次拉取 list 长度为 5,hasMsg 为 false。
    第四次拉取 list 长度为 0,hasMsg 为 false。
    第四次拉取:重复第一次拉取,以此循环

    //请确保单群聊消息云存储服务开通,且开通后有过收发消息记录
     RongIMClient.getInstance().getHistoryMessages(RongIMLib.ConversationType.PRIVATE, targetId, timestrap, count, {
        onSuccess: function(list, hasMsg) {
          // hasMsg为boolean值,如果为true则表示还有剩余历史消息可拉取,为false的话表示没有剩余历史消息可供拉取。
            // list 为拉取到的历史消息列表
        },
        onError: function(error) {
            // APP未开启消息漫游或处理异常
                // throw new ERROR ......
        }
      });
    

    表情库

    表情库引用地址

    获取官方 Emoji (目前版本为 2.2.5 ) 地址加入到自己页面中,如下:
    <script src="http(s)://cdn.ronghub.com/RongEmoji-2.2.5.min.js"></script>

    表情库使用方法

    1. 默认支持 128 个 Emoji 表情并且支持自定义扩展 Emoji
    2. 初始化后可调用 API 实现所需各种转化
    3. SDK 使用的图标仅为示例,正式产品里使用时请自行解决版权问题并替换

    1、初始化 Emoji

    //直接初始化
    RongIMLib.RongIMEmoji.init();
    
    //通过配置扩展表情初始化,可参考 http://unicode.org/emoji/charts/full-emoji-list.html
    var newEmojis = {
      dataSource: {
        "表情unicode码":{
          "en":"英文名称",
          "zh":"中文名称",
          "tag":"原生表情字符",
          "bp":"多背景图时表情对应的坐标"
        },
      },
      url: "背景图片地址"
    };
    RongIMLib.RongIMEmoji.init(newEmojis);
    

    2、获取全部表情

    var emojis = RongIMLib.RongIMEmoji.emojis;
    // emojis[0].innerHTML => <span class="RongIMExpression_grinning" name="[大笑]"> 表情字符 </span>
    // emojis[0].children[0].getAttribute("name") => "[大笑]"
    

    3、Emoji 转名称

    在不支持原生 Emoji 渲染时,可显示对应名称,适用于消息输入

    var message = "😀😁测试 Emoji";
    message = RongIMLib.RongIMEmoji.emojiToSymbol(message);
    // message => "[大笑][露齿而笑]测试Emoji"
    

    4、名称转 Emoji

    发送消息时,消息体里必须使用原生 Emoji 字符

    var message = "[大笑][露齿而笑]测试Emoji";
    message = RongIMLib.RongIMEmoji.symbolToEmoji(message);
    //message => "😀😁测试Emoji"
    //sendMessage(conversationtype, targetId, message, callbacks);
    

    5、Emoji 转 HTML

    Web SDK 接收消息后,消息体内的原生 Emoji 字符会被解码为对应的 unicode 码(格式如下),需转化才能正确显示

    var message = "\uf600\uf601测试Emoji";
    RongIMLib.RongIMEmoji.emojiToHTML(message);
    

    6、名称转 HTML

    var message = "[露齿而笑]测试 Emoji";
    RongIMLib.RongIMEmoji.symbolToHTML(message);
    

    7、支持 ADM、CMD

    声音库

    声音基本信息

    1、IE 内核自动使用 Flash 播放。

    2、Chrome、FireFox 等高级浏览器使用 Audio 标签播放。

    3、iOS Safari 、iOS 微信浏览器 、Android Chrome 浏览器、Android 微信浏览器 。

    4、声音库支持 AMD、CMD

    声音库使用方法

    <script src="http(s)://cdn.ronghub.com/Libamr-2.2.5.min.js"></script>
    <script src="http(s)://cdn.ronghub.com/RongIMVoice-2.2.5.min.js"></script>
    <script>
    /*
    初始化声音库
    在 RongIMClient.init之后,全局只init一次
    */
    RongIMLib.RongIMVoice.init();
    
    /*
    定义音频文件,base64码,AMR格式
    
    实际项目中,文档:http://www.rongcloud.cn/docs/api/js/VoiceMessage.html
    
    var audioFile = VoiceMessage.content.content;
    var duration = VoiceMessage.content.duration;
    */
    var audioFile = "IyFBTVIKLNEafAAeef/hgmeAH8AD...";
    var duration = audioFile.length/1024;
    
    
    //预加载 + 播放
    RongIMLib.RongIMVoice.preLoaded(audioFile, function(){
        // 播放声音
        RongIMLib.RongIMVoice.play(audioFile,duration);
    });
    
    //停止播放
    RongIMLib.RongIMVoice.stop(audioFile);
    </script>
    
    注:以上代码示例中 audioFile 的值为部份示意数据,完整数据请查看 base64 编码的 AMR 音频数据文件,该文件仅用于测试使用。

    聊天插件

    聊天插件是 Web IM SDK 的特色功能,通过简单几行代码,即可直接集成,节省大量的开发调试时间。目前提供 AngularJS 版本插件。

    1、下载并引用插件资源

    融云官方网站下载插件包放在自己项目目录中,在页面中引入以下资源:

    <script type="text/javascript" src="{资源目录}/RongIMWidget.js"></script>
    <link rel="stylesheet" type="text/css" href="{资源目录}/css/RongIMWidget.css"/>
    <rong-widget></rong-widget>
    

    2、初始化

    var demo = angular.module("demo", ["RongWebIMWidget"]);
    demo.controller("main", ["$scope", "WebIMWidget", function($scope,WebIMWidget) {
        WebIMWidget.init({
          appkey:"bmdehs6pd",
          token:"****",
          onSuccess:function(){
            //初始化完成
          },
          onError:function(){
            //初始化错误
          }
        });
    }]);
    

    3、插件样式设置

    设置界面样式

    通过 init 方法中的 style 参数设置显示位置,如下:

    WebIMWidget.init({
      appkey:"bmdehs6pdw0ss",
      token:"****",
      style:{
        width:500,
        height:600,
        bottom:0,
        left:0
      }
    });
    

    style 中参数说明:

    • 通过 topleftbottomright 设置界面显示位置。
    • 通过 positionFixed 是否固定在页面显示,true 为固定,false 为不固定,默认 false
    • 通过 widthheight 设置对话框显示大小。

    设置显示会话列表

    通过 displayConversationList 设置是否显示会话列表,true 为显示,false 为不显示,默认为 false

    WebIMWidget.init({
      appkey:"bmdehs6pdw0ss",
      token:"****",
      displayConversationList:true
    });
    

    设置会话列表显示位置

    通过 conversationListPosition 设置会话列表位置,会话列表在对话框左边或右边。(注: displayConversationListtrue 时才有效),如下:

    WebIMWidget.init({
      appkey:"bmdehs6pdw0ss",
      token:"****",
      displayConversationList:true,
      conversationListPosition:WebIMWidget.EnumConversationListPosition.left
    });
    

    最小化时显示状态

    displayMinButton 最小化时是否显示最小化按钮,true 为显示,false 为不显示,默认为 true (注:displayConversationListtrue 时才有效)。

    WebIMWidget.init({
      appkey:"bmdehs6pdw0ss",
      token:"****",
      displayConversationList:true,
      displayMinButton:false
    });
    

    4、设置当前会话

    通过 setConversation 设置当前会话对象,setConversation 只有在初始化成功后才可以使用,否则引发一些错误,如下:

    /**
     *@param conversationType 会话类型 {EnumConversationType} [PRIVATE|GROUP……] 如:EnumConversationType.PRIVATE
     *@param targetId 会话目标id {string}
     *@param title 会话显示标题 {string}
     */
    WebIMWidget.setConversation(WebIMWidget.EnumConversationType.PRIVATE,"x001","张三");
    

    5、隐藏、显示控件

    通过 showhide 方法设置控件显示与隐藏。

    //呈现会话面板
    WebIMWidget.show();
    //隐藏会话面板
    WebIMWidget.hide();
    

    6、事件

    会话面板被关闭时触发事件

    //会话面板被关闭时
    WebIMWidget.onClose = function() {
      //do something
    }
    

    接收到消息时触发事件

    //接收到消息时
    WebIMWidget.onReceivedMessage = function(message) {
      //message 收到的消息
    }
    

    7、用户信息设置

    通过 setUserInfoProvider 接口来设置插件中显示的用户信息。

    WebIMWidget.setUserInfoProvider(function(targetId,obj){
        $http({
          method:'GET',
          url:'自己服务器获取用户信息接口',
          params:{
            'userId':targetId
          }
        }).then(function(data){
            obj.onSuccess({name:data.name,userId:data.userId,portraitUri:data.portraitUri});
        });
    });
    

    上传插件

    插件内置 3 个云厂商上传方式,可参考七牛对其他云厂商的支持,且支持私有文件上传服务。

    使用融云文件存储注意事项:
    1、融云 SDK 中默认上传文件存储有效期为 1 个月
    2、文件不支持迁移

    1、七牛云

    需配置 token ,七牛官方文档Demo

    2、腾讯云

    需配置 sign 和 bucket ,腾讯官方文档Demo

    3、阿里云

    需配置 appServer,bucket,region,OSSUrl ,阿里官方文档Demo

    4、私有文件上传服务

    私有文件上传服务需要暴露 uploadProcess , upload.js 中会调用全局的 uploadProcess 方法。

    细节可参考 上传七牛云 Demo

    示例:

    window.uploadProcess = function(file, options, callback){
        // file => 上传的文件对象(file 或 base64)
        // options => 调用上传接口传入的 config 对象
        // callback => 调用上传接口传入的 callback 对象
    };
    

    客服插件

    引入融云 SDK

    融云官方网站下载插件包(项目源码 dist 目录),放在自己项目目录中,在页面中引入以下资源:

    <script type="text/javascript" src="{资源目录}/RongIMWidget.js"></script>
    <link rel="stylesheet" type="text/css" href="{资源目录}/css/RongIMWidget.css"/>
    <rong-widget></rong-widget>
    

    初始化客服插件

    var demo = angular.module("demo", ["RongWebIMWidget"]);
    demo.controller("main", ["$scope", "RongCustomerService", function($scope,RongCustomerService) {
      RongCustomerService.init({
        appkey:"bmdehs6pdw0sd",
        token:"****",
        customerServiceId:"****",
      });
    }]);
    

    插件样式设置

    通过 Position 控制客服显示位置, RongCustomerService.Position.left 为左侧显示、RongCustomerService.Position.right 为右侧显示。

    demo.controller("main", ["$scope", "RongCustomerService", function($scope,RongCustomerService) {
      RongCustomerService.init({
        appkey:"bmdehs6pdw0ss",
        token:"****",
        customerServiceId:"****",
        position:RongCustomerService.Position.left,
      });
    }]);
    

    通过 displayMinButton [ boolean ] 设置是否显示最小化按钮。true 表示为显示最小化按钮,false 表示为不显示,默认为 true 显示。

    RongCustomerService.init({
      appkey:"bmdehs6pdw0ss",
      token:"****",
      customerServiceId:"****",
      displayMinButton:false
    });
    

    通过 reminder 设置打开客服会话的按钮文字。

    RongCustomerService.init({
      appkey:"bmdehs6pdw0ss",
      token:"****",
      customerServiceId:"****",
      reminder:"在线咨询"
    });
    

    音视频服务

    详细请查看 Web CallLib 开发指南

    开源项目

    为了方便广大开发者,节约开发资源,融云在 GitHub 上提供以下开源项目: