IM

IM

new IM(options)

Parameters:
Name Type Description
options Object

配置

Properties
Name Type Description
SDKAppID number

云通信应用的 SDKAppID

Methods

on(eventName, handler, contextopt)

监听事件。

注意:请在调用 login 接口前调用此接口监听事件,避免漏掉 SDK 派发的事件。

Example
let onTextMessageReceived = function(event) {
  event.data.forEach(function(message) {
    console.log('im | ' + (message.from || message.nick) + ' : ', message.payload.text);
  });
};
im.on(TWebLive.EVENT.IM_TEXT_MESSAGE_RECEIVED, onTextMessageReceived);
Parameters:
Name Type Attributes Description
eventName string

事件名称。所有的事件名称都存放在 TWebLive.EVENT 变量中,如需要查看可以使用 console.log(TWebLive.EVENT) 把所有的事件显示出来。事件列表

handler function

处理事件的方法,当事件触发时,会调用此handler进行处理。

context * <optional>

期望 handler 执行时的上下文

off(eventName, handler, contextopt)

取消监听事件。

Example
im.off(TWebLive.EVENT.IM_TEXT_MESSAGE_RECEIVED, onTextMessageReceived);
Parameters:
Name Type Attributes Description
eventName string

事件名称。所有的事件名称都存放在 TWebLive.EVENT 变量中,如需要查看可以使用 console.log(TWebLive.EVENT) 把所有的事件显示出来。事件列表

handler function

处理事件的方法,当事件触发时,会调用此handler进行处理。

context * <optional>

期望 handler 执行时的上下文

setLogLevel(level)

设置日志级别,低于 level 的日志将不会输出。

Example
im.setLogLevel(1);
Parameters:
Name Type Description
level Number

日志级别

  • 0 普通级别,日志量较多,接入时建议使用
  • 1 release级别,SDK 输出关键信息,生产环境时建议使用
  • 2 告警级别,SDK 只输出告警和错误级别的日志
  • 3 错误级别,SDK 只输出错误级别的日志
  • 4 无日志级别,SDK 将不打印任何日志

(async) createRoom(options) → {Promise}

创建直播间

Example
let promise = im.createRoom({
  name: '我的直播间X'
});
promise.then(function(imResponse) { // 创建成功
  console.log(imResponse.data.group.groupID); // 创建的群的 ID
}).catch(function(imError) {
  console.warn('im | createRoom | failed', imError); // 创建群组失败的相关信息
});
Parameters:
Name Type Description
options Object

参数

Properties
Name Type Attributes Default Description
name string

直播间名字

roomID string <optional>
''

直播间 ID

notification string <optional>
''

直播间公告,最长300字节

introduction string <optional>
''

直播间简介,最长240字节

avatar string <optional>
''

直播间群头像 url,最长100字节

Returns:
Type
Promise

enterRoom(roomID) → {Promise}

加入直播间

Example
let promise = im.enterRoom('AV1');
promise.then(function(imResponse) {
  switch (imResponse.data.status) {
    case TWebLive.TYPES.ENTER_ROOM_SUCCESS: // 加入直播间成功
      break;
    case TWebLive.TYPES.ALREADY_IN_ROOM: // 已经在直播间内
      break;
    default:
      break;
  }
}).catch(function(imError){
  console.warn('im | enterRoom | failed', imError); // 加入直播间失败的相关信息
});
Parameters:
Name Type Description
roomID string

直播间 ID

Returns:
Type
Promise

(async) exitRoom(roomID) → {Promise}

离开直播间

Example
let promise = im.exitRoom('AV1');
promise.then(function(imResponse) {
  // 退出直播间成功
}).catch(function(imError){
  console.warn('im | exitRoom | failed', imError); // 退出直播间失败的相关信息
});
Parameters:
Name Type Description
roomID string

直播间ID

Returns:
Type
Promise

login(options) → {Promise}

登录

Example
let promise = im.login({userID: 'your userID', userSig: 'your userSig'});
promise.then(function(res) {
  console.log(res.data); // 登录成功
  if (res.data.repeatLogin === true) {
    // 标识账号已登录,本次登录操作为重复登录
    console.log(imResponse.data.errorInfo);
  }
}).catch(function(imError) {
  console.warn('im | login | failed', imError); // 登录失败的相关信息
});
Parameters:
Name Type Description
options Object

登录参数

Properties
Name Type Description
userID string

用户 ID

userSig string

用户登录即时通信 IM 的密码,其本质是对 UserID 等信息加密后得到的密文。
具体生成方法请参见生成 UserSig

Returns:
Type
Promise

logout() → {Promise}

登出

Example
let promise = im.logout();
promise.then(function(imResponse) {
  console.log(imResponse.data); // 登出成功
}).catch(function(imError) {
  console.warn('im | logout | failed', imError);
});
Returns:
Type
Promise

(async) setMyProfile(options) → {Promise}

设置个人资料,如昵称和头像

Example
// 设置个人昵称和头像
let promise = im.setMyProfile({
  nick: '我的昵称',
  avatar: 'http(s)://url/to/image.jpg'
});
promise.then(function(imResponse) {
  console.log(imResponse.data); // 成功
}).catch(function(imError) {
  console.warn('im | setMyProfile | failed', imError); // 设置资料失败的相关信息
});
Parameters:
Name Type Description
options Object

参数

