Web SDK 开发指南

    特性介绍

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

    轻巧稳定:

    • SDK 采用 TypeScript 语言开发,结构清晰、健壮
    • 即时通讯库尺寸小,只有 100 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.8.min.js"></script>
    Release Notes:
    1、修复了不刷新页面重复加入聊天室无法获取最新聊天内容的问题。
    2、修复了可以撤回其他用户发送的消息的问题。
    3、优化了错误信息日志,RongIMClient.init(appkey, null, {showError: true}) 开启,默认关闭。
    4、新增了在线状态。

    历史版本: <script src="http(s)://cdn.ronghub.com/RongIMLib-2.2.7.min.js"></script>

    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 方法前必须开通 单群聊消息云存储 功能。 开发环境下可免费使用,生产环境下,需要在开发者后台“应用/IM 服务/高级功能设置”中开通公有云专业版后,开启单群聊消息云存储功能即可使用。

    会话列表中包含的会话类型如下:

    • RongIMLib.ConversationType.PRIVATE : 二人单聊会话类型,枚举值为 1 。
    • RongIMLib.ConversationType.DISCUSSION : 讨论组会话类型,枚举值为 2 。
    • RongIMLib.ConversationType.GROUP : 群组会话类型,枚举值为 3。
    • RongIMLib.ConversationType.CUSTOMER_SERVICE : 客服会话类型,枚举值为 5 。
    • RongIMLib.ConversationType.SYSTEM : 系统消息类型,枚举值为 6 。
    • RongIMLib.ConversationType.APP_PUBLIC_SERVICE : 公众号(默认关注)会话类型,枚举值为 7 。
    • RongIMLib.ConversationType.PUBLIC_SERVICE : 公众号 (手动关注) 会话类型,枚举值为 8 。

    注:聊天室类型会话(RongIMLib.ConversationType.CHATROOM 枚举值为 4)不进入会话列表。

     //请确保单群聊消息云存储服务开通,且开通后有过收发消息记录
     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",
          "sentStatus": 40,
          "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",
        "sentStatus": 1,
        "sentTime": 1499238335281,
        "targetId": "9e6ea82e-caa1-467b-8ee5-02a9c2460196",
        "unreadMessageCount": 0
      }
    

    会话列表中,每个会话的数据结构如下:

    名称 说明
    conversationTitle 会话标题。
    conversationType 会话类型,1 为单聊、2 为讨论组、3 为群组、4 为聊天室、5 为客服、6 为系统、7 为应用公众服务,8 为公有公众服务。
    latestMessageId 会话中最后一条消息 Id。
    notificationStatus 是否设置消息免打扰。
    objectName 会话中最后一条消息的消息标识,融云内置消息以 "RC:" 开头。融云内置消息类型表
    sentStatus 10 为发送中、20 为发送失败、30 为已发送、40 为对方已接收、50 为对方已读、60 为对方已销毁。
    sentTime 会话中最后一条消息融云服务端的发送时间。
    targetId 根据 conversationType 的不同,可能是用户 Id、讨论组 Id、3 群组 Id、4 聊天室 Id、5 客服 Id、6 系统会话 Id、7 应用公众号 Id,8 为公有公众号 Id
    unreadMessageCount 当前会话的未读消息数。
    latestMessage 会话中最后一条消息。

    会话列表中 latestMessage 结构如下:

    名称 说明
    content 消息内容。
    conversationType 会话类型,1 为单聊、2 为讨论组、3 为群组、4 为聊天室、5 为客服、6 为系统、7 为应用公众服务,8 为公有公众服务。
    objectName 消息标识,融云内置消息以 "RC:" 开头。融云内置消息类型表
    messageDirection 消息方向,1 为发送的消息、2 为接收的消息。
    messageId 本地生成的消息 Id。
    sentStatus 10 为发送中、20 为发送失败、30 为已发送、40 为对方已接收、50 为对方已读、60 为对方已销毁
    receivedTime 应用接收到消息的本地时间。
    senderUserId 发送方 Id。
    sentTime 消息在融云服务端的发送时间。
    targetId 目标 Id。
    messageType 消息类型,详细请查看消息类型说明
    messageUId 消息在融云服务端的唯一标识,通过 messageUId 进行消息撤回操作。
    offLineMessage 是否为离线消息,true 为离线消息,false 为非离线消息。

    获取历史消息

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

    该方法开发环境下可免费使用,生产环境下需要登录开发者后台,在“应用/IM 服务/高级功能设置”中开通公有云专业版后,开启单群聊消息云存储功能才能使用。

    单群聊消息云存储不支持聊天室消息云存储,拉取历史消息最多一次行拉取 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 ......
        }
      });
    

    用户信息

    1. 获取会话后,可以根据 conversationType 和 targetId 判断会话对象,然后根据 targetId 从应用服务器获取相应数据
    2. 接收到消息后,可以根据 conversationType 和 senderUserId 判断会话对象,然后根据 senderUserId 从应用服务器获取相应数据

    表情库

    表情库引用地址

    获取官方表情库 (当前版本为 2.2.6 ) :
    <script src="http(s)://cdn.ronghub.com/RongEmoji-2.2.6.min.js"></script>
    代码示例: https://rongcloud.github.io/websdk-demo/emoji.html

    表情库使用方法

    1. 兼容表情库 2.2.5 及以下版本
    2. 默认支持 128 个 Emoji 表情并且支持自定义扩展 Emoji
    3. 支持范围:
      (1) IE7+、Edge、Chrome 30+、Firefox 30+、Safari 10+ 等主流桌面版浏览器
      (2) Android 4.4+ 系统的 Chrome 浏览器以及微信浏览器
      (3) iPhone 操作系统 iOS 8.0+ 的 Safari 浏览器以及微信浏览器

    1、Emoji 初始化

    使用默认参数初始化

    RongIMLib.RongIMEmoji.init();
    

    通过配置初始化

    // 表情信息可参考 http://unicode.org/emoji/charts/full-emoji-list.html
    var config = {
      size: 24, // 大小, 默认 24, 建议18 - 58
      url: "//f2e.cn.ronghub.com/sdk/emoji-48.png", // Emoji 背景图片
      lang: "zh", // Emoji 对应名称语言, 默认 zh
      // 扩展表情
      extension: {
        dataSource: {
          u1F914: {
            en: "thinking face", // 英文名称
            zh: "思考", // 中文名称
            tag: "🤔", // 原生 Emoji
            position: "0 0" // 所在背景图位置坐标
          }
        },
        // 新增 Emoji 背景图 url
        url: "//cdn.ronghub.com/thinking-face.png"
      }
    };
    RongIMLib.RongIMEmoji.init(config);
    

    2、获取 Emoji 列表

    var list = RongIMLib.RongIMEmoji.list;
    /*
    list => [
        {
            unicode: 'u1F600',
            emoji: "😀",
            node: span,
            symbol: "[笑嘻嘻]"
        },
        ...
    ]
    */
    

    3、Emoji 转名称

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

    var message = "😀😁测试 Emoji";
    // 将 message 中的原生 Emoji 转化为对应名称
    RongIMLib.RongIMEmoji.emojiToSymbol(message);
    // => "[笑嘻嘻][露齿而笑]测试 Emoji"
    

    4、名称转 Emoji

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

    var message = "[笑嘻嘻][露齿而笑]测试 Emoji";
    // 将 message 中的 Emoji 对应名称转化为原生 Emoji
    RongIMLib.RongIMEmoji.symbolToEmoji(message);
    // => "😀😁测试 Emoji"
    

    5、Emoji 转 HTML

    Web SDK 接收消息后,消息体内的原生 Emoji 字符会被解码为对应 Unicode 码,需调用转化方法才能正确显示

    var message = "\uf600测试 Emoji";
    // 将 message 中的原生 Emoji (包含 Unicode ) 转化为 HTML
    RongIMLib.RongIMEmoji.emojiToHTML(message);
    // => "<span class='rong-emoji-content' name='[笑嘻嘻]'>😀</span>测试 Emoji"
    

    6、名称转 HTML

    var message = "[露齿而笑]测试 Emoji";
    // 将 message 中的 Emoji 对应名称转化为 HTML
    RongIMLib.RongIMEmoji.symbolToHTML(message);
    // => "<span class='rong-emoji-content' name='[露齿而笑]'>😁</span>测试 Emoji"
    

    7、支持 ADM、CMD

    // requirejs
    require.config({
        paths: {
            'RongIMEmoji': 'http(s)://cdn.ronghub.com/RongEmoji-2.2.6.min'
        }
    });
    require(['RongIMEmoji'], function(RongIMEmoji) {
        var message = "\uf600测试 Emoji";
        RongIMEmoji.symbolToEmoji(message);
        // => "😀测试 Emoji"
    });
    

    声音库

    声音库引用地址

    获取官方声音库 (当前版本 2.2.5 ) :
    <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>
    代码示例: https://rongcloud.github.io/websdk-demo/voice.html

    声音库使用方法

    支持范围:
    ​ (1) IE9+、Edge、Chrome 49+、Firefox 52+、Safari 等主流桌面版浏览器
    ​ (2) Android 4.4+ 系统的默认浏览器以及微信浏览器
    ​ (3) iOS Safari 浏览器以及微信浏览器

    1、初始化

    RongIMLib.RongIMVoice.init();
    

    2、播放音频

    /*
    音频格式: base64 格式的 AMR
    完整示例音频: https://cdn.ronghub.com/voice-amr-base64.json
    */
    var audioFile = "IyFBTVIKLNEafAAeef/hgmeAH8AD...";
    // 音频文件长度   
    var duration = audioFile.length / 1024;
    // 预加载
    RongIMLib.RongIMVoice.preLoaded(audioFile, function(){
        // 播放声音
        RongIMLib.RongIMVoice.play(audioFile, duration);
    });
    

    3、停止播放

    RongIMLib.RongIMVoice.stop(audioFile);
    

    如何开发 WebIM

    如何基于 Web SDK 快速开发出一款 IM 产品? 参考 Web IM 集成开发可以快速系统的进行开发。

    聊天插件

    聊天插件是 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 中默认上传文件存储有效期为 6 个月
    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 上提供以下开源项目: