简介

IMWeb SDK提供Web端完整解决方案,方便客户快速集成IM功能. SDK 提供的能力如下:

  • 注册
  • 登录
  • 用户会话
  • 联系人
  • 群组
  • 消息

开发准备

IMWeb SDK代码放在github.com开源,请从以下网址下载:

https://github.com/yun2win/yun2win-sdk-web/

Web目录结构如下:

  • js:包含所需全部js文件
    • core:核心库
    • widget:UI库
    • common:通用库
    • 3rd:第三方库
  • css:样式文件夹
  • images:图片文件夹
  • index.html:登录页面
  • register.html:注册页面
  • main.html:主页面

注册

调用以下代码进行用户注册

                        
    /**
    * 注册
    * @param account:帐号信息,常见如邮箱,手机号码等。
    * @param pwd:密码
    * @param name:名称
    * @returns user:{
        id:"1",
        name:"例君",
        account:"audd",
        avatarUrl:""
    }
    */
    Users.getInstance().remote.register(account, pwd, name, function(err, user){
        if(err){
            alert("注册失败:" + err);
            return;
        }
        alert("注册成功");
        window.location.href = '../web/index.html';
    });
                        
                    

登录

调用以下代码进行登录

                        
Users.getInstance().remote.login(account, pwd, function(err){
    if(err){
        alert("登录失败:" + err);
        return;
    }
    window.location.href = '../web/main.html';
})
                        
                    

提醒

登录成功后会将用户登录信息保存到localStorage,供载入main.html后调用。

用户查找

根据帐户查找用户。

                        
    /**
    * 根据帐户查找用户(单个),
    * @param account:目前不支持模糊查找,需要完整的account。
    * @param token:如果用户已经登陆,此处设为null,否则需要设定值
    * @returns user:{
        id:"1",
        name:"例君",
        account:"audd",
        avatarUrl:""
    }
    */
    Users.getInstance().remote.search(account, token, function(err,user){
        if(user){
            //查到了用户
        }
    });
                        
                    

当前用户

进入main.html后,调用以下代码初始化当前用户

                        
var currentUser = Users.getInstance().getCurrentUser();
                        
                    

属性

当前用户对象包含以下属性:

                        
var CurrentUser = function(obj){
    this.appKey = obj['key'];
    this.secret = obj['secret'];
    this.token = obj['token'];
    this.imToken = obj['imToken'];//用于连接y2wIM消息推送服务器
    this.userConversations = new UserConversations(this);//用户会话对象
    this.contacts = new Contacts(this);//联系人对象
    this.sessions = new Sessions(this);//会话对象
    this.userSessions = new UserSessions(this);//群组对象
    this.attchments = new Attachments(this);//附件对象
    this.remote = currentUserRemoteSingleton.getInstance(this);//远程方法封装对象
    this.currentSession;//当前会话对象
    this.y2wIMBridge;//消息推送代理对象
}
                        
                    

远程方法

当前用户对象包含以下远程方法:

  • 更新当前用户信息
                                    
    currentUser.remote.store(function(err){
        if(err){
            alert("更新失败:" + err);
            return;
        }
        alert("更新成功");
    })
                                    
                                
  • 同步获取用于连接y2wIM消息推送服务器的凭证
                                    
    currentUser.remote.syncIMToken(function(err){
        if(err){
            alert("同步失败:" + err);
            return;
        }
        alert("同步成功");
    })
                                    
                                

初始化

当前用户对象初始化时会做以下工作:

  1. 创建用户会话管理对象:userConversations
  2. 创建联系人管理对象:contacts
  3. 创建群组管理对象:userSessions
  4. 创建会话管理对象:sessions
  5. 使用localStorage中的数据创建/填充以下对象:
    • 当前用户
    • 当前用户所有相关的用户列表(联系人,群成员包含的用户信息)
    • 用户会话列表
    • 联系人列表
    • 群组列表
    • 会话及会话成员列表

用户会话

用户会话由服务端管理,客户端不能主动创建,只需通过同步获取最新的用户会话信息,用户会话包含如下对象:

  • 用户会话管理对象UserConversations:包含同步时间戳,并负责管理用户会话列表
  • 用户会话对象UserConversation:包含用户会话信息,并负责管理其下的消息

UserConversations

用户会话管理对象,管理列表,查询与同步等工作

属性

UserConversations包含以下属性:

                        
var UserConversations = function(user){
    this.user = user;//用户会话管理对象从属于某一用户,此处保存对用户的引用,通常为当前用户
    this.updatedAt = globalMinDate;//同步时间戳,同步时使用此时间戳获取之后的数据
    this.remote = new userConversationsRemote(this);//远程方法封装对象
}
                        
                    

方法

