IM SDK for HTML5 使用指南

SDK初始化

<script src="yim.core.js"></script>
<script src="yim.text.message.js"></script>
<script src="yim.voice.message.js"></script>
<script src="yim.amr.recorder.js"></script>
<script src="yim.wechat.recorder.js"></script>

// 初始化 YIM 实例，注册消息类型插件
var yim = new YIM({
    appKey: 'YOUMEXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX',
    userId: 'user',
    token: 'xxx',
    roomId: 'xxxxx',
    useMessageType: [TextMessage, VoiceMessage]
});

// 为语音消息插件注册录音类型插件
VoiceMessage.registerRecorder([AmrRecorder, WechatRecorder]);

// 发送文本消息示例
function sendText(text) {
    var msg = new TextMessage(text);
    yim.sendToRoom('xxxxx', msg);
}

// 发送语音消息示例
var voice;
function startRecord() {
    voice = new VoiceMessage();  // 新建实例
    voice.startRecord();         // 开始录音
}
function finishRecord() {
    voice.finishRecord();           // 结束录音
    yim.sendToRoom('xxxxx', voice); // 发送录音
}

// 接收消息示例
yim.on('message:receive:*', function (eventName, msg) {
    // 获得消息对象（TextMessage 或 VoiceMessage）
    var msgObj = msg.message;
    // 根据消息类型做出相应操作
    switch (msgObj.getType()) {
        // 文本消息 TextMessage
        case 'text':
            alert('收到文本消息: ' + msgObj.getText());
            break;
        // 语音消息 VoiceMessage
        case 'voice':
            msgObj.play();
            break;
    }
});

用户管理

用户登录

功能：指定用户ID登录IM系统。原型：

yim.login(userId, token, silent=false);

string userId: 由调用者分配，不可为空字符串，只可由字母或数字或下划线组成。
string token: 从服务端获取到的token，请参考《游密后台服务接口文档》->添加用户。
boolean silent: silent=false 若 true，则登录失败时不抛出错误（关闭 catch）。

返回：错误码，详细描述见错误码定义。
备注：这是一个异步操作，操作结果会通过回调监听接口返回:account.login。

yim.on('account.login', function () {
  console.log('已登录到 ' + yim.getMyUserId());
});

用户登出

功能：登出游密IM云服务器。原型：

yim.logout();

备注：这是一个异步操作，操作结果会通过回调监听接口返回:account.logout。

yim.on('account.logout', function () {
  console.log('退出登录');
});

被用户踢出通知

功能：同一个用户ID在多台设备上登录时，后登录的会把先登录的踢下线。原型：

yim.on('account.kickoff', function () {
  alert('你被踢下线了');
});

备注：这是一个异步操作，操作结果会通过回调监听接口返回:account.kickoff。

频道管理

加入频道

功能：加入频道进行群组聊天。原型：

yim.joinRoom(roomId);

string roomId: 请求加入的频道ID。

备注：这是一个异步操作，操作结果会通过回调监听接口返回:room.join:*。

yim.joinRoom(roomId).catch(function (e) {
  console.log('加入房间失败：' + e.name);
}).then(function(){
  // 加入房间成功...
});
// 事件绑定：加入房间
yim.on('room.join:*', function (eventName, roomId) {
  console.log('加入房间：' + roomId);
});

离开频道

功能：退出聊天频道。原型：

yim.leaveRoom(roomId);

string roomId: 请求加入的频道ID。

备注：这是一个异步操作，操作结果会通过回调监听接口返回:room.leave:*。

yim.leaveRoom(roomId).catch(function (e) {
  console.log('退出房间失败：' + e.name);
});
yim.on('room.leave:*', function (eventName, roomId) {
  console.log('退出房间：' + roomId);
});

消息管理

接收消息

在初始化核心 YIM 类的时候，应该使用 new YIM() 的 useMessageType 属性或者 yim.registerMessageType() 来注册所用到的消息类。例如：

yim.registerMessageType([
    TextMessage,
    VoiceMessage
]);

这个注册的目的是让 YIM 当接受到消息的时候从注册列表中判断所接受的消息类型，然后自动使用相应的消息类 new 新建相应的消息实例。

例如，若不注册 VoiceMessage，当 YIM 接收到语音消息时，将会无法识别消息，导致非法消息错误。

然后，接收消息需要监听：

yim.on('message:receive:*', function (eventName: string, msg: MessageObject) {
    // ...
});

发送文本消息

情景一：发送文本消息到指定频道(群聊)。原型：

yim.sendToRoom(roomId, msg, silent=false);

