-
1. 后端处理服务器API
- 1.1 数据库结构
- 1.2 后端处理服务器HTTP 接口
- 1.3. 数据包
-
2. 后端处理服务器应用集成API
- 2.1 设置应用集成
- 2.2 API 格式和签名机制
- 2.3 API 定义
- 3. 客户端扩展机制
-
4. 会话机器人开发指南
- 4.1 机器人应用开发
所有数据包
- 2019-11-04 16:16:57
- 先知
- 10984
- 最后编辑:先知 于 2020-02-04 15:41:25
- 分享链接
本文档向大家介绍喧喧所有数据包(请求、响应、推送)的定义和数据包中变量的定义。
一、sysServerStart
XXD 服务器在启动之后会向后端服务器发送一个 sysServerStart 数据包来提示 XXD 服务器已经启动。后端服务器在接收到请求数据包后会将系统中所有用户状态重置为离线状态(offline)。
1、请求数据包(xxd→xxb)
数据包定义:
{ method: 'sysServerStart' }2、响应(xxb→xxd)
当后端服务器接收到请求数据包后,并不会需要返回响应数据包,XXD 服务器会根据 HTTP 响应状态码判断后端服务器是否收到请求。
后端服务器也可以返回如下内容来作为响应数据包:
{ method: 'sysServerStart', result: 'success' }
二、userLogin
客户端请求登录验证。
1、请求(xxc→xxd→xxb)数据包定义:
{ method: 'login', params: [ serverName, account, password, status ] }
数据包中变量定义如下:
- serverName:要登录的后端服务器名称,如果为默认后端服务器则可以留空为'';
- account:要执行登录验证的用户账号;
- password:用于进行登录验证的用户密码(加密后);
- status:登录成功后要设置的用户状态,可选值包括'online'(在线)、'away'(离开)、'busy'(忙碌)。
当用户登录验证成功响应数据包:
{ method: 'login', result: 'success', data: userData }
以上数据包中变量定义如下:
- userData:为当前执行登录验证的用户数据对象。
当用户登录验证失败时的响应数据包:
{ method: 'login', result: 'fail', message: failMessage }
以上数据包中变量定义如下:
- failMessage:为验证失败提示用户的文本消息,例如'用户名或密码不正确'。
当 XXD 服务器接收到用户登录验证响应消息并判断用户验证成功后会向系统中所有在线的非当前验证的用户推送一个数据包告知其他客户端有用户登录成功了。
通常此数据包对象为:
{ method: 'login', result: 'success', data: userData }
以上数据包中变量定义如下:
- userData:为成功登录的用户数据对象。
三、userKickoff
当已经在线的用户从一个新的客户端登录时,XXD 服务器会向旧的客户端上推送此数据包。
推送(xxd → xxc)
数据包定义:
{ method: 'userKickoff', result: 'success', message: kickOffMessage }
以上数据包中变量定义如下:
- kickOffMessage:为提示消息文本,例如'当前账号已在其他地方登录,如果不是本人操作,请及时修改密码'。
四、userLogout
请求注销登录状态,用户状态会设置为离线('offline')。
1、请求(xxc→xxd→xxb)
数据包定义:
{ userID: userID, method: 'userLogout' }
数据包中变量定义如下:
- userID:此数据包所对应操作所属的用户 ID。
当用户请求注销登录状态被后端服务器处理成功后,XXD 服务器会立即断开与请求注销的客户端的连接,并向所有在线的客户端推送如下数据包来告知其他在线用户该用户现在已经离线了:
{ method: 'userLogout', result: 'success', data: userData }其中数据包中的userData变量为注销登录状态的用户数据对象。
五、userGetList
从服务器获取用户列表数据。
1、请求(xxc→xxd→xxb 或 xxd→xxb)
数据包定义:{ userID: userID, method: 'userGetList', params: [ idList ] }
数据包中变量定义如下:
- userID:此数据包所对应操作所属的用户 ID;
- idList变量为要获取的用户 ID 列表,例如[1,23,31]会以列表形式返回用户 ID 分别为1、23和31的用户数据,默认为空字符串''会返回系统中所有未标记为删除的用户数据。
提示:当用户登录到系统并验证成功时,XXD 服务器会主动将此数据包发送给后端服务器,然后再将后端服务器处理响应数据包推送给客户端。这样客户端登录成功后无需手动发起请求就可以立即获取系统中的用户列表数据。
2、响应(xxb→xxd→xxc)数据包定义:
{ method: 'userGetList', result: 'success', depts: deptsData, roles: rolesData, data: userListData }
数据包中变量定义如下:
- deptsData:系统中所有部门数据,仅当返回系统中所有用户数据时提供(即当请求数据包中的params字段中的idList不为空);
- rolesData:系统中所有用户角色数据,仅当返回系统中所有用户数据时提供(即当请求数据包中的params字段中的idList不为空);
- userListData:用户列表数据为用户数据对象数组[userData]。
其中部门数据(deptsData)为一个纯 JS 对象,对象中的属性为部门 ID,对应的值为部门对象,部门对象包含的属性如下:
属性名称 | 类型 | 可选性 | 说明 |
---|---|---|---|
id | 数字或字符串 | 必须 | 部门对象在系统数据库中的 ID,通常为数据表主键 |
name | 字符串 | 必须 | 部门名称,例如'开发部' |
order | 数字 | 可选 | 部门在界面上显示的顺序,数值越大显示越靠后 |
parent | 数字或字符串 | 可选 | 父级部门 ID,如果为0或留空则表示为一级部门 |
下面为一个示例部门数据:
{ 1: { id: 1, name: '研发部', order: 1, parent: 0 }, 2: { id: 2, name: 'iOS 开发部', order: 2, parent: 1 } }其中用户角色数据(rolesData)为一个纯 JS 对象,对象中的属性为角色代码,对应的值为角色名称,下面为一个示例角色数据:
{ dev: '研发', office: '行政', pm: `项目经理` }
六、chatGetList
从服务器获取系统中所有会话数据。
1、请求(xxc→xxd→xxb 或 xxd→xxb)数据包定义:
{ userID: userID, method: 'chatGetList' }
数据包中变量定义如下:
- userID:此数据包所对应操作所属的用户 ID。
提示:当用户登录到系统并验证成功时,XXD 服务器会主动将此数据包发送给后端服务器,然后再将后端服务器处理响应数据包推送给客户端。这样客户端登录成功后无需手动发起请求就可以立即获取系统中的会话列表数据。
2、响应(xxb→xxd→xxc)数据包定义:
{ method: 'chatGetList', result: 'success', data: chatListData }
数据包中变量定义如下:
- chatListData:系统中所有会话数据,以会话数据对象数组[chatData]的形式返回。
七、sysSessionID
由 XXD 服务器将客户端在 XXD 服务器上用于 HTTP 协议接口的 SessionID 推送给客户端。
推送(xxd → xxc)
XXD 服务器会在用户登录验证成功之后主动将此数据包推送给登录的用户。该数据包定义为:
{ method: 'sysSessionID', sessionID: sessionID }其中sessionID变量为用于 HTTP 协议接口的 SessionID。
八、messageSend
向会话发送消息,用户可以通过此数据包向指定会话发送一个或多个会话消息,后端服务器会将消息推送给会话中所有在线用户,会话中不在线的用户会存储为离线消息,在用户下次上线时通过 messageSend 推送给用户。
1、请求(xxc→xxd→xxb)数据包定义:
{ userID: userID, method: 'messageSend', params: [sendMessageList] }
数据包中变量定义如下:
- userID:此数据包所对应操作所属的用户 ID;
- sendMessageList:为要发送的消息对象数组[sendMessage]。
服务器端接收到发送消息请求数据包后会将消息存储到数据库,并返回一个推送数据包发送给会话成员中所有在线的用户客户端;不在线的用户会存储为离线消息,在用户下次登录时会推送给用户。
推送数据包定义为:
{ method: 'messageSend', result: 'success', data: messageList }其中messageList变量为已发送的会话消息对象数组[messageData]。
九、syncOfflineMessages
获取用户离线时接受到的消息,通常在用户登录验证成功之后由 XXD 服务器主动请求后端服务器,后端服务器将离线消息通过messageSend推送给用户客户端。
1、请求(xxd→xxb)数据包定义:
{ userID: userID, method: 'syncOfflineMessages' }
数据包中变量定义如下:
- userID:此数据包所对应操作所属的用户 ID。
离线消息推送是通过 messageSend 数据包实现的。
十、userUpdate
更改当前登录的用户信息。
1、请求(xxc→xxd→xxb)数据包定义:
{ userID: userID, method: 'userUpdate', params: [ userChangeData ] }
数据包中变量定义如下:
- userID:此数据包所对应操作所属的用户 ID;
- userChangeData:为要更改的用户属性,该变量为一个对象,属性名称为要更改的用户对象属性名称,值为更改后的值。
目前仅支持更改如下属性值:
属性名称 | 类型 | 说明 |
---|---|---|
status | 字符串 | 要变更的用户状态,可选值包括'online'(在线)、'away'(离开)、'busy'(忙碌) |
password | 字符串 | 要变更的用户密码,需要提供原始密码,数据库会对密码加密后进行存储 |
例如下面为一个请求设置当前登录用户状态为忙碌('busy')的数据包:
{ userID: 12, method: 'userUpdate', params: [ { status: 'busy' } ] }2、响应(xxb→xxd→xxc)
数据包定义:
{ method: 'userUpdate', result: 'success', data: userData }其中数据包中的userData变量为信息发生变更的用户数据对象。
十一、chatCreate
请求创建一个新的会话。
1、请求(xxc→xxd→xxb)数据包定义:
{ userID: userID, method: 'chatCreate', params: [ cgid, name, type, members, subject, public ] }
数据包中变量定义如下:
- userID:此数据包所对应操作所属的用户 ID;
- cgid:必须项,为要创建的会话对象全局唯一字符串;
- name:会话名称,如果为一对一会话则可以留空;
- type:会话类型,可选值包括:'system'(系统会话),'one2one'(一对一会话),'group'(多人讨论组),以及系统自定义的类型,例如'project'(禅道项目),'product'(禅道产品)等;
- members:会话成员的 ID 列表,例如[12,43,32]分别表示要创建的会话成员中包含用户 ID 为12、43和32的用户;
- subject:会话成员的 ID 列表,例如[12,43,32]分别表示要创建的会话成员中包含用户 ID 为12、43和32的用户;
- public:如果值为true且类型(type)非一对一会话(one2one)时则将会话设置为公开会话。
提示:客户端在向服务器通过此数据包发送消息时,确保为新的会话对象生成了全局唯一字符串(RFC4122)作为gid属性。如果你使用 JavaScript 可以使用 uuid 模块来实现。
2、推送(xxb→xxd→xxc)后端服务器接收到请求数据包时先检查对应gid的会话是否存在,如果存在则返回已有的会话信息,如果不存在则创建一个会话并推送新创建的会话信息给该会话成员内所有已在线的客户端。
数据包定义:
{ method: 'chatCreate', result: 'success', data: chatData }其中chatData为系统中已经存在或者刚刚创建的会话数据对象。
十二、chatJoin
加入一个会话。
1、请求(xxc→xxd→xxb)数据包定义:
{ userID: userID, method: 'chatJoin', params: [ cgid, ] }
数据包中变量定义如下:
- userID:此数据包所对应操作所属的用户 ID;
- cgid:要加入的会话gid属性。
后端服务器接收到请求数据包时先检查用户是否能够加入会话,如果能加入将更新会话对象的成员列表信息,然后将新的会话对象推送给会话内所有在线的成员用户。
数据包定义:
{ method: 'chatJoin', result: 'success', data: chatData }其中chatData为系统中的会话数据对象。
十三、chatLeave
退出一个会话。
1、请求(xxc→xxd→xxb)数据包定义:
{ userID: userID, method: 'chatLeave', params: [ cgid, ] }
数据包中变量定义如下:
- userID:此数据包所对应操作所属的用户 ID;
- cgid:要退出的会话gid属性。
2、推送(xxb→xxd→xxc)
数据包定义:{ method: 'chatJoin', result: 'success', data: chatData }其中chatData为系统中的会话数据对象。
十四、chatRename
修改会话名称。
提示:当前版本中仅支持对讨论组类型的会话进行名称修改操作。
1、请求(xxc→xxd→xxb)数据包定义:
{ userID: userID, method: 'chatRename', params: [ gid, newChatName ] }
数据包中变量定义如下:
- userID:此数据包所对应操作所属的用户 ID;
- gid:要修改名称的会话gid属性;
- newChatName:要修改的新名称。
后端服务器接收到请求数据包时先检查用户是否能够修改此会话名称,如果能则存储新的名称,然后将新的会话对象推送给会话内所有在线的成员用户。
数据包定义:
{ method: 'chatRename', result: 'success', data: chatData }其中chatData为系统中的会话数据对象。
十五、chatInvite
邀请用户到讨论组中。
1、请求(xxc→xxd→xxb)数据包定义:
{ userID: userID, method: 'chatInvite', params: [ gid, members, ] }
数据包中变量定义如下:
- userID:此数据包所对应操作所属的用户 ID;
- gid:要操作的会话对象的gid属性;
- membersList:要邀请的用户 ID 列表,例如[12,2]则将邀请 ID 为12和2的用户;
后端服务器接收到请求数据包并操作成功后会将变更后的会话对象推送给会话内所有在线的成员用户。
数据包定义:
{ method: 'chatInvite', result: 'success', data: chatData }其中chatData为系统中的会话数据对象。
十六、chatKick
从讨论组中移除用户。
1、请求(xxc→xxd→xxb)数据包定义:
{ userID: userID, method: 'chatKick', params: [ gid, members, ] }
数据包中变量定义如下:
- userID:此数据包所对应操作所属的用户 ID;
- gid:要操作的会话对象的gid属性;
- membersList:要移除的用户 ID 列表,例如[12,2]则将移除 ID 为12和2的用户;
后端服务器接收到请求数据包并操作成功后会将变更后的会话对象推送给会话内所有在线的成员用户(包括本次被从讨论组中移除的用户)。
数据包定义:
{ method: 'chatKick', result: 'success', data: chatData }其中chatData为系统中的会话数据对象。
十七、chatStar
收藏或取消收藏指定的会话。
1、请求(xxc→xxd→xxb)数据包定义:
{ userID: userID, method: 'chatStar', params: [ star, gid, ] }
数据包中变量定义如下:
- userID:此数据包所对应操作所属的用户 ID;
- star:如果为true则表示进行收藏操作,如果为false则进行取消收藏操作;
- gid:要操作的会话gid属性。
数据包定义:
{ method: 'chatStar', result: 'success', data: { gid: gid, star: star, } }
数据包中变量定义如下:
- gid:所操作的会话gid属性;
- star:如果为true则表示已完成收藏操作,如果为false则已完成取消收藏操作。
十八、chatMute
设置会话为免打扰或取消设置为免打扰。
1、请求(xxc→xxd→xxb)
数据包定义:
{ userID: userID, method: 'chatMute', params: [ mute, gid, ] }
数据包中变量定义如下:
- userID:此数据包所对应操作所属的用户 ID;
- mute:如果为true则表示进行设置免打扰,如果为false则进行取消取消设置免打扰操作;
- gid:要操作的会话gid属性。
数据包定义:
{ method: 'chatMute', result: 'success', data: { gid: gid, mute: mute } }
数据包中变量定义如下:
- gid:所操作的会话gid属性;
- mute:如果为true则表示已完成设置免打扰操作,如果为false则已完成取消设置免打扰操作。
十九、chatFreeze
将会话暂时从最近会话列表上移除或者取消移除状态。
1、请求(xxc→xxd→xxb)数据包定义:
{ userID: userID, method: 'chatMute', params: [ frozen gid, ] }
数据包中变量定义如下:
- userID:此数据包所对应操作所属的用户 ID;
- frozen:如果为true则表示设置从活动会话列表移除,如果为false则取消设置从活动会话列表移除;
- gid:要操作的会话gid属性。
数据包定义:
{ method: 'chatMute', result: 'success', data: { gid: gid, } }
其中gid为设置的会话 GID
数据包中变量定义如下:
- gid:所操作的会话gid属性;
- frozen:如果为true则表示已完成设置从活动会话列表移除,如果为false则已完成取消设置从活动会话列表移除。
二十、chatHide
用户存档或取消存档指定的会话。
提示:存档后的会话在最近会话列表上不可见。
1、请求(xxc→xxd→xxb)
数据包定义:
{ userID: userID, method: 'chatHide', params: [ cgid, hide ] }
数据包中变量定义如下:
- userID:此数据包所对应操作所属的用户 ID;
- cgid:要操作的会话gid属性;
- hide:当为true或留空时则为将会话设置为存档,否则为取消存档。
数据包定义:
{ method: 'chatHide', result: 'success', data: chatData }其中chatData为系统中的会话数据对象。
二十一、chatSetCategory
设置会话在界面上显示的分组名称。
1、请求(xxc→xxd→xxb)数据包定义:
{ userID: userID, method: 'chatSetCategory', params: [ cgid, category ] }
数据包中变量定义如下:
- userID:此数据包所对应操作所属的用户 ID;
- cgid:要操作的会话gid属性;
- category:要设置的分组名称。
2、响应(xxb→xxd→xxc)
数据包定义:
{ method: 'chatSetCategory', result: 'success', data: { gids: gids, category: category } }其中gids为已设置分组名称的会话 GID 属性列表;category为设置后的分组名称。
二十二、chatRenameCategory
重命名会话列表上的分组名称。
1、请求(xxc→xxd→xxb)数据包定义:
{ userID: userID, method: 'chatRenameCategory', params: [ cgids, category ] }
数据包中变量定义如下:
- userID:此数据包所对应操作所属的用户 ID;
- cgids:要操作的会话gid属性列表;
- category:要设置的分组名称。
数据包定义:
{ method: 'chatRenameCategory', result: 'success', data: { gids: gids, category: category } }其中gids为已设置分组名称的会话 GID 属性列表;category为设置后的分组名称。
二十三、chatDeleteCategory
移除会话在界面上的自定义的分组名称。
1、请求(xxc→xxd→xxb)数据包定义:
{ userID: userID, method: 'chatDeleteCategory', params: [ cgids, ] }
数据包中变量定义如下:
- userID:此数据包所对应操作所属的用户 ID;
- cgids:要操作的会话gid属性列表。
2、响应(xxb→xxd→xxc)
数据包定义:{ method: 'chatDeleteCategory', result: 'success', data: { gids: gids, } }其中gids为已设置分组名称的会话 GID 属性列表。
二十四、chatSetVisibility
设置讨论组可见性,可以设置为公开讨论组或非公开讨论组。
当讨论组被设置为公开后,非讨论组内的成员可以看见讨论组名称并自由加入公开的讨论组。
1、请求(xxc→xxd→xxb)数据包定义:
{ userID: userID, method: 'chatSetVisibility', params: [ gid, public ] }
数据包中变量定义如下:
- userID:此数据包所对应操作所属的用户 ID;
- gid:要操作的会话gid属性;
- public:当为true或留空时则为将会话设置为公开讨论组,否则为取消设置公开讨论组。
后端服务器接收到请求数据包时先检查用户是否能够进行此操作,如果能操作成功将操作后的会话对象推送给会话内所有在线的成员用户。
数据包定义:
{ method: 'chatSetVisibility', result: 'success', data: chatData }其中chatData为系统中的会话数据对象。
二十五、chatGetPublicList
获取系统中所有已设置为公开的讨论组列表。
1、请求(xxc→xxd→xxb)数据包定义:
{ userID: userID, method: 'chatGetPublicList' }
数据包中变量定义如下:
- userID:此数据包所对应操作所属的用户 ID。
数据包定义:
{ method: 'chatGetPublicList', result: 'success', data: chatDataList }其中chatDataList为系统中的会话数据对象数组[chatData]。
二十六、chatSetAdmin
设置会话成员内的指定用户为管理员。
1、请求(xxc→xxd→xxb)数据包定义:
{ userID: userID, method: 'chatSetAdmin', params: [ cgid, adminsList, ] }
数据包中变量定义如下:
- userID:此数据包所对应操作所属的用户 ID;
- cgid:要操作的会话gid属性;
- adminsList:以数组形式表示要操作的用户 ID 列表,例如[1,23,31]要操作的用户 ID 分别为1、23和31。
2、推送(xxb→xxd→xxc)
后端服务器接收到请求数据包时先检查用户是否能够进行此操作,如果能操作成功将操作后的会话对象推送给会话内所有在线的成员用户。
数据包定义:
{ method: 'chatSetAdmin', result: 'success', data: chatData }其中chatData为系统中的会话数据对象。
二十七、chatRemoveAdmin
取消会话成员内的指定用户的管理员身份。
1、 请求(xxc→xxd→xxb)数据包定义:
{ userID: userID, method: 'chatRemoveAdmin', params: [ gid, adminsList, ] }
数据包中变量定义如下:
- userID:此数据包所对应操作所属的用户 ID;
- gid:要操作的会话gid属性;
- adminsList:以数组形式表示要操作的用户 ID 列表,例如[1,23,31]要操作的用户 ID 分别为1、23和31。
后端服务器接收到请求数据包时先检查用户是否能够进行此操作,如果能操作成功将操作后的会话对象推送给会话内所有在线的成员用户。
数据包定义:
{ method: 'chatRemoveAdmin', result: 'success', data: chatData }其中chatData为系统中的会话数据对象。
二十八、chatSetCommitters
设置会话能够发言的成员名单,或者修改名单类型。
1、 请求(xxc→xxd→xxb)数据包定义:
{ userID: userID, method: 'chatSetCommitters', params: [ gid, committers ] }
数据包中变量定义如下:
- userID:此数据包所对应操作所属的用户 ID;
- gid:要操作的会话gid属性;
- committers:会话允许用户发言(在会话中发布消息)的用户 ID 列表,多个用户 ID 使用英文逗号分隔,其中特殊值'$ADMINS'表示仅允许管理员发言,如果留空或者使用特殊值'$ALL'则表示允许会话中所有人发言。
后端服务器接收到请求数据包时先检查用户是否能够进行此操作,如果能操作成功将操作后的会话对象推送给会话内所有在线的成员用户。
数据包定义:
{ method: 'chatSetCommitters', result: 'success', data: chatData }其中chatData为系统中的会话数据对象。
二十九、chatDismiss
解散一个讨论组。
目前仅支持会话成员中的管理员解散讨论组。
1、 请求(xxc→xxd→xxb)数据包定义:
{ userID: userID, method: 'chatDismiss', params: [ cgid ] }
数据包中变量定义如下:
- userID:此数据包所对应操作所属的用户 ID;
- cgid:要操作的会话gid属性。
后端服务器接收到请求数据包时先检查用户是否能够进行此操作,如果能操作成功将操作后的会话对象推送给会话内所有在线的成员用户。
数据包定义:
{ method: 'chatDismiss', result: 'success', data: chatData }
其中chatData为系统中的会话数据对象。
已解散的会话在用户界面上一定时期内仍会存在,但会提示讨论组已经被解散。
三十、chatGetHistory
获取会话的消息记录。
使用分页参数通过多次请求可以实现获取服务器端全部消息历史记录数据。
1、 请求(xxc→xxd→xxb)数据包定义:
{ userID: userID, method: 'chatGetHistory', params: [ gid, recPerPage, pageID, recTotal, continued, startDate ] }
数据包中变量定义如下:
- userID:此数据包所对应操作所属的用户 ID;
- gid:要获取会话记录的会话gid属性;
- recPerPage:分页信息,用于限定每次请求返回的最大会话消息数目;
- pageID:分页信息,用户设置当前要获取的页面序号;
- recTotal:分页信息,表示已知的总消息记录数目,如果为0则表示客户端请求时并不指定总消息记录数目(通常为第一次发起请求);
- continued:分野信息,如果为true表示客户端是否是接上次请求持续获取其他页面的消息记录数目,此字段会在响应请求中包含方便客户端进行跟踪;
- startDate:要获取的记录中会话消息发送日期最小值,使用时间戳格式(精确到秒),也就是仅仅获取此时间之后的发出的会话消息。
数据包定义:
{ method: 'chatGetHistory', result: 'success', data: chatDataList, pager: pagerData }
数据包中的变量定义:
- chatDataList:系统中的会话数据对象 数组[chatData];
- pagerData:分页信息对象。
三十一、userSyncSettings
上传或下载用户在客户端上的个人配置数据。个人配置数据使用一个 JSON 对象来存储,对象的属性对应配置项名称,对象的属性值为对应配置项的值。
1、 请求(xxc→xxd→xxb)数据包定义:
{ userID: userID, method: 'userSyncSettings', params: [ account, settings ] }
数据包中变量定义如下:
- userID:此数据包所对应操作所属的用户 ID;
- account:个人配置所属的用户账号;
- settings:根据此参数字段的类型不同,执行不同的操作,支持的类型包括:
- 如果为空字符串'',则表示请求从服务器下载用户的所有配置项,后端服务器应该使用一个对象返回该用户在服务器上存储的所有个人配置;
- 如果为字符串数组,例如['shortcut.captureScreen', 'shortcut.sendMessage'],则表示请求返回数组中列出的配置项的值,以对象的形式返回所有列出的配置项的值,例如:
{ "shortcut.captureScreen": "Ctrl+Alt+Z", "shortcut.sendMessage": "Enter" }如果为对象,例如{"shortcut.captureScreen": "Ctrl+Alt+Z", "shortcut.sendMessage": "Enter"},则表示将对象中的配置项合并到服务器的配置对象中。
2、响应(xxb→xxd→xxc)
数据包定义:
{ method: 'userSyncSettings', result: 'success', data: settings, }
数据包中的变量定义:
- settings:为用户请求或修改后的用户个人配置对象。
三十二、syncUsers
此数据包由 XXD 服务器定期向后端服务器发送,用户检查系统中是否由用户信息变更操作(包括添加了新用户、删除了用户或者修改了用户信息),来决定是否向客户端推送 userGetList 数据。
1、请求(xxd→xxb)数据包定义:
{ userID: userID, method: 'syncUsers' }
数据包中变量定义如下:
- userID:此数据包所对应操作所属的用户 ID。
数据包定义:
{ method: 'syncUsers', result: 'success', data: checkResult, }
数据包中的变量定义:
- checkResult:为服务器检查结果,如果为'yes',表示从上次检查以来系统中有用户信息变更操作,其他值则表示没有用户信息变更操作。
如果检查结果表示系统中由用户信息变更操作,则由 XXD 服务器向后端服务器发送请求 userGetList 数据包。
4、推送(xxb→xxd→xxc)
如果检查结果表示系统中由用户信息变更操作,则由 XXD 服务器向后端服务器发送请求 userGetList 数据包,后端服务器会将新的用户列表数据通过此数据包推送给所有客户端,使得客户端上的用户信息得到更新。
三十三、syncNotifications
获取系统通知消息。
系统通知消息在界面上会显示在名称为 “小喧喧” 的会话界面中。
1、请求(xxd→xxb)当用户登录验证(chatlogin)成功后由 XXD 服务器向后端服务器发送请求获取用户系统通知的请求数据包,该数据包定义:
{ userID: userID, method: 'syncNotifications', }
数据包中变量定义如下:
- userID:此数据包所对应操作所属的用户 ID。
数据包定义:
{ method: 'syncNotifications', result: 'success', data: notifitionList, }
其中notifitionList变量为通知消息对象数组[notifitionData]。
三十四、chatTyping
向其他用户发送我正在输入的状态。
1、请求(xxc→xxd)当用户启用发送输入状态且正在一对一会话界面发送框进行输入操作时会向其他用户发送状态。此状态数据包会发送给 XXD,该数据包定义:
{ userID: userID, method: 'chatTyping', params: [ othersIDList, cgid, typing ] }
数据包中变量定义如下:
- userID:此数据包所对应操作所属的用户 ID;
- othersIDList:需要接收此状态的所有用户 ID 属性列表;
- cgid:当前会话的 GID 属性;
- typing:布尔值表示当前状态是否正在输入,如果为true为正在输入,否则为已停止输入。
XXD 接收到chatTyping数据包后会立即将状态分发给需要接收此状态的用户,数据包定义如下:
{ method: 'chatTyping', result: 'success', data: { cgid, typing, user } }
数据包中变量定义如下:
- user:用户 ID,表示此状态为哪个用户发送过来的;
- cgid:当前会话的 GID 属性;
- typing:布尔值表示当前状态是否正在输入,如果为true为正在输入,否则为已停止输入。
三十五、userSetDeviceToken
向服务器报告当前登录的设备 Token。
1、请求(xxc→xxd→xxb)数据包定义:
{ userID: userID, method: 'userSetDeviceToken', params: [ deviceToken, deviceType, ] }
数据包中变量定义如下:
- userID:此数据包所对应操作所属的用户 ID;
- deviceToken:设备 Token 字符串;
- deviceType:设备类型,例如'android'、'ios'等。
数据包定义:
{ method: 'userSetDeviceToken', result: 'success' }
三十六、extensionGetList
获取服务器上安装的客户端扩展列表。
要了解更多请参考“远程客户端扩展”文档。
1、请求(xxd→xxb)当用户登录验证(chatlogin)成功后由 XXD 服务器向后端服务器发送请求获取用户客户端上可以使用的客户端扩展列表,该数据包定义:
{ userID: userID, method: 'extensionGetList', }
数据包中变量定义如下:
- userID:此数据包所对应操作所属的用户 ID。
数据包定义:
{ method: 'extensionGetList', result: 'success', data: extensionList, }
其中extensionList变量为客户端扩展信息对象数组[extensionData]。客户端扩展信息对象包括如下属性:
属性名称 | 类型 | 可选性 | 说明 |
---|---|---|---|
name | 字符串 | 必须 | 用于标识扩展内部名称 |
displayName | 字符串 | 必须 | 扩展在界面上显示的名称 |
entryID | 数字或字符串 | 可选 | 表示扩展对应的应用在系统中的 ID |
logo | 字符串 | 可选 | 扩展图标图片地址 |
download | 字符串 | 必须 | 扩展包下载地址 |
md5 | 字符串 | 必须 | 扩展包 MD5 值,用于客户端判断是否扩展包是否更新 |
webViewUrl | 字符串 | 可选 | 扩展对应的应用默认访问地址 |
data | 任意类型 | 可选 | 后端服务器通过此属性来传递额外的数据给扩展包 |
三十七、extensionGetAccessURL
获取系统中内置应用免登录访问地址。
1、请求(xxd→xxb)当用户登录验证(chatlogin)成功后由 XXD 服务器向后端服务器发送请求获取用户系统通知的请求数据包,该数据包定义:
{ userID: userID, method: 'extensionGetAccessURL', params: [ entryID, referer ] }
数据包中变量定义如下:
- userID:此数据包所对应操作所属的用户 ID;
- entryID:必须,要访问的应用入口 ID;
- referer:要访问的应用地址,如果留空则实际返回应用的首页地址。
2、响应(xxb→xxd→xxc)
数据包定义:
{ method: 'extensionGetAccessURL', result: 'success', data: visitUrl, }其中visitUrl变量为生成的免登录访问地址。
三十八、sysError
当系统发生错误时由 XXD 通过此接口将错误信息报告给 XXC。
推送(xxd → xxc )
数据包定义:
{ method: 'sysError', result: 'fail', message: failMessage, }其中failMessage:为操作失败提示用户的文本消息,例如'用户名或密码不正确'。
三十九、通用操作失败响应数据包定义
当执行某个操作失败时后端服务器或 XXD 服务器会返回失败响应数据包,通常表示操作失败的数据包定义为:
{ method: methodName, result: 'fail', message: failMessage }
数据包中变量定义如下:
- methodName:为数据包操作模块内方法名称,例如'message';
- failMessage:为操作失败提示用户的文本消息,例如'用户名或密码不正确'。
微信公众号