UserConversations包含以下本地方法

  • 初始化,用于从localStorage获取本地数据并填充用户会话对象集合
                                    
    userConversations.init()
                                    
                                
  • 获取用户会话
                                    
    /**
    * 获取用户会话
    * @param type['p2p'|'group']:会话场景类型
    * @param targetId[user.id|session.id]会话目标Id
    * type=='p2p':targetId=user.id(对方用户);
    * type=='group':targetId=session.id(会话id)
    * @returns userConversation
    */
    userConversations.get(type, targetId)
                                    
                                
  • 获取用户会话列表
                                    
    /**
    * 获取用户会话列表
    * @param type['p2p'|'group'|undefined]
    * @returns [userConversation]
    */
    userConversations.getUserConversations(type)
                                    
                                

UserConversations包含以下远程方法

  • 同步用户会话
                                    
    userConversations.remote.sync(function(err){
        if(err){
            alert("同步失败:" + err);
            return;
        }
        alert("同步成功");
    })
                                    
                                
  • 更新用户会话信息
                                    
    /**
    * 更新用户会话信息
    * @param userConversation
    * @param cb
    */
    userConversations.remote.store(userConversation, function(err){
        if(err){
            alert("更新失败:" + err);
            return;
        }
        alert("更新成功");
    })
                                    
                                
  • 删除用户会话
                                    
    /**
    * 删除用户会话
    * @param userConversationId:用户会话id
    * @param cb
    */
    userConversations.remote.remove(userConversationId, function(err){
        if(err){
            alert("删除失败:" + err);
            return;
        }
        alert("删除成功");
    })
                                    
                                

UserConversation

用户会话对象,包含用户会话信息,并管理该用户会话下的消息

属性

UserConversation包含以下属性:

                        
var UserConversation = function(userConversations, obj){
    this.userConversations = userConversations;//用户会话从属于用户会话管理对象,此处保存对其的引用
    this.id = obj['id'];//用户会话id
    this.name = obj['name'];//名称
    this.avatarUrl = obj['avatarUrl'] || ' ';//头像
    this.targetId = obj['targetId'];//会话目标Id
    this.unread = obj['unread'];//未读数量
    this.type = obj['type'];//场景类型['p2p','group']
    this.isDelete = obj['isDelete'];//删除标志
    this.createdAt = new Date(obj['createdAt']).getTime();//创建时间
    this.updatedAt = new Date(obj['updatedAt']).getTime();//更新时间
    this.visiable = obj['visiable'];//是否显示
    this.top = obj['top'];//置顶标志
    this.lastMessage = obj['lastMessage'];//最近一条消息内容
}
                        
                    

方法

UserConversation包含以下方法

  • 获取名称
                                    
    /**
    * 获取名称
    * @returns name
    */
    userConversation.getName()
                                    
                                
  • 获取头像
                                    
    /**
    * 获取头像
    * @returns url
    */
    userConversation.getAvatarUrl()
                                    
                                
  • 获取目标会话
                                    
    userConversation.getSession(function(err, session){
        if(err){
            alert('获取session失败:' + err);
            return;
        }
        alert('获取session成功');
    })
                                    
                                
  • 同步消息
                                    
    /**
    * 同步消息
    * @param force:强制同步
    * @param cb
    */
    userConversation.syncMessages(force, function(err, messages){
        if(err){
            alert('同步失败:' + err);
            return;
        }
        alert('同步成功');
    })
                                    
                                
  • 获取历史消息
                                    
    /**
    * 获取历史纪录
    * @param cb
    */
    userConversation.getLastMessages(function(err, messages){
        if(err){
            alert('获取历史消息失败:' + err);
            return;
        }
        alert('获取历史消息成功');
    })
                                    
                                
  • 清除已读数量
                                    
    userConversation.clearUnread()
                                    
                                

联系人

联系人包含如下对象:

  • 联系人管理对象Contacts:包含同步时间戳,并负责管理联系人列表
  • 联系人对象Contact:包含联系人信息

Contacts

联系人管理对象,管理列表,查询与同步等工作

属性

Contacts包含以下属性:

                        
var Contacts = function(user){
    this.user = user;//联系人管理对象从属于某一用户,此处保存对用户的引用,通常为当前用户
    this.updatedAt = globalMinDate;//同步时间戳,同步时使用此时间戳获取之后的数据
    this.remote = new contactsRemote(this);//远程方法封装对象
}
                        
                    

方法

Contacts包含以下本地方法

  • 初始化,用于从localStorage获取本地数据并填充联系人对象集合
                                    
    contacts.init()
                                    
                                
  • 获取联系人
                                    
    /**
    * 获取联系人
    * @param userId:用户id
    * @returns contact
    */
    contacts.get(userId)
                                    
                                
  • 获取联系人列表
                                    
    /**
    * 获取联系人列表
    * @returns [contact]
    */
    contacts.getContacts()
                                    
                                