Properties
Name Type Description
nick string

昵称

avatar string

头像 url

Returns:
Type
Promise

getMyProfile() → {Promise}

获取个人资料,如昵称和头像

Example
let promise = im.getMyProfile();
promise.then(function(imResponse) {
  console.log('昵称:', imResponse.data.nick, '头像:', imResponse.data.avatar); // 个人资料 - Profile 实例
}).catch(function(imError) {
  console.warn('im | getMyProfile | failed', imError); // 获取个人资料失败的相关信息
});
Returns:
Type
Promise

(async) sendTextMessage(options) → {Promise}

聊天互动,在直播间发送文本消息

Example
let promise = im.sendTextMessage({
  roomID: 'AV1',
  priority: TWebLive.TYPES.MSG_PRIORITY_NORMAL,
  text: 'hello from TWebLive'
});
promise.then(function(imResponse) {
  console.log('im | sendTextMessage | OK', imResponse);
}).catch(function(imError) {
  console.log('im | sendTextMessage | failed', imError);
});
Parameters:
Name Type Description
options Object

消息参数

Properties
Name Type Attributes Default Description
roomID string

直播间ID

priority string <optional>
TWebLive.TYPES.MSG_PRIORITY_NORMAL

消息优先级

text string

文本消息内容

Returns:
Type
Promise

(async) sendCustomMessage(options) → {Promise}

在直播间发送自定义消息,如点赞、送礼等

Example
let promise = im.sendCustomMessage({
  roomID: 'AV1',
  priority:TWebLive.TYPES.MSG_PRIORITY_LOW, // 低优先级
  data: 'dianzan', // 用于标识该消息是点赞类型的自定义消息
  description: '',
  extension: ''
});
promise.then(function(imResponse) {
  console.log('im | sendCustomMessage | OK', imResponse);
}).catch(function(imError) {
  console.log('im | sendCustomMessage | failed', imError);
});
Parameters:
Name Type Description
options Object

消息参数

Properties
Name Type Attributes Default Description
roomID string

直播间ID

priority string <optional>
TWebLive.TYPES.MSG_PRIORITY_NORMAL

消息优先级

payload.data string

自定义消息的数据字段

payload.description string

自定义消息的说明字段

payload.extension string

自定义消息的扩展字段

Returns:
Type
Promise

(async) sendImageMessage(options) → {Promise}

在直播间发送图片消息。v1.1.0 起支持

Examples
// Web 端发送图片消息示例1 - 传入 DOM 节点
let promise = im.sendImageMessage({
  roomID: 'AV1',
  priority:TWebLive.TYPES.MSG_PRIORITY_LOW, // 低优先级
  file: document.getElementById('imagePicker'),
  onProgress: function(event) { console.log('file uploading:', event) }
});
promise.then(function(imResponse) {
  console.log('im | sendImageMessage | OK', imResponse);
}).catch(function(imError) {
  // 发送失败
  console.log('im | sendImageMessage | failed', imError);
});
// Web 端发送图片消息示例2- 传入 File 对象
// 先在页面上添加一个 id 为 "testPasteInput" 的消息输入框,如 <input type="text" id="testPasteInput" placeholder="截图后粘贴到输入框中" size="30" />
let file = null;
document.getElementById('testPasteInput').addEventListener('paste', function(e) {
  let clipboardData = e.clipboardData;
  let fileCopy;
  if (clipboardData && clipboardData.files && clipboardData.files.length > 0) {
    file = clipboardData.files[0];
    // 图片消息发送成功后,file 指向的内容可能被浏览器清空,如果接入侧有额外的渲染需求,可以提前复制一份数据
    fileCopy = file.slice();
  }

  if (typeof file === 'undefined') {
    console.warn('file 是 undefined,请检查代码或浏览器兼容性!');
    return;
  }
}

let promise = im.sendImageMessage({
  roomID: 'AV1',
  priority:TWebLive.TYPES.MSG_PRIORITY_LOW, // 低优先级
  file: file,
  onProgress: function(event) { console.log('file uploading:', event) }
});
promise.then(function(imResponse) {
  console.log('im | sendImageMessage | OK', imResponse);
}).catch(function(imError) {
  // 发送失败
  console.log('im | sendImageMessage | failed', imError);
});
Parameters:
Name Type Description
options Object

消息参数

Properties
Name Type Attributes Default Description
roomID string

直播间ID

priority string <optional>
TWebLive.TYPES.MSG_PRIORITY_NORMAL

消息优先级

payload.file HTMLInputElement | File | Object

用于选择图片的 DOM 节点(Web)或者 File 对象(Web)。SDK 会读取其中的数据并上传图片

Returns:
Type
Promise

(async) stopPush(options) → {Promise}

当主播停止推流时,使用此接口通知直播间的观众“主播已停止推流或直播已结束”

Example
im.stopPush({
  roomID: 'AV1',
  postscript: '欢迎下次再来呦'
});

// 观众端监听 TWebLive.EVENT.IM_PUSH_STOPPED
let onPushStopped = function(event) {
  console.log('postscript: ', event.data);
};
im.on(TWebLive.EVENT.IM_PUSH_STOPPED, onPushStopped);
Parameters:
Name Type Description
options Object

消息参数

Properties
Name Type Attributes Default Description
roomID string

直播间ID

postscript string <optional>
''

附言

Returns:
Type
Promise