README

IM-CLIENT-SDK

Installation

npm install im-client-sdk --save

How to use

import IOClientSDK from 'im-client-sdk';
import { SSO_QRLOGIN } from 'im-client-sdk/dist/constant';

// initialize a io client
const instance = new IOClientSDK({
  root: 'http://localhost:7001', // root url
  nsp: 'sso',                    // namespace 'sso' || 'chat'
  query: {
    token: 'xxx',
  },
});

// get the socket instance
// reference the socket.io socket
const socket = instance.getSocket();

instance.emit(SSO_QRLOGIN, 'ping');

instance.on(SSO_QRLOGIN, (resp) => {
  console.log(resp);
})

// destroy current socket instance
instance.destroySocket();

// close current socket instance
instance.closeSocket();

API Documentation

new IOClientSDK({root, nsp, [, options]})

root (String) socket 连接根路径
nsp (String) socket 连接命名空间 namespace 'sso' || 'chat'
options (Object)
Returns IOClientSDK (instance)

options 参数配置： https://socket.io/docs/client-api/#new-Manager-url-options

instance.getSocket()

Returns Socket

返回初始化后 Socket.io 的 Socket 实例

socket 实例的 API：https://socket.io/docs/client-api/#Socket

instance.openSocket()

socket.open()

socket 实例的 open 方法：https://socket.io/docs/client-api/#socket-open

instance.closeSocket()

socket.close()

socket 实例的 close 方法：https://socket.io/docs/client-api/#socket-close

instance.destroySocket()

销毁 socket 连接

instance.destroy()

断开 socket 连接，并销毁 IOClientSDK 实例

instance.on(eventName, callback)

eventName (String) 事件名称 Tips: 事件列表见 Emit cheatsheet
callback (Function)

instance.on 不等价于 socket.on, 以发布订阅的监听回调作为 instance.on 的入参。确保整个连接只订阅一次，可以在 SDK 里扩展事件处理。see here

instance.emit(eventName[, …args][, ack])

eventName (String)
args
ack (Function)
Returns Socket

instance.emit 等价于 socket.emit, 这么做的目的是为了收敛发射事件的逻辑。see here

具体 API 可以参见：https://socket.io/docs/client-api/#socket-emit-eventName-%E2%80%A6args-ack

Emit cheatsheet

Please see the cheatsheet here.

IO 通用数据返回格式

{
  meta: {
    timestamp: 1585236081249  // server timestamp
  },
  code: 0,                    // enum: [ 0 -> success   1 -> fail   other -> another errors ]
  data: {
    action: 'SSO_QRLOGIN',    // event name
    payload: {},              // response data
  }
}

Socket 事件文档

通用事件

1. IMERROR

事件名称： IMERROR

事件归属命名空间：全局

详细说明：监听该事件可以获取到业务错误码

连接入参值：无需入参

返回值：错误码 cheapsheet

错误代码	错误信息	详细描述
20001	Auth failed	【鉴权失败】可能 token 过期，需要重新登录
20002	Parameter absent	【缺失参数】缺失必要的请求参数
20003	Send message failed	【发送失败】消息发送失败，可能是因为非法获取到群 ID，并向该群发送消息
20004	you are sign in on other device	【重复登录】在另外一台设备上登录，会踢出当前登录设备。目前支持有且仅在一台移动设备和桌面端设备上登录

代码示例：

使用方式：

import { IMERROR } from 'im-client-sdk/dist/constant';

const instance = new IOClientSDK({
  root: 'http://localhost:7001',
  nsp: 'chat',
});

instance.on(IMERROR, (resp) => {
  // TODO
});

返回值

// eg: 重复登录错误
{
  meta: {
    timestamp: 1585236081249,
    msg: "you are sign in on other device",
    },
  code: 20004, // 错误码
  data: {
    action: 'IMERROR',
    payload: null,
  }
}

订阅事件

1. SSO_QRLOGIN

事件名称：SSO_QRLOGIN

事件归属命名空间：sso

详细说明：PC 端通过订阅 SSO_QRLOGIN 事件来实时获取移动端扫码登录是否成功

连接入参值：详细见代码示例 - 使用方法

device_id 设备 ID

返回值：详细见代码示例 - 返回值

代码示例：

使用方式：

import { SSO_QRLOGIN } from 'im-client-sdk/dist/constant';

const instance = new IOClientSDK({
  root: 'http://localhost:7001',
  nsp: 'sso',
  query: {
    device_id: 'xxx', // 需要传入 device_id
  },
});

instance.on(SSO_QRLOGIN, (resp) => {
  // TODO
});

返回值

// 1. success 状态
{
  meta: { timestamp: 1585236081249 },
  code: 0,                            // 成功状态码
  data: {
    action: 'SSO_QRLOGIN',
    payload: {
      token: 'xxx'                    // 返回登录的 token
    },
  }
}

// 2. fail 状态
{
  meta: { timestamp: 1585236081249 },
  code: 1,                            // 失败状态码
  data: {
    action: 'SSO_QRLOGIN',
    payload: {},                      // 不返回任何 payload
  }
}

2. CHAT_ONLINE

事件名称：CHAT_ONLINE