Contacts包含以下远程方法

  • 同步联系人
                                    
    contacts.remote.sync(function(err){
        if(err){
            alert("同步失败:" + err);
            return;
        }
        alert("同步成功");
    })
                                    
                                
  • 添加联系人
                                    
    /**
    * 添加联系人
    * @param userId:用户id
    * @param name:用户姓名
    * @param cb
    */
    contacts.remote.add(userId, name, function(err){
        if(err){
            alert("添加联系人失败:" + err);
            return;
        }
        alert("添加联系人成功");
    })
                                    
                                

    提醒

    添加联系人后使用同步方法重新获取联系人

  • 更新联系人信息
                                    
    /**
    * 更新联系人信息
    * @param contact
    * @param cb
    */
    contacts.remote.store(contact, function(err){
        if(err){
            alert("更新失败:" + err);
            return;
        }
        alert("更新成功");
    })
                                    
                                
  • 删除联系人
                                    
    /**
    * 删除联系人
    * @param contactId:联系人id
    * @param cb
    */
    contacts.remote.remove(contactId, function(err){
        if(err){
            alert("删除失败:" + err);
            return;
        }
        alert("删除成功");
    })
                                    
                                

Contact

联系人对象

属性

Contact包含以下属性:

                        
var Contact = function(contacts, obj){
    this.contacts = contacts;//联系人从属于联系人管理对象,此处保存对其的引用
    this.id = obj['id'];//联系人id
    this.name = obj['name'];//名称
    this.pinyin = obj['pinyin'];//拼音
    this.title = obj['title'];//备注,修改联系人备注,会在会话及消息中显示备注的名称
    this.titlePinyin = obj['titlePinyin'];//备注拼音
    this.remark = obj['remark'];//其它信息
    this.isDelete = obj['isDelete'];//删除标志
    this.createdAt = new Date(obj['createdAt']).getTime();//创建时间
    this.updatedAt = new Date(obj['updatedAt']).getTime();//更新时间
    this.userId = obj['userId'];//用户id
    this.avatarUrl = obj['avatarUrl'] || ' ';//头像
}
                        
                    

方法

Contact包含以下本地方法

  • 获取名称
                                    
    /**
    * 获取名称
    * @returns name
    */
    contact.getName()
                                    
                                
  • 获取头像
                                    
    /**
    * 获取头像
    * @returns url
    */
    contact.getAvatarUrl()
                                    
                                
  • 获取拼音
                                    
    /**
    * 获取拼音
    * @returns pinyin
    */
    contact.getPinYin()
                                    
                                

群组

群组在项目中定义为"收藏到群组列表的多人会话",群组包含如下对象:

  • 群组管理对象UserSessions:包含同步时间戳,并负责管理群组列表
  • 群组对象UserSession:包含群组信息

UserSessions

群组管理对象,管理列表,查询与同步等工作

属性

UserSessions包含以下属性:

                        
var UserSessions = function(user){
    this.user = user;//群组管理对象从属于某一用户,此处保存对用户的引用,通常为当前用户
    this.updatedAt = globalMinDate;//同步时间戳,同步时使用此时间戳获取之后的数据
    this.remote = new userSessionsRemote(this);//远程方法封装对象
}
                        
                    

方法

UserSessions包含以下本地方法

  • 初始化,用于从localStorage获取本地数据并填充群组对象集合
                                    
    userSessions.init()
                                    
                                
  • 获取群组
                                    
    /**
    * 获取群组
    * @param sessionId:会话Id
    * @returns userSession
    */
    userSessions.get(sessionId)
                                    
                                
  • 获取群组列表
                                    
    /**
    * 获取群组列表
    * @returns [userSession]
    */
    userSessions.getUserSessions()
                                    
                                

UserSessions包含以下远程方法

  • 同步群组
                                    
    /**
    * 同步群组
    * @param cb
    */
    userSessions.remote.sync(function(err){
        if(err){
            alert("同步失败:" + err);
            return;
        }
        alert("同步成功");
    })
                                    
                                
  • 收藏群组
                                    
    /**
    * 收藏群组
    * @param sessionId:会话Id
    * @param name:群组名称
    * @param avatarUrl:群组头像
    * @param cb
    */
    userSessions.remote.add(sessionId, name, avatarUrl, function(err){
        if(err){
            alert("收藏群组失败:" + err);
            return;
        }
        alert("收藏群组成功");
    })
                                    
                                
  • 取消收藏群组
                                    
    /**
    * 取消收藏群组
    * @param userSessionId:群组id
    * @param cb
    */
    userSessions.remote.remove(userSessionId, function(err){
        if(err){
            alert("取消收藏群组失败:" + err);
            return;
        }
        alert("取消收藏群组成功");
    })
                                    
                                

UserSession

群组对象,包含群组信息

属性

UserSession包含以下属性:

                        
var UserSession = function(userSessions, obj){
    this.userSessions = userSessions;//群组从属于群组管理对象,此处保存对其的引用
    this.id = obj['id'];//群组id
    this.sessionId = obj['sessionId'];//会话id
    this.name = obj['name'];//名称
    this.isDelete = obj['isDelete'];//删除标志
    this.createdAt = new Date(obj['createdAt']).getTime();//创建时间
    this.updatedAt = new Date(obj['updatedAt']).getTime();//更新时间
    this.avatarUrl = obj['avatarUrl'] || ' ';//头像
}
                        
                    

方法

UserSession包含以下本地方法

  • 获取头像
                                    
    /**
    * 获取头像
    * @returns url
    */
    userSession.getAvatarUrl()
                                    
                                

Session

