Web SDK 开发指南

    特性介绍

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

    轻巧稳定:

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

    功能丰富:

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

    兼容性:

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

    扩展性:

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

    提供开源的聊天界面:

    image
    显示会话列表的聊天页面
    image
    聊天页面

    注册开发者帐号

    请前往融云官方网站注册开发者帐号。注册时,您需要提供真实的邮箱和手机号,以方便我们向您发送重要通知并在紧急时刻能够联系到您。如果您没有提供正确可用的邮箱和手机号,我们随时可能关闭您的应用。

    首先,让我们先创建您的第一个应用吧!

    创建应用

    您要进行应用开发之前,需要先在融云开发者平台创建应用。如果您还没有注册融云开发者帐号,请前往融云官方网站首先注册开发者帐号,注册后创建应用。

    您创建完应用后,最需要了解的就是 App Key / Secret,它们是融云 SDK 连接服务器所必须的标识,每一个 App 对应一套 App Key / Secret。针对开发者的生产环境和开发环境,我们提供两套 App Key / Secret,您在应用最终上线前,使用开发环境即可,两套环境的功能完全一致。

    image
    App Key / Secret 位置
    开发环境 App Key / Secret 是专门为您提供的仅供开发使用的,开发环境将和生产环境的数据隔离,避免开发环境数据和线上生产环境数据互相冲突。在“开发环境”分类下,您可以找到开发 App Key / Secret。您在申请上线前可以一直使用开发环境的 App Key / Secret 开发。

    生产环境的 App Key / Secret 默认先不提供,等您提交上线后,我们会提供生产环境的 App Key / Secret。

    引入 SDK

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

    融云 Web SDK 从 0.9.9 版本起将开始支持 seaJsrequireJs 等模块加载器。

    使用 requireJs 进行模块加载

      require.config({
        paths: {
         protobuf: 'http(s)://cdn.ronghub.com/protobuf-2.1.5.min',
         RongIMLib: 'http(s)://cdn.ronghub.com/RongIMLib-2.2.5.min'
        }
      });
    
      require(['protobuf','RongIMLib'], function(protobuf,RongIMLib) {
    
         //初始化
         RongIMLib.RongIMClient.init();
         //dosomething...
      });
    

    使用 seaJs 进行模块加载

    seajs.config({
     alias: {
       "RongIMLib":'http(s)://cdn.ronghub.com/RongIMLib-2.2.5.min.js'
      }
     });
    
     seajs.use("RongIMLib",function(){
       //dosomething...
     });
    

    编写代码

    初始化 SDK

    请使用您前面从融云开发者平台注册得到的 App Key,传入 init 方法,初始化 SDK 。在整个应用程序全局,只需要调用一次 init 方法。

    // 初始化
    // RongIMClient.init(appkey, [dataAccessProvider],[options]);
    // appkey:官网注册的appkey。
    // dataAccessProvider:自定义本地存储方案的实例,不传默认为内存存储,自定义需要实现WebSQLDataProvider所有的方法,此参数必须是传入实例后的对象。
    RongIMClient.init("e7x8xycsx6flq");
    
    以上代码中的 App Key 值 e7x8xycsx6flq 仅为示例,直接拷贝执行将返回错误,请注意替换为您自己的 App Key 值。

    设置监听器

    必须设置监听器后,再连接融云服务器,代码示例如下:

     // 设置连接监听状态 ( status 标识当前连接状态)
     // 连接状态监听器
     RongIMClient.setConnectionStatusListener({
        onChanged: function (status) {
            switch (status) {
                //链接成功
                case RongIMLib.ConnectionStatus.CONNECTED:
                    console.log('链接成功');
                    break;
                //正在链接
                case RongIMLib.ConnectionStatus.CONNECTING:
                    console.log('正在链接');
                    break;
                //重新链接
                case RongIMLib.ConnectionStatus.DISCONNECTED:
                    console.log('断开连接');
                    break;
                //其他设备登录
                case RongIMLib.ConnectionStatus.KICKED_OFFLINE_BY_OTHER_CLIENT:
                    console.log('其他设备登录');
                    break;
                  //网络不可用
                case RongIMLib.ConnectionStatus.NETWORK_UNAVAILABLE:
                  console.log('网络不可用');
                  break;
                }
        }});
    
     // 消息监听器
     RongIMClient.setOnReceiveMessageListener({
        // 接收到的消息
        onReceived: function (message) {
            // 判断消息类型
            switch(message.messageType){
                case RongIMClient.MessageType.TextMessage:
                       // 发送的消息内容将会被打印
                    console.log(message.content.content);
                    break;
                case RongIMClient.MessageType.VoiceMessage:
                    // 对声音进行预加载                
                    // message.content.content 格式为 AMR 格式的 base64 码
                    RongIMLib.RongIMVoice.preLoaded(message.content.content);
                    break;
                case RongIMClient.MessageType.ImageMessage:
                    // do something...
                    break;
                case RongIMClient.MessageType.DiscussionNotificationMessage:
                    // do something...
                    break;
                case RongIMClient.MessageType.LocationMessage:
                    // do something...
                    break;
                case RongIMClient.MessageType.RichContentMessage:
                    // do something...
                    break;
                case RongIMClient.MessageType.DiscussionNotificationMessage:
                    // do something...
                    break;
                case RongIMClient.MessageType.InformationNotificationMessage:
                    // do something...
                    break;
                case RongIMClient.MessageType.ContactNotificationMessage:
                    // do something...
                    break;
                case RongIMClient.MessageType.ProfileNotificationMessage:
                    // do something...
                    break;
                case RongIMClient.MessageType.CommandNotificationMessage:
                    // do something...
                    break;
                case RongIMClient.MessageType.CommandMessage:
                    // do something...
                    break;
                case RongIMClient.MessageType.UnknownMessage:
                    // do something...
                    break;
                default:
                    // 自定义消息
                    // do something...
            }
        }
    });
    

    获取 Token

    Token 也叫用户令牌,是 SDK 端用来连接融云服务器的凭证,每个用户连接服务器都需要一个 Token。每次初始化连接服务器(请看下节)时,都需要向服务器提交 Token。

    要想获取用户 Token,流程如下:首先需要您的 App 查询您的应用程序服务器,然后您的应用程序服务器再访问融云服务器获取,最后返回给 App,App 用返回的 Token 连接服务器登录。详细描述请参考 Server 开发指南中的用户服务小节。

    为了方便您进行测试开发,我们还提供了 API 调试工具,以便您不用部署服务器端程序,即可直接获得测试开发所需的用户令牌。请访问我们的融云开发者平台,打开您想测试的应用,在左侧菜单中选择“API 调试”即可。
    image
    API 调试工具

    连接服务器

    将您在上一节请求身份认证服务器时获取的 Token 传入 connect 方法,开始连接服务器。在整个应用程序全局,只需要调用一次 connect 方法,SDK 会负责自动重连。

    您可以用在上一节介绍的 API 调试工具生成一个 Token,这里我们假设您生成 Token 时使用的参数如下:

    用户 Id: userId = "1"

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

    用户名称: name = "韩梅梅"

    用户的显示名称,用来在 Push 推送时,或者客户端没有提供用户信息时,显示用户的名称。

    用户头像地址: portraitUri = "http://rongcloud-web.qiniudn.com/docs_demo_rongcloud_logo.png"

    这里为了测试,您可以随意提供一个地址,如果此图片不存在,会显示默认的头像。

    假设返回的 Token 是 mKmyKqTSf7aNDinwAFMnz7NXKILeV3X0+CCRBOxmtOApmvQjMathViWrePIfq0GuTu9jELQqsckv4AhfjCAKgQ==

    代码示例

    // 初始化。
    RongIMClient.init("e7x8xycsx6flq");
    var token = "mKmyKqTSf7aNDinwAFMnz7NXKILeV3X0+CCRBOxmtOApmvQjMathViWrePIfq0GuTu9jELQqsckv4AhfjCAKgQ==";
    
    // 连接融云服务器。
          RongIMClient.connect(token, {
            onSuccess: function(userId) {
              console.log("Login successfully." + userId);
            },
            onTokenIncorrect: function() {
              console.log('token无效');
            },
            onError:function(errorCode){
                  var info = '';
                  switch (errorCode) {
                    case RongIMLib.ErrorCode.TIMEOUT:
                      info = '超时';
                      break;
                    case RongIMLib.ErrorCode.UNKNOWN_ERROR:
                      info = '未知错误';
                      break;
                    case RongIMLib.ErrorCode.UNACCEPTABLE_PaROTOCOL_VERSION:
                      info = '不可接受的协议版本';
                      break;
                    case RongIMLib.ErrorCode.IDENTIFIER_REJECTED:
                      info = 'appkey不正确';
                      break;
                    case RongIMLib.ErrorCode.SERVER_UNAVAILABLE:
                      info = '服务器不可用';
                      break;
                  }
                  console.log(errorCode);
                }
          });
    
    以上代码中的 Token 值 mKmyKqTSf7aNDinwAFMnz7NXKILeV3X0+CCRBOxmtOApmvQjMathViWrePIfq0GuTu9jELQqsckv4AhfjCAKgQ== 仅为示例,直接拷贝执行将返回错误,请注意替换为您自己的 Token 值。

    发送消息

    发送单聊、群组及聊天室消息,发送消息必须在执行初始化 SDK 方法 init 及连接融云服务器 connect 成功之后进行。

     // 定义消息类型,文字消息使用 RongIMLib.TextMessage
     var msg = new RongIMLib.TextMessage({content:"hello",extra:"附加信息"});
     //或者使用RongIMLib.TextMessage.obtain 方法.具体使用请参见文档
     //var msg = RongIMLib.TextMessage.obtain("hello");
     var conversationtype = RongIMLib.ConversationType.PRIVATE; // 私聊
     var targetId = "xxx"; // 目标 Id
     RongIMClient.getInstance().sendMessage(conversationtype, targetId, msg, {
                    // 发送消息成功
                    onSuccess: function (message) {
                        //message 为发送的消息对象并且包含服务器返回的消息唯一Id和发送消息时间戳
                        console.log("Send successfully");
                    },
                    onError: function (errorCode,message) {
                        var info = '';
                        switch (errorCode) {
                            case RongIMLib.ErrorCode.TIMEOUT:
                                info = '超时';
                                break;
                            case RongIMLib.ErrorCode.UNKNOWN_ERROR:
                                info = '未知错误';
                                break;
                            case RongIMLib.ErrorCode.REJECTED_BY_BLACKLIST:
                                info = '在黑名单中,无法向对方发送消息';
                                break;
                            case RongIMLib.ErrorCode.NOT_IN_DISCUSSION:
                                info = '不在讨论组中';
                                break;
                            case RongIMLib.ErrorCode.NOT_IN_GROUP:
                                info = '不在群组中';
                                break;
                            case RongIMLib.ErrorCode.NOT_IN_CHATROOM:
                                info = '不在聊天室中';
                                break;
                            default :
                                info = x;
                                break;
                        }
                        console.log('发送失败:' + info);
                    }
                }
            );
    

    同步会话列表

    在浏览器中使用融云 Web SDK 与在移动端中使用融云 iOS、Android SDK 不同的是浏览器一刷新页面,之前已经在内存中存好的会话列表都将会清空。

    Web SDK 提供 getConversationList 来获取会话列表,如果本地不存在会话记录,SDK 会自动向服务器拉取,此方法必须在执行初始化 SDK 方法 init 及连接融云服务器 connect 成功之后进行。

    注:在使用 getConversationList 方法前需开通 历史消息云存储(原历史消息漫游) 功能,否则无法获取会话记录,此功能为付费功能,开发环境下可免费使用。您需要登录开发者后台,在付费功能 -> 历史消息云存储中,开启后才能使用。收费详情
    //getConversationList示例
    
       RongIMClient.getInstance().getConversationList({
          onSuccess: function(list) {
            console.log(list);
          },
          onError: function(error) {
             // do something...
          }
        },null);
    

    获取历史消息

    通过 getHistoryMessages 来帮助开发者获取历史消息纪录。此方法必须在执行初始化 SDK 方法 init 及连接融云服务器 connect 成功之后进行,使用此方法前提是 APP 必须开启单群聊消息云存储,如 APP 没有开启则执行 onError 方法。

    单群聊消息云存储不支持聊天室消息云存储,拉取历史消息最多一次行拉取 20 条消息。拉取顺序按时间倒序拉取,如果本地不存在历史消息,SDK 会自动向服务器拉取。

    单群聊消息云存储为付费功能,开发环境下可免费使用。您需要登录开发者后台,在付费功能 -> 单群聊消息云存储中,开启后才能使用。收费详情

    拉取历史消息为循环拉取,举例:

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

    //getHistoryMessages
     RongIMClient.getInstance().getHistoryMessages(RongIMLib.ConversationType.PRIVATE, 'targetId', null, 20, {
              onSuccess: function(list, hasMsg) {
                // hasMsg为boolean值,如果为true则表示还有剩余历史消息可拉取,为false的话表示没有剩余历史消息可供拉取。
                   // list 为拉取到的历史消息列表
              },
              onError: function(error) {
                  // APP未开启消息漫游或处理异常
                       // throw new ERROR ......
              }
            });
    

    自定义消息

    1、自定义消息支持方式

    1. 自定义消息结构及解析方式。
    2. SDK 内置消息结构及解析方式。

    2、自定消息类型参数说明

    RongIMClient.registerMessageType('messageType','objectName','messageTag','message|[]')

    1. messageType:消息类型(与自定义消息类名一致)。
    2. objectName:消息内置名称。
    3. messageTag:设置是否保存是否计数。
    4. message|[]:此参数有一参二用的功能,自定义消息结构及解析方式请传入自定义消息的实例,使用融云内置消息结构及解析方式,直接传入属性数组即可["name","age"]。

    3、自定消息注意事项

    1. 自定义消息结构: 任意形式,在 decode 中解析可即可。
    2. SDK 内置消息结构: JSON 类型的字符串 JSON.stringify({name:"zhangsan",age:12})
    3. 自定义消息注册位置: RongIMClient.init("appkey") 之后的第一行位置注册即可。
    4. 必须在执行初始化 SDK 方法 init 及连接融云服务器 connect 成功之后进行。

    注册自定义消息示例(消息结构自定义)

    自定义消息结构,首先要定义消息类,其次是注册,EmptyMessage 为自定义消息名称。

    以下代码为示例代码,实际应用中可能有不规范之处,敬请谅解,自定义消息类型,格式必须与此一样,可修改的内容有:

    1. 消息类名称可修改为:

      RongIMClient.RegisterMessage.***Message=function(message){
         dosomething....
      }
      
    2. messageName 的值必须与消息类名称一致。
    3. encode 方法的实现可以自定义(编译消息,发送消息时用到)。
    4. decode 方法的实现可以自定义(解析消息,接受消息时用到)。
    //1、创建消息
    RongIMClient.RegisterMessage.PersonMessage = function(message){
    
           this.messageName = "PersonMessage";
    
           this.encode = function(){
              return "name="+message.name+";age="+message.age;
           }
    
           this.decode = function(message){
    
             if (typeof message != "string") {
                return message;
             }
    
             var strArrs = message.split(";"),msg = new RongIMClient.RegisterMessage.PersonMessage();
    
             for(var p in strArrs){
                msg[strArrs[p].split("=")[0]]=strArrs[p].split("=")[1];
             }
             return msg;
           }
       }
    RongIMClient.registerMessageType('PersonMessage','s:empty',new RongIMLib.MessageTag(true,true),new RongIMClient.RegisterMessage.PersonMessage);
    //发送消息
    var msg = new RongIMClient.RegisterMessage.PersonMessage({name:"zhang",age:12});
    RongIMClient.getInstance().sendMessage('convertype','targetId', msg, {
                onSuccess: function (data) {
                },
                onError: function (errorCode) {
                }
            });
    

    注册自定义消息示例(内置消息结构)

    //创建消息
    RongIMClient.registerMessageType('PersonMessage','s:empty',new RongIMLib.MessageTag(true,true),["name","age"]);
    //发送消息
    var msg = new RongIMClient.RegisterMessage.PersonMessage({name:"zhang",age:12});
    RongIMClient.getInstance().sendMessage('convertype','targetId', msg, {
                onSuccess: function (data) {
                },
                onError: function (errorCode) {
                }
            });
    

    检测未读消息

    此接口用来查询当前传入 Token(表示一个用户)是否有未读的消息,此方法必须在执行初始化 SDK 方法 init 及连接融云服务器 connect 成功之后进行。

    //此接口必须在init()方法之后调用。
    RongIMClient.getInstance().hasRemoteUnreadMessages('mKmyKqTSf7aNDinwAFMnz7NXKILeV3X0+CCRBOxmtOApmvQjMathViWrePIfq0GuTu9jELQqsckv4AhfjCAKgQ==',{
        onSuccess:function(hasMessage){
            if(hasMessage){
                // 有未读的消息
            }else{
                // 没有未读的消息
            }
        },onError:function(err){
            // 错误处理...
        }
    });
    

    表情库

    表情库引用地址

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

    表情库使用方法

    1、RongEmoji 默认支持 128 个 Emoji 表情并且支持自定义 Emoji 。

    2、如果使用自定义的 Emoji,请设置 emojiFactory 对象的 dataSourceurl 属性。

    3、初始化 Emoji 中的 emojiFactory 子项说明: en: 英文名称;zh: 中文名称;tag: 原生 Emoji;bp: Emoji 所在图片坐标;

    1、初始化 Emoji

    1、表情名称: ['名称'],例如:[露齿而笑]。

    2、表情结构:

    Windows:<span class="RongIMExpression_rinning" name="[狞笑]">表情图片</span>

    Mac/iOS:<span class="RongIMExpression_rinning" name="[狞笑]">原生 Emoji</span>

    3、RongIMLib.RongIMEmoji.init([em])

    方法 1,使用默认 Emoji 和图片:

    RongIMLib.RongIMEmoji.init();
    

    方法 2,使用自定义 Emoji 和图片:

    1、emojiFactory.dataSource.bp 必须和表情所在图片的坐标一一匹配。

    例如:

    图片:

    image

    emoji: var emojiFactory = {"u1F601":{"en":"grin","zh":"\u9732\u9F7F\u800C\u7B11","tag":"\uD83D\uDE01","bp":"-22px 0px"}}

    var emojiFactory = {dataSource:{
                              "u1F600":{"en":"grinning","zh":"\u72DE\u7B11","tag":"\uD83D\uDE00","bp":"0px 0px"},
                              "u1F601":{"en":"grin","zh":"\u9732\u9F7F\u800C\u7B11","tag":"\uD83D\uDE01","bp":"-22px 0px"},
                              "u1F602":{"en":"joy","zh":"\u6B22\u4E50","tag":"\uD83D\uDE02","bp":"-44px 0px"}},
                        url:"url路径"};
    RongIMLib.RongIMEmoji.init(emojiFactory);
    

    2、获取全部表情

    执行 RongIMLib.RongIMEmoji.init() 后,RongIMLib.RongIMEmoji.emojis 可获取存放全部表情的数组 emojis

    var emojis = RongIMLib.RongIMEmoji.emojis;
    // emojis[0].innerHTML => <span class="RongIMExpression_rinning" name="[狞笑]"> 表情图片 </span>
    // emojis[0].children[0].getAttribute("name") => "[狞笑]"
    

    3、名称转 Emoji

    1、发送消息使用。

    var str = RongIMLib.RongIMEmoji.symbolToEmoji("[狞笑][露齿而笑]测试Emoji");
    //str => "😀😁测试Emoji"
    

    4、Emoji 转名称

    1、会话列表显示最后一条消息使用。

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

    5、Emoji 转字 HTML

    1、接收消息使用。

    var str = RongIMLib.RongIMEmoji.emojiToHTML("😂测试 Emoji");
    // str => "<span class="RongIMExpression_rinning" name="[欢乐]"><b class="RC_Expression" style="background-position: -44px 0px;"></b></span>"
    

    6、名称转字 HTML

    var str = RongIMLib.RongIMEmoji.symbolToHTML("[露齿而笑]测试 Emoji");
    // str => "<span class="RongIMExpression_rinning" name="[露齿而笑]"><b class="RC_Expression" style="background-position: -22px 0px;"></b></span>"
    

    7、表情模块兼容 ADM、CMD 等 CommonJS 规范

    1、表情模块已经兼容 AMD、CMD,如下:

    使用 requireJs 进行模块加载

    require.config({
      paths: {
        RongIMEmoji : 'http://cdn.ronghub.com/RongEmoji-2.2.5.min'
      }
    });
    
    require(['RongIMEmoji'], function() {
     //dosomething...
    });
    

    使用 seaJs 进行模块加载

    seajs.config({
     alias: {
       "RongIMEmoji":'http://cdn.ronghub.com/RongEmoji-2.2.5.min.js'
      }
    });
    
    seajs.use("RongIMEmoji",function(){
      //dosomething...
    });
    

    声音库

    声音基本信息

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

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

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

    4、声音库支持 AMD、CMD、SeaJS

    声音库使用方法

    <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、引用 SDK

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

    <script type="text/javascript" src="{资源目录}/RongIMWidget.js"></script>
    <link rel="stylesheet" type="text/css" href="{资源目录}/css/RongIMWidget.css"/>
    
    在页面 body 中加入 <rong-widget></rong-widget> 标签。

    2、初始化

    Angular Modle 中引入 SDK :

    var demo = angular.module("demo", ["RongWebIMWidget"]);
    

    在整个应用程序全局,只需要调用一次 init 方法:

    /*
     *@param config {Object} 初始化配置参数
     */  
    WebIMWidget.init(config);
    

    在集成融云聊天插件前,需要配置 App KeyToken 这两个基础参数,如下:

    demo.controller("main", ["$scope", "WebIMWidget", function($scope,WebIMWidget) {
        WebIMWidget.init({
          appkey:"bmdehs6pd",
          token:"****"
        });
    }]);
    
    注:请从融云开发者平台注册得到的 App KeyToken

    初始化回调函数,onSuccess 初始化成功回调、onError 初始化错误回调。如下:

    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、七牛云

    需配置 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 对象
        // TODO 实现上传文件上传逻辑(文件、大文件分片、图片、Base64 格式图片等)
    };
    

    客服插件

    引入融云 SDK

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

    <script type="text/javascript" src="{资源目录}/RongIMWidget.js"></script>
    <link rel="stylesheet" type="text/css" href="{资源目录}/css/RongIMWidget.css"/>
    
    在页面 body 中加入 <rong-widget></rong-widget> 标签。

    初始化客服插件

    在您 js 文件的 angular modle 中引入 SDK var demo = angular.module("demo", ["RongWebIMWidget"]);

    初始化时需要传入 appkey 、token 、customerServiceId 参数信息:

    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:"在线咨询"
    });
    

    API 调用示例

    为了方便刚接触融云 Web SDK 的开发者更有效的使用 API 接口,总结了 SDK API 的用法及常见异常,详细请参考 Web SDK API 示例

    音视频服务

    详细请查看 Web CallLib 开发指南

    开源项目

    为了方便广大开发者,节约您的开发资源和时间,我们在 GitHub 上提供了开源项目。

    GitHub 项目如下: