Web SDK 开发指南

特性介绍

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

轻巧稳定:

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

功能丰富:

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

兼容性:

  • 兼容各种环境:IE6 - IE11, Chrome, Firefox, Safari, Edge, H5, QQ 浏览器, 微信浏览器, Electron, Android 浏览器 2.3.6 及以上
  • 支持两种连接:WebSocketHTTP 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.4 ) 地址加入到自己页面中 如下:
<script src="http://cdn.ronghub.com/RongIMLib-2.2.4.min.js"></script>
支持 https
<script src="https://cdn.ronghub.com/RongIMLib-2.2.4.min.js"></script>

编写代码

1、初始化 SDK

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

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

2、获取 Token

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

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

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

3、设置消息监听器

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

 // 设置连接监听状态 ( 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...
        }
    }
});

4、连接服务器

将您在上一节请求身份认证服务器时获取的 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==

4.1、Token 获取方式

1.未搭建后台服务:如上步骤 2 所述,直接去融云官网注册 Token,直接连接即可。
2.已搭建后台服务:调用融云 Server API,向融云注册 Token,融云返回 Token 给您,保存到本地服务器,Token 不需要每次登录都注册。
从您的应用服务器请求,以获取 Token。在本示例中我们直接在下面 hardcode 给 Token 赋值。
var token = getTokenFromAppServer();
此处直接 hardcode 给 Token 赋值,请替换为您自己的 Token。

4.2、示例

// 初始化。
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 值。

5.1、发送消息

发送单聊消息,群组消息,聊天室消息。

 // 定义消息类型,文字消息使用 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);
                }
            }
        );

5.2、同步会话列表

在浏览器中使用融云 Web SDK 与在移动端中使用融云 iOS、Android SDK 不同的是浏览器一刷新页面,之前已经在内存中存好的会话列表都将会清空。
Web SDK 提供 getConversationList 来获取会话列表,如果本地不存在会话记录,SDK 会自动向服务器拉取。

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

   RongIMClient.getInstance().getConversationList({
      onSuccess: function(list) {
        console.log(list);
      },
      onError: function(error) {
         // do something...
      }
    },null);

5.3、获取历史消息

融云 Web SDK 最新提供 getHistoryMessages,来帮助开发者获取历史消息纪录。 使用此方法前提是 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 ......
          }
        });

5.4、自定义消息

5.4.1.1、自定义消息支持方式

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

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

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

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

5.4.1.3、自定消息注意事项

  1. 自定义消息结构: 任意形式,在 decode 中解析可即可。
  2. SDK 内置消息结构: JSON 类型的字符串 JSON.stringify({name:"zhangsan",age:12})
  3. 自定义消息注册位置: RongIMClient.init("appkey") 之后的第一行位置注册即可。

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

自定义消息结构,首先要定义消息类,其次是注册,EmptyMessage 为自定义消息名称。
以下代码为示例代码,实际应用中可能有不规范之处,敬请谅解,自定义消息类型,格式必须与此一样,可修改的内容有:

  1. 消息类名称可修改为:
RongIMClient.RegisterMessage.***Message=function(message){
    dosomething....
}
  1. messageName 的值必须与消息类名称一致。
  2. encode 方法的实现可以自定义(编译消息,发送消息时用到)。
  3. 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, null, {
            onSuccess: function (data) {
            },
            onError: function (errorCode) {
            }
        });

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

//创建消息
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, null, {
            onSuccess: function (data) {
            },
            onError: function (errorCode) {
            }
        });

5.5、检测是否有未读的消息

此接口用来查询当前传入 Token(表示一个用户)是否有未读的消息。

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

6、兼容 CMD、AMD 等 CommonJS 规范

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

使用 requireJs 进行模块加载

  require.config({

    paths: {

     protobuf: 'http://cdn.ronghub.com/protobuf-2.1.5.min',

     RongIMLib: 'http://cdn.ronghub.com/RongIMLib-2.2.4.min'

    }

  });

  require(['protobuf','RongIMLib'], function(protobuf,RongIMLib) {

     //初始化
     RongIMLib.RongIMClient.init();

     //dosomething...

  });

使用 seaJs 进行模块加载

seajs.config({
 alias: {
   "RongIMLib":'http://cdn.ronghub.com/RongIMLib-2.2.4.min.js'
  }
 });

 seajs.use("RongIMLib",function(){
   //dosomething...
 });

7.1、 表情库引用地址

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

7.2、 表情库使用方法

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

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

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

7.2.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);

7.2.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") => "[狞笑]"

7.2.3、 名称转 Emoji

1、发送消息使用。

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

7.2.4、 Emoji 转名称

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

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

7.2.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>"

7.2.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.2.7、 表情模块兼容 ADM、CMD 等 CommonJS 规范

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

使用 requireJs 进行模块加载

require.config({
  paths: {
    RongIMEmoji : 'http://cdn.ronghub.com/RongEmoji-2.2.4.min'
  }
});

require(['RongIMEmoji'], function() {
 //dosomething...
});

使用 seaJs 进行模块加载

seajs.config({
 alias: {
   "RongIMEmoji":'http://cdn.ronghub.com/RongEmoji-2.2.4.min.js'
  }
});

seajs.use("RongIMEmoji",function(){
  //dosomething...
});

8.1、 声音库引用地址

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

8.2、 声音库使用方法

播放声音自动兼容浏览器:

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

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

3、iOS SafariiOS 微信浏览器Android Chrome 浏览器Android 微信浏览器

声音插件方法调用顺序:

1、初始化声音库 RongIMLib.RongIMVoice.init()

2、必须先执行 RongIMLib.RongIMVoice.preLoaded(base64Str)

3、播放声音 RongIMLib.RongIMVoice.play(base64Str)

8.2.1、初始化声音库

声音库使用之前必须进行初始化操作,初始化位置在 RongIMClient.init(appkey, [dataAccessProvider]); 之后即可,在整个应用程序全局,声音库只需 init 一次。

RongIMLib.RongIMVoice.init();

8.2.2、预加载声音

请收到 VoiceMessage 后对声音进行预加载,预加载位置在接收消息监听 onReceived 方法中。

RongIMLib.RongIMVoice.preLoaded(base64Str);

8.2.3、播放声音

1、播放传入的格式为 AMR 的音频 BASE64 码 RongIMLib.RongIMVoice.play(base64Str,duration)

// base64Str 格式为 AMR 格式的 base64 码。
var base64Str = "IyFBTVIKLNEafAAeef/hgmeAH8AD...";
// 音频持续大概时间(秒)
var duration = base64Str.length/1024;
RongIMLib.RongIMVoice.play(base64Str,duration);

8.2.4、停止播放

1、暂停消息播放。

// base64Str 格式为 AMR 格式的 base64 码
RongIMLib.RongIMVoice.stop(base64Str);

8.2.5、声音库兼容 ADM、CMD 等 CommonJS 规范

1、声音库已经兼容 AMD、CMD,如下:

使用 requireJs 进行模块加载

require.config({
  paths: {
    RongIMVoice : 'http://cdn.ronghub.com/RongIMVoice-2.2.4.min'
  }
});

require(['RongIMVoice'], function() {
 //dosomething...
});

使用 seaJs 进行模块加载

seajs.config({
 alias: {
   "RongIMVoice":'http://cdn.ronghub.com/RongIMVoice-2.2.4.min.js'
  }
});

seajs.use("RongIMVoice",function(){
  //dosomething...
});

9、 客服功能

原理同上,通过以下代码,您的 App 可以直接调起客服聊天界面。 其中,customerServiceId 的值,可以在 融云开发者平台 的客服模块中找到。 位置为:xx应用 / 客服业务 / 客服管理 。查看 customerServiceId 之前,请您先开启客服功能。

image
customerServiceId 值的位置
 var customerServiceId = "XXXXXX";// 客服 Id
 var msg = new RongIMLib.TextMessage({content:"hello",extra:"附加信息"});
 var conversationtype = RongIMLib.ConversationType.CUSTOMER_SERVICE; // 客服会话类型
 RongIMClient.getInstance().sendMessage(conversationtype, customerServiceId, msg, {

                onSuccess: function (message) {

                },
                onError: function (errorCode,message) {

                }
            }
        );

聊天插件

聊天插件是 Web IM SDK 的特色功能,通过简单几行代码,就可以直接将聊天界面集成到您的产品中,省去大量的开发调试时间。目前提供 AngularJS 集成方式。

1、引用 SDK

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

<scrip 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});
    });
});

Upload 插件

引用插件

引入 Web Upload 插件地址: http://cdn.ronghub.com/RongUploadLib-2.2.4.min.js