Session:会话

  • 会话管理对象Sessions:负责管理会话集合
  • 会话对象Session:包含会话信息,并负责管理该会话的成员与消息

Sessions

会话管理对象,管理会话集合

属性

Sessions包含以下属性:

                        
var Sessions = function(user){
    this.user = user;//群组管理对象从属于某一用户,此处保存对用户的引用,通常为当前用户
    this.remote = new contactsRemote(this);//远程方法封装对象
}
                        
                    

方法

获取会话

                        
/**
* 获取会话
* @param targetId:会话目标id
* type=='p2p':targetId=user.id(对方用户);
* type=='group':targetId=session.id(会话id)
* @param type['p2'|'group']:会话场景类型
* @param cb
*/
sessions.get(targetId, type, function(err, session){
    if(err){
        alert("获取会话失败:" + err);
        return;
    }
    alert("获取会话成功");
})
                        
                    

重要

  1. 此方法先在本地搜索,如果本地不存在将去服务器获取,此方法必定会返回session
  2. 获取会话将同时将返回会话成员

Sessions包含以下本地方法

  • 初始化,用于从localStorage获取本地数据并填充会话对象集合
                                    
    sessions.init()
                                    
                                
  • 根据SessionId获取本地会话
                                    
    /**
    * 根据SessionId获取本地会话
    * @param id
    * @returns {*}
    */
    sessions.getById(id);
                                    
                                
  • 获取会话目标id
                                    
    /**
    * 获取会话目标id
    * type=='p2p':targetId=user.id(对方用户);
    * type=='group':targetId=session.id(会话id)
    * @param id:会话Id
    * @param type['p2p|'group']:会话场景类型
    * @returns targetId
    */
    sessions.getTargetId(id, type)
                                    
                                

Sessions包含以下远程方法

  • 同步会话
                                    
    /**
    * 同步会话
    * @param targetId:会话目标id
    * type=='p2p':targetId=user.id(对方用户);
    * type=='group':targetId=session.id(会话id)
    * @param type['p2p|'group']:会话场景类型
    * @param type
    * @param cb
    */
    sessions.remote.sync(targetId, type, function(err){
        if(err){
            alert("同步失败:" + err);
            return;
        }
        alert("同步成功");
    })
                                    
                                

    重要

    同步会话将同时同步会话成员

  • 添加会话
                                    
    /**
    * 添加会话
    * @param type:['p2p'|'group']:会话场景类型
    * @param name:名称
    * @param secureType['public'|'private']:安全类型,通常使用private
    * @param avatarUrl:头像
    * @param cb
    */
    sessions.remote.add(type, name, secureType, avatarUrl, function(err, session){
        if(err){
            alert("添加会话失败:" + err);
            return;
        }
        alert("添加会话成功");
    })
                                    
                                
  • 删除会话
                                    
    /**
    * 删除会话
    * @param session
    * @param cb
    */
    sessions.remote.remove(session, function(err){
        if(err){
            alert("删除会话失败:" + err);
            return;
        }
        alert("删除会话成功");
    })
                                    
                                

Session

会话对象,包含会话信息,并负责管理该会话的成员与消息

属性

Session包含以下属性:

                        
var Session = function(sessions, obj){
    this.sessions = sessions;//会话从属于会话管理对象,此处保存对其的引用
    this.id = obj['id'];//会话id
    this.name = obj['name'];//名称
    this.nameChanged = obj['nameChanged'];//名称修改标记,默认未修改时,会话名称由会话成员名称组合合成
    this.secureType = obj['secureType'];//会话安全类型
    this.type = obj['type'];//场景类型
    this.description = obj['description'];//描述
    this.avatarUrl = obj['avatarUrl'] || ' ';//头像
    this.createdAt = new Date(obj['createdAt']).getTime();//创建时间
    this.updatedAt = new Date(obj['updatedAt']).getTime();//更新时间
    this.members = new SessionMembers(this);//会话成员管理对象
    this.messages = new Messages(this);//消息管理对象
}
                        
                    

方法

Session包含以下本地方法

  • 获取用户会话对象
                                    
    /**
    * 获取用户会话对象
    * @returns userConversation
    */
    session.getConversation()
                                    
                                

SessionMember

SessionMember:会话成员

  • 会话成员管理对象SessionMembers:负责管理会话成员同步,增删等操作
  • 会话成员对象SessionMember:包含会话成员信息

SessionMembers

会话成员管理对象,负责管理会话成员同步,增删等操作

属性

SessionMembers包含以下属性:

                        
var SessionMembers = function(session){
    this.session = session;//会话成员管理对象从属于某一会话,此处保存对会话的引用
    this.createdAt = globalMinDate;//会话成员创建时间,用于推送消息
    this.updatedAt = globalMinDate;//同步时间戳,同步时使用此时间戳获取之后的数据
    this.remote = new contactsRemote(this);//远程方法封装对象
}
                        
                    

方法

