开发指南
1. 与消息服务建立连接
与消息服务器建立连接使用 chat.connect 接口，该接口是一个长连接订阅接口：
// 建立连接
let subscription；
RSocket.rs({
route: 'chat.connect',
onNext: handleIncomingMessage, // onNext回调中处理收到的消息
onSubscribe: (sub) => {
subscription = sub;
}
});
// 断开连接
subscription.cancel();
1.1 重连机制
为持续收到服务器的下行消息，需要通过重连机制，确保长连接不会断开：
export async function connect({ onNext, onSubscribe }) {
return Util.retry(Number.MAX_SAFE_INTEGER, async () => _connect({ onNext, onSubscribe }));
}
async function _connect(options) {
return RSocket.rs({
route: 'chat.connect',
...options,
});
}
2. 消息格式
{
"seq" : 39, // 消息序列号(在线消息不包含该字段)
"id" : "e6404191e56c47839288e1d3245cf0ef", // 消息标识
"from" : "13500010001@mzd", // 消息发送者
"to" : "13500020002@mzd", // 消息接收者
"resource" : "183.14.29.145:46752", // 客户端标识
"type" : "chat", // 消息类型
"body" : "Hello Taurus Chat", // 消息内容
"ts" : "2024-11-03T04:08:35.845Z" // 消息时间戳(在线消息不包含该字段)
}
3. 消息扩展
除普通文本消息外，其他格式或具有不同功能的消息，通过消息扩展实现。不同的扩展使用ns（namespace）区分。
内置的消息扩展一览：
| 类型 | ns |
|---|---|
| 多格式消息 | |
| 图片消息 | urn:ximp:message:media#image |
| 视频消息 | urn:ximp:message:media#video |
| 语音消息 | urn:ximp:message:media#voice |
| 音频消息 | urn:ximp:message:media#audio |
| 文件消息 | urn:ximp:message:media#file |
| 位置消息 | urn:ximp:message:location |
| 分享链接消息 | urn:ximp:message:link |
| 通知类消息 | |
| 异常 | urn:ximp:message:error |
| 联系人邀请通知 | urn:ximp:roster:invite |
| 联系人列表更新通知 | urn:ximp:roster:update |
| 群邀请通知 | urn:ximp:group:invite |
| 群变更通知 | urn:ximp:group:update |
3.1 多格式消息
3.1.1 图片消息
ns: urn:ximp:message:media#image
{
"id" : "e6404191e56c47839288e1d3245cf0ef", // 消息标识
"from" : "13500010001@mzd", // 消息发送者
"to" : "13500020002@mzd", // 消息接收者
"resource" : "183.14.29.145:46752", // 客户端标识
"type" : "chat", // 消息类型
"body" : "[image]", // 消息内容固定为[image]
"x" : [ // 消息扩展定义
{
"src": "https://sit.aspiretop.com/v2/api/files/chat:image:e6404191e56c47839288e1d3245cf0ef.jpg", // 图片链接
"meta": { // 图片元数据，由客户端自行填充
"type": "jpeg",
"width": 1080,
"height": 1920,
"orientation": "up"
},
"ns": "urn:ximp:message:media#image" // 图片消息扩展的namespace标识
}
]
}
3.1.2 视频消息
ns: urn:ximp:message:media#video
{
"id" : "e6404191e56c47839288e1d3245cf0ef", // 消息标识
"from" : "13500010001@mzd", // 消息发送者
"to" : "13500020002@mzd", // 消息接收者
"resource" : "183.14.29.145:46752", // 客户端标识
"type" : "chat", // 消息类型
"body" : "[video]", // 消息内容固定为[video]
"x" : [ // 消息扩展定义
{
"src": "https://sit.aspiretop.com/v2/api/files/chat:video:3df372de096747bf8761cbc24936de8a.mp4", // 视频文件链接
"meta": { // 视频元数据，由客户端自行填充
"audioBitrate": 55.0,
"fps": 29.0,
"orientation": "up",
"audioChannel": 1.0,
"audioSampleRate": 44100.0,
"width": 540.0,
"type": "video/mp4",
"size": 192.0,
"bitrate": 665.0,
"height": 960.0,
"duration": "2.1",
"resolution": "[540, 960]",
"errMsg": "getVideoInfo:ok"
},
"ns": "urn:ximp:message:media#video" // 视频消息扩展的namespace标识
}
]
}
3.1.3 语音消息
ns: urn:ximp:message:media#voice
{
"id" : "e6404191e56c47839288e1d3245cf0ef", // 消息标识
"from" : "13500010001@mzd", // 消息发送者
"to" : "13500020002@mzd", // 消息接收者
"resource" : "183.14.29.145:46752", // 客户端标识
"type" : "chat", // 消息类型
"body" : "[voice]", // 消息内容固定为[voice]
"x" : [ // 消息扩展定义
{
"src": "https://sit.aspiretop.com/v2/api/files/chat:voice:e6404191e56c47839288e1d3245cf0ef.aac", // 语音音频文件url
"meta": { // 语音音频元数据，由客户端自行填充
"duration": 10000,
"sampleRate": 44100,
"numberOfChannels": 1,
"encodeBitRate": 192000,
"format": "aac",
"frameSize": 50
},
"ns": "urn:ximp:message:media#voice" // 语音消息扩展的namespace标识
}
]
}
3.1.4 音频消息
ns: urn:ximp:message:media#voice
{
"id" : "e6404191e56c47839288e1d3245cf0ef", // 消息标识
"from" : "13500010001@mzd", // 消息发送者
"to" : "13500020002@mzd", // 消息接收者
"resource" : "183.14.29.145:46752", // 客户端标识
"type" : "chat", // 消息类型
"body" : "[audio]", // 消息内容固定为[voice]
"x" : [ // 消息扩展定义
{
"src": "https://sit.aspiretop.com/v2/api/files/chat:voice:e6404191e56c47839288e1d3245cf0ef.mp3", // 音频文件url
"meta": { // 语音音频元数据，由客户端自行填充
"duration": 10000,
"sampleRate": 44100,
"numberOfChannels": 1,
"encodeBitRate": 192000,
"format": "mp3",
"frameSize": 50
},
"ns": "urn:ximp:message:media#audio" // 语音消息扩展的namespace标识
}
]
}
3.1.5 文件消息
ns: urn:ximp:message:media#file
{
"id" : "e6404191e56c47839288e1d3245cf0ef", // 消息标识
"from" : "13500010001@mzd", // 消息发送者
"to" : "13500020002@mzd", // 消息接收者
"resource" : "183.14.29.145:46752", // 客户端标识
"type" : "chat", // 消息类型
"body" : "[file]", // 消息内容固定为[file]
"x" : [ // 消息扩展定义
{
"src": "https://sit.aspiretop.com/v2/api/files/chat:file:c30c6d7f358a4af5a2861fbb19b2a142.pptx", // 文件链接
"meta": { // 文件元数据，由客户端自行填充
"name": "渠道管理需求说明.pptx",
"size": 812727
},
"ns": "urn:ximp:message:media#file" // 文件消息扩展的namespace标识
}
]
}
3.1.6 位置消息
ns: urn:ximp:message:location
{
"id" : "e6404191e56c47839288e1d3245cf0ef", // 消息标识
"from" : "13500010001@mzd", // 消息发送者
"to" : "13500020002@mzd", // 消息接收者
"resource" : "183.14.29.145:46752", // 客户端标识
"type" : "chat", // 消息类型
"body" : "[location]", // 消息内容固定为[location]
"x" : [ // 消息扩展定义
{
"longitude": 113.931007, // 经度
"latitude": 22.531813, // 维度
"address": "广东省深圳市南山区桃园路1号", // 地址
"addressDesc": "西海明珠大厦", // 位置名称
"ns": "urn:ximp:message:location" // 位置消息扩展的namespace标识
}
]
}
3.1.7 分享链接消息
ns: urn:ximp:message:link
{
"id" : "e6404191e56c47839288e1d3245cf0ef", // 消息标识
"from" : "13500010001@mzd", // 消息发送者
"to" : "13500020002@mzd", // 消息接收者
"resource" : "183.14.29.145:46752", // 客户端标识
"type" : "chat", // 消息类型
"body" : "[link]", // 消息内容固定为[location]
"x" : [ // 消息扩展定义
{
"url": "https://www.someweb.com/page.html", // 分享链接url
"title": "每日新闻", // 分享标题
"description": "今天没什么大事", // 分享描述
"addressDesc": "西海明珠大厦", // 位置名称
"thumbUrl": "https://sit.aspiretop.com/v2/api/files/chat:link:thumb:e6404191e56c47839288e1d3245cf0ef.png", // 缩略图url
"ns": "urn:ximp:message:link" // 分享链接消息扩展的namespace标识
}
]
}
3.2 异常
ns: urn:ximp:message:error
客户端收到此类消息时，可通过UI提示用户。
{
"id" : "e6404191e56c47839288e1d3245cf0ef", // 消息标识
"from" : "13500010001@mzd", // 消息发送者
"to" : "13500020002@mzd", // 消息接收者
"type" : "chat", // 消息类型
"body" : "Hello", // 原始消息内容
"x" : [ // 消息扩展定义
{
"code": 10403, // 错误码
"errMsg": "Your message can not be delivered.", // 错误消息
"ns": "urn:ximp:message:error" // 异常消息扩展的namespace标识
}
]
}
3.3 联系人邀请通知
ns: urn:ximp:roster:invite
客户端收到此类消息时，在消息盒子展示该通知，并提供交互，对邀请进行 【接受】 或【拒绝】处理
{
"id" : "e6404191e56c47839288e1d3245cf0ef", // 消息标识
"from" : "13500010001@mzd", // 邀请者
"to" : "13500020002@mzd", // 消息接收者
"type" : "invite", // 消息类型
"body" : "我是孔丘", // 邀请消息内容
"x" : [ // 消息扩展定义
{
"inviterName": "孔丘", // 邀请者昵称
"ns": "urn:ximp:roster:invite" // 邀请消息扩展的namespace标识
}
]
}
3.4 联系人列表更新通知
ns: urn:ximp:roster:update
客户端收到此类消息时，应重新 拉取联系人列表。
{
"id" : "e6404191e56c47839288e1d3245cf0ef", // 消息标识
"to" : "13500020002@mzd", // 消息接收者
"type" : "nnotify", // 消息类型
"x" : [ // 消息扩展定义
{
"contactId": "13500020002@mzd", // 变化的联系人标识
"ns": "urn:ximp:roster:update" // 联系人列表更新通知扩展的namespace标识
}
]
}
3.5 群邀请通知
ns: urn:ximp:group:invite
客户端收到此类消息时，在消息盒子展示该通知，并提供交互，对邀请进行 【接受】 或【拒绝】处理
{
"id" : "e6404191e56c47839288e1d3245cf0ef", // 消息标识
"from" : "672ab775cf4031052ea149bc@group.mzd",// 群标识
"to" : "13500020002@mzd", // 消息接收者
"type" : "invite", // 消息类型
"body" : "孔丘邀请您加入群：关于XX业务的讨论", // 邀请消息内容
"x" : [ // 消息扩展定义
{
"inviterId": "13500010001@mzd", // 邀请者表示
"inviterName": "孔丘", // 邀请者昵称
"ns": "urn:ximp:group:invite" // 邀请消息扩展的namespace标识
}
]
}
3.6 群变更通知
ns: urn:ximp:group:update
客户端收到此类消息时，应重新 拉取群列表。
{
"id" : "e6404191e56c47839288e1d3245cf0ef", // 消息标识
"from" : "672ab775cf4031052ea149bc@group.mzd",// 群标识
"to" : "13500020002@mzd", // 消息接收者
"type" : "notify", // 消息类型
"x" : [ // 消息扩展定义
{
"memberId": "13500020002@mzd", // 变化的群成员标识
"type": "join", // 变更类型
"ns": "urn:ximp:group:update" // 群变更通知扩展的namespace标识
}
]
}
其中变更类型包括：
- join - 成员加入;
- leave - 成员退出; 当成员ID是自己时，客户端需要更新群列表
- update - 修改群名称，群公告等;
- destroy - 群销毁; 客户端需要更新群列表