事件归属命名空间：chat

详细说明：订阅 CHAT_ONLINE 事件来实时获取当前所有在线的用户列表，当有用户上线或者离线的时候，都会更新用户列表。

连接入参值：详细见代码示例 - 使用方法

token 客户端登录的 token 信息
userId 当前用户 ID

返回值：详细见代码示例 - 返回值

代码示例：

使用方式：

import { CHAT_ONLINE } from 'im-client-sdk/dist/constant';

const instance = new IOClientSDK({
  root: 'http://localhost:7001',
  nsp: 'chat',
  query: {
    token: 'xxx',  // 需传入当前登录 token
    userId: '111', // 需传入当前用户 ID
  },
})

instance.on(CHAT_ONLINE, (resp) => {
  // TODO
});

返回值

// 当有用户上线时
{
  meta: { timestamp: 1585236081249 },
  code: 0,
  data: {
    action: 'CHAT_ONLINE',
    payload: {
      type: 'online',           // 上线推送类型 or 离线推送类型
      current: '111',           // 上线的用户 ID
      clients: ['111', '222'],  // 用户列表
    },
  }
}

// 当有用户离线时
{
  meta: { timestamp: 1585236081249 },
  code: 0,
  data: {
    action: 'CHAT_ONLINE',
    payload: {
      type: 'offline',          // 离线推送类型
      current: '222',           // 离线的用户 ID
      clients: ['111'],         // 用户列表
    },
  }
}

3. CHAT_MESSAGE

事件名称：CHAT_MESSAGE

事件归属命名空间：chat

详细说明：订阅 CHAT_MESSAGE 事件来实时获取其他用户发送给你点对点消息。消息协议见：这里

连接入参值：详细见代码示例 - 使用方法

token 客户端登录的 token 信息
userId 当前用户 ID

返回值：详细见代码示例 - 返回值

代码示例：

使用方式：

import { CHAT_MESSAGE } from 'im-client-sdk/dist/constant';

const instance = new IOClientSDK({
  root: 'http://localhost:7001',
  nsp: 'chat',
  query: {
    token: 'xxx',  // 需传入当前登录 token
    userId: '111', // 需传入当前用户 ID
  },
})

instance.on(CHAT_MESSAGE, (resp) => {
  // TODO
});

返回值

// 当有用户发送消息
// 消息字段协议见：[](/src/protocal.js)
{
  meta: { timestamp: 1585236081249 },
  code: 0,
  data: {
    action: 'CHAT_MESSAGE',
    payload: {
      type: 1,
      from: "222",
      to: "111",
      content: "content",
      fp: "yv5Fpp7NvKrdD93",
      time: 1586941056440,
      typeu: -1,
    },
  }
}

发射事件

1. CHAT_TO

事件名称：CHAT_TO

事件归属命名空间：chat

详细说明：可以通过发射 CHAT_TO 事件向其他用户发送消息， 消息协议见：这里

连接入参值：详细见代码示例 - 使用方法

token 客户端登录的 token 信息
userId 当前用户 ID

返回值：无返回值

代码示例：

使用方式：

import { CHAT_TO } from 'im-client-sdk/dist/constant';
import { createMsgProtocal } from 'im-client-sdk/dist/protocal';

const instance = new IOClientSDK({
  root: 'http://localhost:7001',
  nsp: 'chat',
  query: {
    token: 'xxx',  // 需传入当前登录 token
    userId: '111', // 需传入当前用户 ID
  },
})

// 可以调用 SDK 提供的 createMsgProtocal 方法创建消息体
const msg = createMsgProtocal({
  type: 1,                // 消息类型 1: 文本消息 2: 图片消息 3: 语音消息
  from: '111',            // 消息发送者 uid
  to: '222',              // 消息接收者 uid
  content: '输入的内容',    // 消要发送的数据内容
});

instance.emit(CHAT_TO, msg);

// c2g 消息和 c2c 消息事件一致
// 注意 typeu 字段，该字段是用来标记消息域，
// typeu: 1 表示 c2c 消息，defaultValue 就是 1，所以可以不传
// typeu: 2 表示 c2g 消息，如果是群消息需要传该字段并标记为 2
const msg = createMsgProtocal({
  type: 1,                // 消息类型 1: 文本消息 2: 图片消息 3: 语音消息
  from: '111',            // 消息发送者 uid
  to: '5e9d4c2898b',      // 群 ID
  content: '输入的内容',    // 要发送的数据内容
  typeu: 2,               // 消息域标记位,
});

License

MIT

Usage no npm install needed!

README

IM-CLIENT-SDK

Installation

How to use

API Documentation

new IOClientSDK({root, nsp, [, options]})

instance.getSocket()

instance.openSocket()

instance.closeSocket()

instance.destroySocket()

instance.destroy()

instance.on(eventName, callback)

instance.emit(eventName[, …args][, ack])

Emit cheatsheet

IO 通用数据返回格式

Socket 事件文档

通用事件

1. IMERROR

订阅事件

1. SSO_QRLOGIN

2. CHAT_ONLINE

3. CHAT_MESSAGE

发射事件

1. CHAT_TO

License