SessionMembers包含以下本地方法

  • 初始化,用于从localStorage获取本地数据并填充会话对象集合
                                    
    sessionMembers.init()
                                    
                                
  • 获取会话成员
                                    
    /**
    * 获取会话成员
    * @param userId:用户id
    * @returns sessionMember
    */
    sessionMembers.getMember(userId);
                                    
                                
  • 获取会话成员列表
                                    
    /**
    * 获取会话成员列表
    * @returns [sessionMember]
    */
    sessionMembers.getMembers()
                                    
                                
  • 获取p2p会话相对方的会话成员对象
                                    
    /**
    * 获取p2p会话相对方的会话成员对象
    * @param userId
    * @returns sessionMember
    */
    sessionMembers.getP2POtherSideMember(userId)
                                    
                                

SessionMembers包含以下远程方法

  • 同步会话成员
                                    
    sessionMembers.remote.sync(function(err){
        if(err){
            alert("同步失败:" + err);
            return;
        }
        alert("同步成功");
    })
                                    
                                
  • 添加会话成员
                                    
    /**
    * 添加会话成员
    * @param userId:用户id
    * @param name:用户名称
    * @param role['master'|'admin'|'user']:会话成员角色,master:群主;admin:管理员;user:一般成员
    * @param avatarUrl:头像
    * @param status['active'|'封禁']:用户状态,active:有效;inactive:封禁
    * @param cb
    */
    sessionMembers.remote.add(userId, name, role, avatarUrl, status, function(err){
        if(err){
            alert("添加会话成员失败:" + err);
            return;
        }
        alert("添加会话成员成功");
    })
                                    
                                
  • 删除会话成员
                                    
    /**
    * 删除会话成员
    * @param memberId:会话成员id
    * @param cb
    */
    sessionMembers.remote.remove(memberId, function(err){
        if(err){
            alert("删除会话成员失败:" + err);
            return;
        }
        alert("删除会话成员成功");
    })
                                    
                                

SessionMember

会话成员对象,包含会话成员信息

属性

SessionMember包含以下属性:

                        
var SessionMember = function(sessionMembers, obj){
    this.sessionMembers = sessionMembers;//会话成员从属于会话成员管理对象,此处保存对其的引用
    this.id = obj['id'];//会话成员id
    this.name = obj['name'];//会话成员名称
    this.pinyin = obj['pinyin'];//会话成员拼音
    this.createdAt = new Date(obj['createdAt']).getTime();//创建时间
    this.updatedAt = new Date(obj['updatedAt']).getTime();//更新时间
    this.userId = obj['userId'];//用户id
    this.isDelete = obj['isDelete'];//删除标志
    this.role = obj['role'];//角色
    this.status = obj['status'];//状态
}
                        
                    

方法

SessionMember包含以下本地方法

  • 获取头像
                                    
    /**
    * 获取头像
    * @returns url
    */
    sessionMember.getAvatarUrl()
                                    
                                

消息

消息包含如下对象:

  • 消息管理对象Messages:包含同步时间戳,负责管理消息列表
  • 消息对象Message:包含消息信息

Messages

消息管理对象,包含同步时间戳,负责管理消息列表

重要

Web端localStorage不缓存消息,每次登入从服务器获取

属性

Messages包含以下属性:

                        
var Messages = function(session){
    this.session = session;//消息管理对象从属于某一会话,此处保存对会话的引用
    this.more = true;//是否有更多历史消息,用于获取历史数据
    this.updatedAt = globalMinDate;//同步时间戳,同步时使用此时间戳获取之后的数据
    this.topDate = globalMaxDate;//当前会话最早一条消息时间,用于获取历史数据
    this.sessionUpdatedAt = globalMinDate;//会话更新时间,用于判断是否需要同步会话
    this.remote = new messagesRemote(this);//远程方法封装对象
}
                        
                    

方法

Messages包含以下本地方法

  • 获取消息数量
                                    
    /**
    * 获取消息数量
    * @returns {Number}
    */
    messages.count()
                                    
                                
  • 获取消息列表
                                    
    /**
    * 获取消息列表
    * @returns [messages]
    */
    messages.getMessages()
                                    
                                
  • 创建消息对象
                                    
    /**
    * 创建消息对象
    * @param obj
    * @returns message
    */
    messages.createMessage(obj)
                                    
                                

Messages包含以下远程方法

  • 保存消息
                                    
    messages.remote.store(message, function(err, message){
        if(err){
            alert("保存失败:" + err);
            return;
        }
        alert("保存成功");
    })
                                    
                                
  • 同步消息
                                    
    messages.remote.sync(function(err, list){
        if(err){
            alert("同步失败:" + err);
            return;
        }
        alert("同步成功");
    })
                                    
                                
  • 获取历史消息
                                    
    messages.remote.getLastMessages(function(err, list){
        if(err){
            alert("获取历史消息失败:" + err);
            return;
        }
        alert("获取历史消息成功");
    })
                                    
                                

    提醒

    获取历史消息以topDate时间向上一次获取20条数据

Message

消息对象,包含消息信息

属性