string roomId: 频道ID。
Message msg: 文本消息类，详见上面初始化示例。
boolean silent: silent=false 若 true，则发送失败时不抛出错误（关闭 catch）。

情景二：发送文本消息到指定用户(私聊)。原型：

yim.sendToUser(userId, msg, silent=false);

string userId: 用户ID。
Message msg: 文本消息类，详见上面初始化示例。
boolean silent: silent=false 若 true，则发送失败时不抛出错误（关闭 catch）。

返回：消息ID，与消息状态回调接口的strMessageID对应。
备注：这是一个异步操作，操作结果会通过回调接口返回，onSendMessageStatus。

发送语音消息


// 为语音消息插件注册录音类型插件
VoiceMessage.registerRecorder([AmrRecorder, WechatRecorder]);

// 发送语音消息示例
let voice: VoiceMessage;
function startRecord() {
    voice = new VoiceMessage('extra param');  // 新建实例
    voice.startRecord();         // 开始录音
}
function finishRecord() {
    voice.finishRecord();           // 结束录音
    yim.sendToRoom('xxxxx', voice); // 发送录音
}

// 接收消息示例
yim.on('message:receive:*', function (eventName: string, msg: MessageObject) {
    // 获得消息对象（TextMessage 或 VoiceMessage）
    const msgObj = msg.message;
    if (msgObj instanceof VoiceMessage) {
        alert('附加参数是：'+ msgObj.message.getExtra())
        msgObj.play();
    }
});

拉取聊天室消息记录

功能：可通过接口从服务器拉取频道最近的聊天历史记录。这个功能默认不开启，需要的请联系我们修改服务器配置。联系我们，可以通过专属游密支持群或者技术支持的大群。原型：

yim.queryRoomHistoryMessageByLastMsgid(roomId, count, direction , lastMsgid);

string roomId: 频道ID。
number count: 消息数量(单次最大返回30条，最大保存200条)。
number direction: 历史消息排序方向 0：按时间戳升序 1：按时间戳逆序。
string lastMsgid: 上一分页最后last_msgid值,第一页可传空。

使用示例如下(详细看SDK Demo)：

yim.queryRoomHistoryMessageByLastMsgid("benz",30,0,'').then(function(msgList) {
    console.log(msgList);
    var l = msgList.length;
    if(l>0){
        for (var i=0;i<l;i++)
        {
            console.log(msgList[i]);
        }
    }
}).catch(function (e) {
    console.log(e.name);
});

拉取私聊消息记录

功能：获取本地私聊消息历史记录，这是一个异步操作，操作结果会通过回调接口返回。原型：

yim.queryPrivateHistoryMessageByLastMsgid(userId, count, direction, lastMsgid, callback);

string userId: 私聊对象用户ID。
number count: 消息数量。
number direction: 历史消息排序方向 0：按时间戳升序 1：按时间戳逆序。
string lastMsgid: 上一分页最后last_msgid值,第一页可传空。
funciton callback: 查询私聊消息回调。

使用示例如下(详细看SDK Demo)：

yim.queryPrivateHistoryMessageByLastMsgid("sanji",30,0,0,queryPrivateHistoryMessage);
function queryPrivateHistoryMessage(msgList) {
    console.log(msgList);
    var l = msgList.length;
    if(l>0){
        for (var i= 0;i<l;i++)
        {
            console.log(msgList[i]);
        }
    }
}

获取最近私聊联系人列表

功能：该接口是根据本地历史消息记录生成的最近联系人列表，按最后聊天时间倒序排列。这是一个异步操作，操作结果会通过回调接口返回。原型：

yim.getHistoryContact(callback);

funciton callback: 查询私聊联系人回调。使用示例如下(详细看SDK Demo)：


yim.getHistoryContact(getContact);
function getContact(contactList){
var l = contactList.length;
var temp_arr = []
if(l>0){
    for (var i= 0;i<l;i++)
    {
        console.log((contactList[i]);
    }
}

}


### 删除最近私聊联系人
功能：该接口是删除最近私聊联系人。这是一个异步操作，操作结果会通过回调接口返回。
原型：
```javascript
yim.deleteHistoryContact(userId,callback);

string userId: 联系人用户Id。

funciton callback: 删除联系人回调。使用示例如下(详细看SDK Demo)：

yim.deleteHistoryContact('zoro3000',deleteContact);
function deleteContact(res) {
if(res["ErrorCode"]==0){
    console.log("删除联系人成功！");
}
}

选择语言

IM-HTML5

开发指引

API Guides

常见问题

服务器RestAPI