使用方法

1、初始化

1、 必须在 RongIMClient.connect(token,callback) 的成功回调中初始化 Upload 插件。

2、 RongUploadLib 初始化 RongIMLib.RongUploadLib.init([imageOpts],[fileOpts])

3、imageOpts 是初始化发送图片功能所需参数;fileOpts 是初始化发送文件功能所需参数, imageOptsfileOpts 属性相同值不同,说明如下:

{
  drop_element:'container',     // 拖拽容器 Id 。
  container:'container',        // 上传区域 DOM ID,默认是 browser_button 的父元素 。
  browse_button:'pickfiles'     // 上传选择的点选按钮,必需 。
}

4、示例代码

// 初始化 WebSDK

RongIMClient.init("z3f0sqki35v24");

// 设置消息监听,此处省略,消息监听请参考 Web 开发指南。

// 设置连接监听,此处省略,连接监听请参考 Web 开发指南。

// 连接融云服务器。

var token = "mKmyKqTSf7aNDinwAFMnz7NXKILeV3X0+C==";

RongIMClient.connect(token, {
  onSuccess: function(userId) {

    var imageOpts = {
      drop_element:'image_container',  
      container:'image_container',     
      browse_button:'image_pickfiles'
    }

    var fileOpts = {
      drop_element:'file_container',  
      container:'file_container',     
      browse_button:'file_pickfiles'
    }

    // 初始化 Upload 插件。
    RongIMLib.RongUploadLib.init(imageOpts,fileOpts);

    // 设置 RongUploadLib 监听器。
    RongIMLib.RongUploadLib.getInstance().setListeners({
      onFileAdded:function(file){
          // 触发时机:每个文件被添加后。
      },
      onBeforeUpload:function(file){
          // 触发时机:每个文件上传之前。
      },
      onUploadProgress:function(file){
          // 触发时机:每个文件上传中。
      },
      onFileUploaded:function(file,message,type){
          // 触发时机:每个文件上传完成。
      },
      onError:function(err, errTip){
          // 触发时机:每个文件上传失败。
      },
      onUploadComplete:function(){
          // 触发时机:所有文件上传完成。
      }
    });
  },
  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);
      }
});

2、开始上传

conversationType 会话类型。

targetId 目标 Id。

选择上传文件后需要触发开始上传文件方法 RongIMLib.RongUploadLib.getInstance().start(conversationType,targetId);

3、取消上传单个文件

fileId 可以在监听器 onFileAdded 方法中获取到。

RongIMLib.RongUploadLib.getInstance().cancel(fileId);

4、取消上传全部文件

RongIMLib.RongUploadLib.getInstance().cancelAll(function(){
  // do something
});

5、重构上传组件对象

使用场景:上传组件元素在页面中默认可能是隐藏的,RongUploadLib 对隐藏的 DOM 元素进行绑定事件是无效的,所以需要在显示元素后进行重新绑定。

此方法只针对默认隐藏的上传组件元素,反之则可忽略此方法。

var imageType = 'IMAGE',

    fileType = 'FILE';

RongIMLib.RongUploadLib.getInstance().reload(imageType,fileType);

6、销毁上传组件

销毁上传组件调用方式如下:

RongIMLib.RongUploadLib.getInstance().destroy();

7、发送截图

/**
 * @param  {string} bs64Str           由原图转换得来的 Base64
 * @param  {object} file              文件对象
 * @param  {number} conversationType  会话类型
 * @param  {string} targetId          目标 Id。
 * @param  {function}                 回掉函数 data:上传成功后返回的文件参数;message:发送消息成功后返回的消息对象;error:成功为 undefined,失败返回错误码。
 */
RongIMLib.RongUploadLib.getInstance().postImage(bs64Str,file,conversationType,targetId,function(data, message, error){
  // do something
});

8、图片压缩

默认使用 canvas 进行对图片压缩并返回 base64,不支持的 canvas 的情况需要自定义转换。

base64 方法,示例如下:

RongIMLib.RongUploadLib.imageCompressToBase64 = function(file,callback){

  var bs64 = '';

  // 转 base64 过程

  callback(bs64);
}

客服插件

1、引入 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> 标签。

2、初始化

在您 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:"****",
  });
}]);

3、插件样式设置

通过 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 示例

开源项目

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

GitHub 项目如下:


© 2016 RongCloud. All Rights Reserved. Version 2.8.5