Message包含以下属性:

                        
var Message = function(messages, obj){
    this.messages = messages;//消息对象从属于消息管理对象,此处保存对其的引用
    this.id = obj['id'] || guid();//消息id
    this.sender = obj['sender'];//发送者id
    this.from;//发送者
    this.to;//接收者
    this.type = obj['type'];//消息类型["text"|"image"|"video"|"audio"|"file"]
    this.content = JSON.parse(obj['content']);//消息内容
    this.createdAt;//创建时间
    this.updatedAt;//更新时间
    this.isDelete = obj['isDelete'];//删除标志
    this.status = obj['status'] || '';//消息保存状态["storing"|"stored"|"storefailed"]
}
                        
                    

重要

  1. from(消息发送者)与to(消息接受者)
    this.messages.session.type=='p2p': from=user(发送方);to=user(接收方)
    this.messages.session.type=='group': from=sessionMember(发送方);to=session(会话)
  2. status(消息保存状态):只在保存消息时更新此属性,以便UI的状态显示,同步的消息不具备此属性

y2wIM推送服务

y2wIM推送服务包含如下对象

  • y2wIM:负责处理推送服务器的连接,重连,消息推送与接收等任务
  • y2wIMBridge:负责连接y2wIM与业务代码的桥,包含发送特定消息,接收消息队列处理,连接与发送错误处理等工作

y2wIM

推送服务SDK,负责处理推送服务器的连接,重连,消息推送与接收等工作

连接

                        
var opts = {
    appKey: user.appKey,
    token: user.imToken,//用于连接y2wIM消息推送服务器的token,
    uid: user.id.toString(),//用户id
    onConnectionStatusChanged: onConnectionStatusChanged,//连接状态变更回调方法
    onMessage: onMessage//接收消息回调方法
};
var client = y2wIM.connect(opts);
                        
                    

提醒

token:连接消息推送服务器的token,使用currentUser.remote.syncIMToken()获取

client:连接客户端对象,用于处理推送消息,更新会话,接收消息

连接状态:

                        
y2wIM.connectionStatus = {
    connecting: 0,//连接中
    connected: 1,//已连接
    reconnecting: 2,//重连中
    networkDisconnected: 3,//网络断开
    disconnected: 100//连接断开
}
                        
                    

连接状态变更:

                        
/**
* 连接状态变更处理
* @param status:连接状态
* @param msg:连接信息
*/
var onConnectionStatusChanged = function (status, msg) {
    switch (status) {
        case y2wIM.connectionStatus.connecting://连接中
            console.log('connecting');
            break;
        case y2wIM.connectionStatus.connected://已连接
            console.log('connected');
            break;
        case y2wIM.connectionStatus.reconnecting://重连中,msg为重连次数
            console.log('reconnecting(' + msg + ')');
            break;
        case y2wIM.connectionStatus.networkDisconnected://网络断开
            console.warn('unable to connect to the network');
            break;
        case y2wIM.connectionStatus.disconnected://连接断开,msg为连接返回码
            onDisconnected(msg);//调用断开连接方法
            break;
        default:
            break;
    }
};
                        
                    

连接返回码:

                        
y2wIM.connectionReturnCode = {
    unacceptableProtocolVersion: 3,//协议错误
    uidIsInvalid: 4,//用户id无效
    tokenIsInvalid: 5,//imToken无效
    tokenHasExpired: 6,//imToken过期
    appKeyIsInvalid: 7,//appKey无效
    kicked: 10,//被踢出,同类型设备重复登录时,之前的设备收到被踢出信息
    serverUnavailable: 99,//服务器不可达
    serverInternalError: 100//服务器内部错误
}
                        
                    

断开连接:

                        
/**
* 断开连接处理
* @param returnCode:连接返回码
*/
var onDisconnected = function (returnCode) {
    switch (returnCode) {
        case y2wIM.connectionReturnCode.uidIsInvalid://用户id无效
            console.error('disconnected: uid is invalid');
            break;
        case y2wIM.connectionReturnCode.tokenIsInvalid://imToken无效
            console.error('disconnected: token is invalid');
            break;
        case y2wIM.connectionReturnCode.tokenHasExpired://imToken过期
            console.error('disconnected: token has expired');
            break;
        case y2wIM.connectionReturnCode.kicked://被踢出,同类型设备重复登录时,之前的设备收到被踢出信息
            console.warn('disconnected: another divice has connected');
            break;
    }
};
                        
                    

重要

y2wIM.connect(opts)连接推送服务器只负责建立连接,连接状态变更时回调onConnectionStatusChanged方法,状态处理由y2wIMBridge负责

推送消息

                        
/**
* 推送消息
* @param imSession:推送目标会话
* imSession:{
*    id:session.type + '_' + session.id
*    mts:session.members.createdAt
* }
* @param message:推送内容
* @param onSendMessage:推送消息回调方法
*/
client.sendMessage(imSession, message, onSendMessage);
                        
                    

imSession

  • 推送消息时,imSession只有两个属性,id和mts
  • id表示将消息推送到哪个会话
  • mts(membersTimeStamp)是会话成员时间戳,会话成员变更时,此时间戳会更新,当发送消息时,推送服务器根据mts判断推送服务器保存的成员与业务服务器会话成员是否一致

