开发准备
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("同步成功"); })
初始化
当前用户对象初始化时会做以下工作:
- 创建用户会话管理对象:userConversations
- 创建联系人管理对象:contacts
- 创建群组管理对象:userSessions
- 创建会话管理对象:sessions
- 使用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("获取会话成功"); })
重要
- 此方法先在本地搜索,如果本地不存在将去服务器获取,此方法必定会返回session
- 获取会话将同时将返回会话成员
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"] }
重要
- from(消息发送者)与to(消息接受者)
this.messages.session.type=='p2p': from=user(发送方);to=user(接收方)
this.messages.session.type=='group': from=sessionMember(发送方);to=session(会话) - 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是一个数组,存放多个会话成员信息
- 更新会话操作只有在以下两种情况下调用
- 推送服务器不存在此会话,此时需要将当前会话所有成员更新到推送服务器
- 推送服务器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)
发送文字消息按以下步骤执行
- 本地创建消息对象
- 回调options.showMsg(message)显示消息,消息状态设置为保存中
- 保存消息
- 成功:修改消息状态为已保存,回调options.storeMsgDone
- 失败:修改消息状态为保存失败,回调options.storeMsgFailed
- 发送通知
发送文件消息
/**
* 发送文件消息
* @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)
发送文件消息按以下步骤执行
- 本地创建消息对象
- 回调options.showMsg(message)显示消息,消息状态设置为保存中
- 上传文件
- 保存消息
- 成功:修改消息状态为已保存,回调options.storeMsgDone
- 失败:修改消息状态为保存失败,回调options.storeMsgFailed
- 发送通知
发送消息处理
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中对自定义的同步类型进行处理