diff --git a/README.md b/README.md index 750d525b2..eed15d2fd 100644 --- a/README.md +++ b/README.md @@ -1,791 +1,15 @@ -_**by wangxiao 2015/02/04**_ # LeanCloud 实时通信 JavaScript SDK -## 简介 +## 详细使用方法请看 [官方文档](https://leancloud.cn/docs/js_realtime.html) -感谢你使用 JavaScript 的 Realtime SDK，LeanCloud 的 Realtime 服务每天处理请求数超过百万级，安全可靠，你的明智之选。你可以通过使用我们提供的 SDK，甚至一行后端代码都不用写，就可以做一个功能完备的实时聊天应用。当然，你也可以通过 Realtime SDK 并且配合「云代码」简单的实现之前可能需要很多人才能完成的实时通信相关需求开发，并且如果你达到我们的收费额度，也会以极低的成本支付你的使用费用，绝对物超所值。 +## 官方新版本发布流程 -## 概念 +* 修改代码中版本号 +* 修改 bower.json 中的版本号 +* Github 生成 release 包 +* 发布到 bower -在你开始使用之前，首先来了解一下实时通信 SDK 的基本概念。实时通信在 SDK 层面只有两个层次： - -* 一层是底层实时通信基础模块，负责与服务器匹配和授权，建立基础的连接和底层控制。这个层次只会派发一些基础的事件出来，你可以通过 SDK 的监听这些事件。这个层面 SDK 会保证底层连接的稳定，包括断开重试，心跳连接等策略； - -* 另一层是业务逻辑层，用户可以使用 SDK 建立不同的 Room （房间）。一个 Room 就是一个独立的通信单元，但 Room 间一般是无法通信的。当然你可以自己在业务逻辑层，通过派发自定义事件的方式来封装其他自定义的逻辑。当你建立一个新 Room 之后，对应的服务器端就会自动生成这个房间，除非你自行删除，否则该房间一直存在。但是用户如果没有连接，该房间不会占用服务器资源，只是存储的一个条目数据； - - -### 全局命名空间 AV - -LeanCloud JavaScript 相关 SDK 都会使用「AV」作为命名空间。 - -### 方法 - -#### lc.realtime(options, callback) - -描述： - -* 创建实时通信对象的方法，会启动实时通信的连接。自动调用 open 方法，内部与服务器匹配，并建立 WebSocket 连接。内部会自动维持与服务器的链接稳定，控制心跳数据包的频率等，如果发生中断可以通过对应的事件来给用户界面上的变化提示。另外，此方法支持多实例，也就是说，你可以在一个页面中，创建多个 RealtimeObject 来实现聊天。 - -参数： - -* options {Object} （必须） 配置实时通信服务所需的必要参数。其中包括： - - * appId {String} （必须）应用的 AppId，在「控制台」-「设置」-「基本信息」中可以查看； - - * clientId {String} （必须）当前客户端的唯一 id，用来标示当前客户端； - - * auth {String}（可选）可以传入一个服务器 url 地址，每次当建立连接的时候就会去服务器请求认证，或者许可之后才能建立连接； - -返回： - -* {Object} 返回 RealtimeObject，其中有后续调用的方法，支持链式调用。 - -例子： - - -```js -var rtObject = lc.realtime({ - // appId 需要换成你自己的 appId - appId: '9p6hyhh60av3ukkni3i9z53q1l8yy3cijj6sie3cewft18vm', - // clientId 是自定义的名字，当前客户端可以理解的名字 - clientId: 'abc123' - // auth 是权限校验的服务器地址，具体请看文档 - // auth: 'http://signature-example.avosapps.com/sign' -}, function() { - console.log('open'); -}); - -rtObject.on('open', function() { - console.log('open'); -}); - -``` - -#### lc.realtime.version - -描述： - -* 获取当前 SDK 的版本信息 - -返回： - -* {String} 返回当前版本 - -例子： - -```js -console.log(lc.realtime.version); // 2.0.0 -``` - -#### RealtimeObject.open(callback) - -描述： - -* 该方法一般情况下，你不需要调用，SDK 会自动启动与服务的连接。该方法可以启动实时通信的连接，与服务器匹配建立 websocket 连接； - -参数： - -* callback {Function}（可选）创建成功并且与服务器建立连接后触发的回调，此时也会派发一个私有的事件到 RealtimeObject 内部，也可以通过监听当前的 RealtimeObject 实例的 open 事件来处理连接成功的业务逻辑； - -返回： - -* {Object} 返回 RealtimeObject，其中有后续调用的方法，支持链式调用。 - -例子： - -```js -var rtObject = lc.realtime({ - // appId 需要换成你自己的 appId - appId: '9p6hyhh60av3ukkni3i9z53q1l8yy3cijj6sie3cewft18vm', - // clientId 是自定义的名字，当前客户端可以理解的名字 - clientId: 'abc123' - // auth 是权限校验的服务器地址，具体请看文档 - // auth: 'http://signature-example.avosapps.com/sign' -}); - -rtObject.open(function() { - console.log('open'); -}); - -rtObject.on('open', function() { - console.log('open,too.'); -}); -``` - -#### RealtimeObject.close() - -描述： - -* 关闭实时通信的连接，并且内部会关闭 websocket 连接。该方法没有回调，因为调用会立刻关闭 WebSocket。 - -返回： - -* {Object} 返回 RealtimeObject，其中有后续调用的方法，支持链式调用。 - -例子： - -```js -var rtObject = lc.realtime({ - // appId 需要换成你自己的 appId - appId: '9p6hyhh60av3ukkni3i9z53q1l8yy3cijj6sie3cewft18vm', - // clientId 是自定义的名字，当前客户端可以理解的名字 - clientId: 'abc123' - // auth 是权限校验的服务器地址，具体请看文档 - // auth: 'http://signature-example.avosapps.com/sign' -}); - -rtObject.close(); - -rtObject.on('close', function() { - console.log('close'); -}); -``` - -#### RealtimeObject.on(eventName, callback) - -描述： - -* 监听 RealtimeObject 内部的事件，基于一个局部的事件中心，事件每次派发就会被触发一次； - -参数： - -* eventName {String} （必须）监听的事件名称 - -* callback {Function} （必须）当事件被派发时会调用的回调 - -返回： - -* {Object} 返回 RealtimeObject，其中有后续调用的方法，支持链式调用。 - -```js -var rtObject = lc.realtime({ - // appId 需要换成你自己的 appId - appId: '9p6hyhh60av3ukkni3i9z53q1l8yy3cijj6sie3cewft18vm', - // clientId 是自定义的名字，当前客户端可以理解的名字 - clientId: 'abc123' - // auth 是权限校验的服务器地址，具体请看文档 - // auth: 'http://signature-example.avosapps.com/sign' -}); - -// 当新建一个 Room 的时候就会触发 -rtObject.on('new', function(data) { - console.log(data); -}); - -// 有人加入 Room 的时候会被触发 -rtObject.on('join', function(data) { - console.log(data); -}); ``` - -#### RealtimeObject.once(eventName, callback) - -描述： - -* 监听 RealtimeObject 内部的事件，基于一个局部的事件中心，事件只会被触发一次； - -参数： - -* eventName {String} （必须）监听的事件名称 - -* callback {Function} （必须）当事件被派发时会调用的回调 - -返回： - -* {Object} 返回 RealtimeObject，其中有后续调用的方法，支持链式调用。 - -```js -var rtObject = lc.realtime({ - // appId 需要换成你自己的 appId - appId: '9p6hyhh60av3ukkni3i9z53q1l8yy3cijj6sie3cewft18vm', - // clientId 是自定义的名字，当前客户端可以理解的名字 - clientId: 'abc123' - // auth 是权限校验的服务器地址，具体请看文档 - // auth: 'http://signature-example.avosapps.com/sign' -}); - -// 当服务建立之后会被触发 -rtObject.once('open', function() { - console.log('opened'); -}); - -// 当服务关闭的时候会被触发 -rtObject.once('close', function() { - console.log('closed'); -}); -``` - -#### RealtimeObject.emit(eventName, dataObject) - -描述： - -* 派发一个事件到 RealtimeObject 中，局部的事件中心 - -参数： - -* eventName {String} （必须）派发的事件名称 - -* dataObject {Obejct}（可选）传递的参数，可以在监听的回调中通过第一个参数获取 - -返回： - -* {Object} 返回 RealtimeObject，其中有后续调用的方法，支持链式调用。 - -```js -var rtObject = lc.realtime({ - // appId 需要换成你自己的 appId - appId: '9p6hyhh60av3ukkni3i9z53q1l8yy3cijj6sie3cewft18vm', - // clientId 是自定义的名字，当前客户端可以理解的名字 - clientId: 'abc123' - // auth 是权限校验的服务器地址，具体请看文档 - // auth: 'http://signature-example.avosapps.com/sign' -}); - -// 当事件被派发的时候会触发 -rtObject.on('wangxiao', function(data) { - // 会输出 test - console.log(data.aaa); -}); - -// 派发了一个自定义的事件，名字叫「wangxiao」。 -rtObject.emit('wangxiao', { - aaa: 'test' -}); +bower register leancloud-realtime git@github.com:leancloud/js-realtime-sdk.git ``` - -#### RealtimeObject.room(options, callback) - -描述： - -* 创建一个 Room（房间），实时通信的最小单元； - -参数： - -* options {Object} （必须）传入配置信息 - - * data {Object} （可选）自定义的数据信息，如 title、name 等 - - * callback {Function} （可选）创建成功后的回调函数，此时也会在 RealtimeObject 内部派发一个 new 事件，可以通过 RealtimeObject.on() 方法来监听； - -返回： - -* {Object} 返回 RoomObject，其中有后续调用的方法，支持链式调用。 - -```js -var rtObject = lc.realtime({ - // appId 需要换成你自己的 appId - appId: '9p6hyhh60av3ukkni3i9z53q1l8yy3cijj6sie3cewft18vm', - // clientId 是自定义的名字，当前客户端可以理解的名字 - clientId: 'abc123' - // auth 是权限校验的服务器地址，具体请看文档 - // auth: 'http://signature-example.avosapps.com/sign' -}); - -var room = rtObject.room({ - members: [ - 'wangxiao02' - ], - data: { - title: 'testTitle' - } -}, function(result) { - console.log('Room created callback'); -}); - -// 当新 Room 被创建时触发 -rtObject.on('create', function(data) { - console.log(data); -}); -``` - -#### RealtimeObject.room(roomId, callback) - -描述： - -* 匹配一个在服务器端已有的 room，并生成对应的 RoomObject，此时不派发任何事件； - -参数： - -* roomId {String} （必须）传入已有 Room 的 id - -* callback {Function} （可选）创建成功后的回调函数，此时不会派发任何事件； - -返回： - -* {Object} 返回 RoomObject，其中有后续调用的方法，支持链式调用。 - -```js -var rtObject = lc.realtime({ - // appId 需要换成你自己的 appId - appId: '9p6hyhh60av3ukkni3i9z53q1l8yy3cijj6sie3cewft18vm', - // clientId 是自定义的名字，当前客户端可以理解的名字 - clientId: 'abc123' - // auth 是权限校验的服务器地址，具体请看文档 - // auth: 'http://signature-example.avosapps.com/sign' -}); - -var room = rtObject.room('sasfalklkjdlfs123'); -``` - -#### RealtimeObject.query(callback) - -描述： - -* 获取当前用户所在的 Room 信息 - -参数： - -* callback {Function} （必须）创建成功后的回调函数，参数中可以获取到 Room 的列表； - -返回： - -* {Object} 返回 RoomObject，其中有后续调用的方法，支持链式调用。 - -```js -var rtObject = lc.realtime({ - // appId 需要换成你自己的 appId - appId: '9p6hyhh60av3ukkni3i9z53q1l8yy3cijj6sie3cewft18vm', - // clientId 是自定义的名字，当前客户端可以理解的名字 - clientId: 'abc123' - // auth 是权限校验的服务器地址，具体请看文档 - // auth: 'http://signature-example.avosapps.com/sign' -}); - -// 当实时通信建立成功之后 -rtObject.on('open', function() { - // 查询当前用户所在的组 - rtObject.query(function(data) { - console.log(data); // list - }); -}); -``` - -#### RoomObject.add(clientId, callback) - -描述： - -* 向当前 RoomObject 中添加一个用户 - -参数： - -* clientId {String} （必须）传入已有用户的 clientId - -* callback {Function} （可选）创建成功后的回调函数，此时会在 RealtimeObject 内部派发一个 join 事件； - -返回： - -* {Object} 返回 RoomObject，其中有后续调用的方法，支持链式调用。 - -```js -var rtObject = lc.realtime({ - // appId 需要换成你自己的 appId - appId: '9p6hyhh60av3ukkni3i9z53q1l8yy3cijj6sie3cewft18vm', - // clientId 是自定义的名字，当前客户端可以理解的名字 - clientId: 'abc123' - // auth 是权限校验的服务器地址，具体请看文档 - // auth: 'http://signature-example.avosapps.com/sign' -}); - -var room = rtObject.room({ - members: [ - 'wangxiao02' - ], - data: { - title: 'testTitle' - } -}); - -room.add('wangxiao03', function() { - console.log('Add success.'); -}); - -// 当前 Room 有新的 client 加入时触发 -rtObject.on('join', function(data) { - console.log(data); -}); -``` - -#### RoomObject.add(clientIdList, callback) - -描述： - -* 向当前 RoomObject 中添加多个用户 - -参数： - -* clientIdList {Array} （必须）传入已有用户的 clientId 的 list，每个元素是 client - -* callback {Function} （可选）创建成功后的回调函数，此时会在 RealtimeObject 内部派发一个 join 事件； - -返回： - -* {Object} 返回 RoomObject，其中有后续调用的方法，支持链式调用。 - -```js -var rtObject = lc.realtime({ - // appId 需要换成你自己的 appId - appId: '9p6hyhh60av3ukkni3i9z53q1l8yy3cijj6sie3cewft18vm', - // clientId 是自定义的名字，当前客户端可以理解的名字 - clientId: 'abc123' - // auth 是权限校验的服务器地址，具体请看文档 - // auth: 'http://signature-example.avosapps.com/sign' -}); - -var room = rtObject.room({ - members: [ - 'wangxiao02' - ], - data: { - title: 'testTitle' - } -}); - -room.add(['wangxiao03', 'wangxiao04'], function() { - console.log('Add success.'); -}); - -// 当前 Room 有新的 client 加入时触发 -rtObject.on('join', function(data) { - console.log(data); -}); -``` - -#### RoomObject.remove(clientId, callback) - -* 描述：从当前 RoomObject 中删除一个用户 - -参数： - -* clientId {String} （必须）传入已有用户的 clientId - -* callback {Function} （可选）删除成功后的回调函数，此时会在 RealtimeObject 内部派发一个 left 事件； - -返回： - -* {Object} 返回 RoomObject，其中有后续调用的方法，支持链式调用。 - -```js -var rtObject = lc.realtime({ - // appId 需要换成你自己的 appId - appId: '9p6hyhh60av3ukkni3i9z53q1l8yy3cijj6sie3cewft18vm', - // clientId 是自定义的名字，当前客户端可以理解的名字 - clientId: 'abc123' - // auth 是权限校验的服务器地址，具体请看文档 - // auth: 'http://signature-example.avosapps.com/sign' -}); - -var room = rtObject.room({ - members: [ - 'wangxiao02' - ], - data: { - title: 'testTitle' - } -}); - -room.remove('wangxiao02', function() { - console.log('Remove success.'); -}); - -// 当前 Room 有 client 立刻时触发 -rtObject.on('left', function(data) { - console.log(data); -}); -``` - -#### RoomObject.remove(clientIdList, callback) - -描述： - -* 从当前 RoomObject 中删除多个用户 - -参数： - -* clientIdList {Array} （必须）传入已有用户的 clientId 的 list，每个元素是 client - -* callback {Function} （可选）创建成功后的回调函数，此时会在 RealtimeObject 内部派发一个 left 事件； - -返回： - -* {Object} 返回 RoomObject，其中有后续调用的方法，支持链式调用。 - -```js -var rtObject = lc.realtime({ - // appId 需要换成你自己的 appId - appId: '9p6hyhh60av3ukkni3i9z53q1l8yy3cijj6sie3cewft18vm', - // clientId 是自定义的名字，当前客户端可以理解的名字 - clientId: 'abc123' - // auth 是权限校验的服务器地址，具体请看文档 - // auth: 'http://signature-example.avosapps.com/sign' -}); - -var room = rtObject.room({ - members: [ - 'wangxiao02', - 'wangxiao03' - ], - data: { - title: 'testTitle' - } -}); - -room.remove(['wangxiao02', 'wangxiao03'], function() { - console.log('Remove success.'); -}); - -// 当前 Room 有 client 立刻时触发 -rtObject.on('left', function(data) { - console.log(data); -}); -``` - -#### RoomObject.join(callback) - -描述： - -* 加入当前这个 Room - -参数： - -* callback {Function} （可选）加入成功后的回调函数，此时会在 RealtimeObject 内部派发一个 join 事件； - -返回： - -* {Object} 返回 RoomObject，其中有后续调用的方法，支持链式调用。 - -```js -var rtObject = lc.realtime({ - // appId 需要换成你自己的 appId - appId: '9p6hyhh60av3ukkni3i9z53q1l8yy3cijj6sie3cewft18vm', - // clientId 是自定义的名字，当前客户端可以理解的名字 - clientId: 'abc123' - // auth 是权限校验的服务器地址，具体请看文档 - // auth: 'http://signature-example.avosapps.com/sign' -}); - -var room = rtObject.room('safjslakjlfkjla123'); - -room.join(function() { - console.log('join'); -}); - -// 当前 Room 有新的 client 加入时触发 -rtObject.on('join', function(data) { - console.log(data); -}); -``` - -#### RoomObject.leave(callback) - -描述： - -* 从当前 RoomObject 中离开 - -参数： - -* clientIdList {Array} （必须）传入已有用户的 clientId 的 list，每个元素是 client - -* callback {Function} （可选）创建成功后的回调函数，此时会在 RealtimeObject 内部派发一个 left 事件； - -返回： - -* {Object} 返回 RoomObject，其中有后续调用的方法，支持链式调用。 - -```js -var rtObject = lc.realtime({ - // appId 需要换成你自己的 appId - appId: '9p6hyhh60av3ukkni3i9z53q1l8yy3cijj6sie3cewft18vm', - // clientId 是自定义的名字，当前客户端可以理解的名字 - clientId: 'abc123' - // auth 是权限校验的服务器地址，具体请看文档 - // auth: 'http://signature-example.avosapps.com/sign' -}); - -var room = rtObject.room({ - members: [ - 'wangxiao02', - 'wangxiao03' - ], - data: { - title: 'testTitle' - } -}); - -room.leave(); - -// 当前 Room 有 client 立刻时触发 -rtObject.on('left', function(data) { - console.log(data); -}); -``` - -#### RoomObject.list(callback) - -描述： - -* 获取当前 RoomObject 中的成员列表 - -参数： - -* callback {Function} （必须）获取成员列表的回调函数； - -返回： - -* {Object} 返回 RoomObject，其中有后续调用的方法，支持链式调用。 - -```js -var rtObject = lc.realtime({ - // appId 需要换成你自己的 appId - appId: '9p6hyhh60av3ukkni3i9z53q1l8yy3cijj6sie3cewft18vm', - // clientId 是自定义的名字，当前客户端可以理解的名字 - clientId: 'abc123' - // auth 是权限校验的服务器地址，具体请看文档 - // auth: 'http://signature-example.avosapps.com/sign' -}); - -var room = rtObject.room({ - members: [ - 'wangxiao02', - 'wangxiao03' - ], - data: { - title: 'testTitle' - } -}); - -room.list(function(data) { - console.log(data); // room 中成员 list -}); -``` - -#### RoomObject.send(dataObject, callback) - -描述： - -* 向当前这个 RoomObject 中发送消息 - -参数： - -* dataObject {Object} （必须）发送的数据内容 - -* callback {Function} （可选）发送到服务器成功后的回调函数，不一定对方已经接收了，但是服务器已经收到。 - -返回： - -* {Object} 返回 RoomObject，其中有后续调用的方法，支持链式调用。 - -```js -var rtObject = lc.realtime({ - // appId 需要换成你自己的 appId - appId: '9p6hyhh60av3ukkni3i9z53q1l8yy3cijj6sie3cewft18vm', - // clientId 是自定义的名字，当前客户端可以理解的名字 - clientId: 'abc123' - // auth 是权限校验的服务器地址，具体请看文档 - // auth: 'http://signature-example.avosapps.com/sign' -}); - -var room = rtObject.room({ - members: [ - 'wangxiao02', - 'wangxiao03' - ], - data: { - title: 'testTitle' - } -}); - -room.send({ - testMsg: 'abcde' -}, function() { - console.log('server ack.'); -}); - -// 当前用户所在的组，有消息时触发 -rtObject.on('message', function(data) { - console.log(data); -}); -``` - -#### RoomObject.receive(callback) - -描述： - -* 接收到当前这个 RoomObject 中的消息 - -参数： - -* callback {Function} （必须）收到当前 Room 中信息的处理函数 - -返回： - -* {Object} 返回 RoomObject，其中有后续调用的方法，支持链式调用。 - -```js -var rtObject = lc.realtime({ - // appId 需要换成你自己的 appId - appId: '9p6hyhh60av3ukkni3i9z53q1l8yy3cijj6sie3cewft18vm', - // clientId 是自定义的名字，当前客户端可以理解的名字 - clientId: 'abc123' - // auth 是权限校验的服务器地址，具体请看文档 - // auth: 'http://signature-example.avosapps.com/sign' -}); - -var room = rtObject.room({ - members: [ - 'wangxiao02', - 'wangxiao03' - ], - data: { - title: 'testTitle' - } -}); - -// 当前用户所在的组，有消息时触发 -room.receive(function(data) { - console.log(data); // 接收到的信息 -}); -``` - -### 事件 - -SDK 会默认派发一些事件，这些事件仅会在 RealtimeObject 内部被派发（注意：RoomObject 内部默认不会派发任何事件），你可以通过监听这些事件来完成你的操作。以下是默认事件的说明： - -#### open - -描述： - -* 与服务器建立好连接之后就会被派发，包括当服务断开重新被连接上时也会被触发 - -#### close - -描述： - -* 与服务器连接断开就会被派发，包括网络中断 - -#### create - -描述： - -* 新建一个 Room 成功之后会被触发 - -#### join - -描述： - -* 当一个 Room 新增了一个成员之后会被触发 - -#### left - -描述： - -* 当一个 Room 中有成员离开之后会被触发 - -#### message - -描述： - -* 当收到消息时会被触发，收到的消息是当前客户端（clientId）存在的 Room 中的信息，所有这些数据都可以在服务器端看到。 - -#### reuse - -* 发生连接错误，可能是网络原因，SDK 在自动尝试重连。可以监听这个状态，给用户「服务器已断开，正在重新连接。。。」之类的提示。 +* 修改 changelog.md diff --git a/bower.json b/bower.json index a1e27583e..0b68dfab0 100644 --- a/bower.json +++ b/bower.json @@ -1,7 +1,7 @@ { "name": "leancloud-realtime.js", "version": "2.0.0", - "homepage": "http://leancloud.cn", + "homepage": "http://github.com/leancloud/js-realtime-sdk/", "authors": [ "WangXiao " ], diff --git a/changelog.md b/changelog.md new file mode 100644 index 000000000..e69de29bb