message:推送内容

  • 为保证业务数据的安全性,yun2win推送服务默认只推送同步通知,不推送任何实质内容
  • message也可由用户自定义推送任何信息

sendReturnCode:消息推送返回码

                        
y2wIM.sendReturnCode = {
    success: 20,//推送成功
    timeout: 21,//推送超时
    cmdIsInvalid: 22,//推送命令无效
    sessionIsInvalid: 23,//会话无效
    sessionIdIsInvalid: 24,//会话id无效
    sessionMTSIsInvalid: 25,//会话成员时间戳无效
    sessionOnServerIsNotExist: 26,//推送服务器不存在此会话
    sessionMTSOnClientHasExpired: 27,//客户端会话成员时间戳过期
    sessionMTSOnServerHasExpired: 28,//推送服务器会话成员时间戳过期
    sessionMembersIsInvalid: 29,//推送服务器会话成员无效
    invalidFormatOfJSONContent: 30,//推送内容是无效的JSON格式
    sessionMembersIsNull: 31//会话成员不存在
}
                        
                    

onSendMessage:推送消息回调方法

                        
var onSendMessage = {
    onSuccess: function () {
        console.log('send success');//推送成功
    },
    onFailure: function (returnCode) {//推送失败
        switch (returnCode) {
            case y2wIM.sendReturnCode.sessionIsInvalid://会话无效
                console.error('send error: session is invalid');
                break;
            case y2wIM.sendReturnCode.sessionIdIsInvalid://会话id无效
                console.error('send error: session.id is invalid');
                break;
            case y2wIM.sendReturnCode.sessionMTSIsInvalid://会话成员时间戳无效
                console.error('send error: session.mts is invalid');
                break;
            case y2wIM.sendReturnCode.cmdIsInvalid://推送命令无效
                console.error('send error: cmd is invalid');
                break;
            case y2wIM.sendReturnCode.invalidFormatOfJSONContent://推送内容是无效的JSON格式
                console.error('send error: send content\'s format is not a valid json');
                break;
            case y2wIM.sendReturnCode.sessionMembersIsNull://会话成员不存在
                console.error('send error: session.members is not null');
                break;
            case y2wIM.sendReturnCode.sessionOnServerIsNotExist://推送服务器不存在此会话,客户端需要更新会话成员到推送服务器
                console.error('send error: session on server is not exist');
                break;
            case y2wIM.sendReturnCode.sessionMTSOnClientHasExpired://客户端会话成员时间戳过期,客户端需要同步会话及会话成员
                console.error('send error: session mts on client has expired');
                break;
            case y2wIM.sendReturnCode.sessionMTSOnServerHasExpired://推送服务器会话成员时间戳过期,客户端需要更新会话成员到推送服务器
                console.error('send error: session mts on server has expired');
                break;
        }
    }
}
                        
                    

更新会话

                        
/**
* 更新会话
* @param imSession:更新的目标会话
* imSession:{
*    id:session.type + '_' + session.id
*    mts:session.members.createdAt
*    members:[
*       {
*           uid:user1.id,
*           isDel:[true|false]
*       },
*       {
*           uid:user2.id,
*           isDel:[true|false]
*       }
*    ]
* }
* @param message:推送内容
* @param onUpdateSession:更新会话回调方法
*/
client.updateSession(imSession, message, onUpdateSession);
                        
                    

imSession

  • 推送服务器不保存任何业务数据,不包含会话成员的个人信息,但必须同步业务服务器中会话成员的id,以便推送到位
  • 更新会话时,imSession需要额外的members属性,members是一个数组,存放多个会话成员信息
  • 更新会话操作只有在以下两种情况下调用
    1. 推送服务器不存在此会话,此时需要将当前会话所有成员更新到推送服务器
    2. 推送服务器mts过期,此时推送服务器将返回服务端mts,客户端需要将此时间之后的成员变更(新增/删除)更新到推送服务器

message:推送内容,更新会话操作是在推送消息时发生mts错误后调用的,updateSession支持将之前发送的消息本体传入,在onUpdateSession回调时将message返回给客户端,以便重新发送此消息

onUpdateSession:更新会话回调方法

                        
var onUpdateSession = {
    onSuccess: function () {//更新会话成功
        console.log('update session success');
    },
    onFailure: function (returnCode) {//更新会话失败
        switch (returnCode) {
            case y2wIM.sendReturnCode.sessionIsInvalid://会话无效
                console.error('update session error: session is invalid');
                break;
            case y2wIM.sendReturnCode.sessionIdIsInvalid://会话id无效
                console.error('update session error: session.id is invalid');
                break;
            case y2wIM.sendReturnCode.sessionMTSIsInvalid://会话成员时间戳无效
                console.error('update session error: session.mts is invalid');
                break;
            case y2wIM.sendReturnCode.cmdIsInvalid://推送命令无效
                console.error('update session error: cmd is invalid');
                break;
            case y2wIM.sendReturnCode.invalidFormatOfJSONContent://推送内容是无效的JSON格式
                console.error('send error: send content\'s format is not a valid json');
                break;
            case y2wIM.sendReturnCode.sessionMTSOnClientHasExpired://客户端会话成员时间戳过期
                console.error('update session error: session mts on client has expired');
                break;
        }
    }
}
                        
                    

y2wIMBridge

推送服务桥对象,负责连接y2wIM与业务代码的桥,包含发送特定消息,接收消息队列处理,连接与发送错误处理等功能

y2wIMBridge在初始化时自动连接推送服务器

发送文字消息

                                
/**
* 发送文字消息
* @param targetId:目标Id
* @param scene:会话场景类型
* @param text:文字
* @param options: {
*       showMsg: showMsg//UI显示消息
*       storeMsgFailed: storeMsgFailed//消息保存失败
*       storeMsgDone: storeMsgDone//消息保存成功
*   }
*/
y2wIMBridge.prototype.sendTextMessage = function(targetId, scene, text, options)
                                
                            

发送文字消息按以下步骤执行

  1. 本地创建消息对象
  2. 回调options.showMsg(message)显示消息,消息状态设置为保存中
  3. 保存消息
    • 成功:修改消息状态为已保存,回调options.storeMsgDone
    • 失败:修改消息状态为保存失败,回调options.storeMsgFailed
  4. 发送通知

发送文件消息

                                
/**
* 发送文件消息
* @param targetId:目标Id
* @param scene:会话场景类型
* @param file:input.files[0]
* @param options:{
*  showMsg: showMsg//UI显示消息
*  storeMsgFailed: storeMsgFailed//消息保存失败
*  storeMsgDone: storeMsgDone//消息保存成功
* }
*/
y2wIMBridge.prototype.sendFileMessage = function(targetId, scene, file, options)
                                
                            

发送文件消息按以下步骤执行

  1. 本地创建消息对象
  2. 回调options.showMsg(message)显示消息,消息状态设置为保存中
  3. 上传文件
  4. 保存消息
    • 成功:修改消息状态为已保存,回调options.storeMsgDone
    • 失败:修改消息状态为保存失败,回调options.storeMsgFailed
  5. 发送通知

发送消息处理

y2wIMBridge现支持发送以下类型的消息

                        
y2wIMBridge.sendTypes = {
    text: 0,//文字
    file: 1//文件
}
                        
                    

消息发送处理方法handleSendMessage

                        
y2wIMBridge.handleSendMessage = function(){
    var that = this;
    if(this.sendList.length > 0){//发送集合存在数据
        var sendObj = this.sendList[0];
        switch (sendObj.type){
            case this.sendTypes.text://处理文字消息
                this.handleSendTextMessage(sendObj, function(){
                    if(that.sendList.length > 0)
                        that.handleSendMessage();
                })
                break;
            case this.sendTypes.file://处理文件消息
                this.handleSendFileMessage(sendObj, function(){
                    if(that.sendList.length > 0)
                        that.handleSendMessage();
                    })
                break;
            default :
                break;
        }
    }
}
                        
                    

重要

关于发送消息:所有地方调用发送消息,消息将加入到一个队列(y2wIMBridge.addToSendList),由消息发送处理方法(y2wIMBridge.handleSendMessage)统一执行发送,保证发送顺序的一致性

扩展自定义消息,可在y2wIMBridge.sendTypes中定义自己的消息类型,并在y2wIMBridge.handleSendMessage中对自定义的消息类型进行处理

接收消息处理

y2wIMBridge在初始化时自动建立连接,并注册接收消息的回调y2wIMBridge.onMessage

重要

yun2win默认发送的推送内容为一个同步集合,告知接收方去业务服务器同步何种信息

y2wIMBridge.onMessage作为统一接收消息的入口,将接收到的推送的消息加入队列,由同步处理方法统一执行

y2wIMBridge现支持以下同步类型

                        
y2wIMBridge.syncTypes = {
    userConversation: 0,//同步用户会话
    message: 1,//同步消息
    contact: 2,//同步联系人
    userSession: 3//同步群组
}
                        
                    

同步处理方法handleMessage

                        
y2wIMBridge.handleMessage = function(){
    var that = this;
    if(this.syncList.length > 0){//同步集合存在数据
        var syncObj = this.syncList[0];
        switch (syncObj.type){
            case this.syncTypes.contact://同步联系人
                this.handleSync_Contact(syncObj, function(){
                    if(that.syncList.length > 0)
                        that.handleMessage();
                })
                break;
            case this.syncTypes.userConversation://同步用户会话
                this.handleSync_UserConversation(syncObj, function(){
                    if(that.syncList.length > 0)
                    that.handleMessage();
                })
                break;
            case this.syncTypes.message://同步消息
                this.handleSync_Message(syncObj, function(){
                    if(that.syncList.length > 0)
                        that.handleMessage();
                })
                break;
            default :
                break;
        }
    }
}
                        
                    

重要

扩展自定义同步类型,可在y2wIMBridge.syncTypes中定义自己的同步类型,并在y2wIMBridge.handleMessage中对自定义的同步类型进行处理