在线状态订阅 - IM 即时通讯（含 UI）

更新时间： 2024/03/14 18:45:30

用户可以通过事件发布及订阅，来实现"发布-订阅"的设计模式编程方法。可应用于订阅指定用户在线状态、用户个性化信息订阅、逻辑异步流处理等场景。
目前，仅开放类型type=1的事件订阅，用户可自定义value值（一个value对应一个事件状态，1-9999为云信预定义值，开发者不可使用）来实现自身业务需求。
大致流程为：A订阅B——>B发布某一特定的事件——>A监听来自B的该事件状态变更——>按照自身业务逻辑解析处理。
注意：云信系统内置的在线状态事件(type=1,value=1/2/3)无需主动发布，这一工作将由云信服务器托管。

前提条件

在线状态订阅功能需要额外在云信控制台开通。

开通路径：应用管理 > 产品功能 > IM 即时通讯 > 全局功能 > 在线状态订阅

订阅事件

向特定用户订阅事件。无论是内置的在线状态事件或是自定义的事件，都需要通过该接口发起订阅。每个帐号最大有效订阅帐号不超过 3000 个。

多端订阅（指同一账号在其他类型客户端订阅）会覆盖这个订阅有效期，所以建议开发者各端订阅时长保持一致。在30秒内对同一账号同一事件订阅，即使设置为立即同步服务的也不会下发目标事件。

示例代码

javascript  nim.subscribeEvent({
      type: 1,
      accounts: ['cs3', 'cs4'],
      subscribeTime: 70,
      sync: true,
      done: subscribeEventDone
  });
  function subscribeEventDone(error, obj) {
      console.log('订阅事件' + (!error?'成功':'失败'), error, obj);
  }

参数解释

type, 事件类型，传入1即可。
subscribeTime, 订阅关系的有效时间，单位秒 60s~30天(2592000)，默认30天。
sync 订阅后是否立即同步最新事件，true:同步，false:不同步，默认同步
vaildTime, 用户发布事件的有效时间，可选参数，以秒为单位，范围在60s~7天(604800s)，默认7天
broadcastType, 事件广播类型，可选参数，1:仅在线 2:在线和离线，默认2(在线和离线)
done, 用户自定义的结果回调函数
- 此回调包含两个参数，第一个参数为error，如果成功则error为null；第二个参数为obj, 它有一个字段failedAccounts的值为操作的类型, 具体类型如下：
  - failedAccounts, 失败的账号数组，如果为空数组则表示操作全部成功

取消订阅

按账号取消订阅

取消自己针对指定账号的订阅事件。

示例代码

javascript  nim.unSubscribeEventsByAccounts({
      type: 1,
      accounts: ['cs3'],
      done: unSubscribeEventDone
  });
  function unSubscribeEventDone(error, obj) {
      console.log('取消订阅事件' + (!error?'成功':'失败'), error, obj);
  }

参数解释

type, 事件类型，传1即可。
accounts, 取消订阅的账号列表。当accounts元素数量大于100时，SDK会以每100个帐号做为一组事务进行处理，按组并行执行操作(每组操作为一个事务)，任意一组失败都会抛出异常，但之前成功的组不会因后续失败的组而异常回滚；若用户有较强烈的事务处理要求，可多次调用此接口，且每次accounts元素数量小于100，进行上层实现
done, 用户自定义的结果回调函数
- 此回调包含两个参数，第一个参数为error，如果成功则error为null；第二个参数为obj, 它有一个字段failedAccounts的值为操作的类型, 具体类型如下：
  - failedAccounts, 失败的账号数组，如果为空数组则表示操作全部成功

按事件取消订阅

取消自己针对指定事件类型的订阅事件。

示例代码

javascript  nim.unSubscribeEventsByType({
      type: 1,
      done: unSubscribeEventDone
  });
  function unSubscribeEventDone(error, obj) {
      console.log('取消订阅事件' + (!error?'成功':'失败'), error, obj);
  }

参数解释

type, 事件类型，传1即可。
done, 用户自定义的结果回调函数
- 此回调包含两个参数，第一个参数为error，如果成功则error为null；第二个参数为obj, 它有一个字段failedAccounts的值为操作的类型, 具体类型如下：
  - failedAccounts, 失败的账号数组，如果为空数组则表示操作全部成功。

发布事件

向订阅者发布事件。若云信系统内置的在线状态无法满足应用需求或者开发者需要一些单独的自定义事件时，可以使用该接口来发布。

示例代码

javascript  nim.publishEvent({
    type: 1,   //传入1即可。
    value: 10001, //value为10000以上(1-9999为云信预定义值，开发者不可使用)
    custom: 'hello world',
    vaildTime: 60,
    sync: false,
    done: publishEventDone
  });
  function publishEventDone(error, obj) {
    console.log('发布事件' + (!error?'成功':'失败'), error, obj);
  }

参数解释

type, 事件类型，传入1即可。
value, value为10000及以上(1-9999为云信预定义值，开发者不可使用)。
custom, 用户自定义事件的扩展属性，可选参数，最大256字节
vaildTime, 用户发布事件的有效时间，可选参数(4.2.0+版本可选，老版本必填)，以秒为单位，范围在60s~7天(604800s)，默认7天。
broadcastType, 事件广播类型，可选参数，1:仅在线 2:在线和离线，默认2(在线和离线)。
sync, 是否同步给自己，可选参数，true/false，默认false
done, 用户自定义的结果回调函数，第一个参数为error，如果成功则error为null。

监听所订阅的事件

当订阅的事件从云信服务器下推时，可从onPushEvents回调监听。

示例代码

javascript  var nim = NIM.getInstance({
    onpushevents: onPushEvents
  });
  function onPushEvents(param) {
    console.log('订阅事件', param.msgEvents);
  }

参数解释

onpushevents, 服务器推送事件的回调函数，以下情况会收到此回调：
- 订阅了对应账号对应类型的事件，且订阅关系在有效期内，对方发布了相应事件
- 此回调会收到一个参数param, 它有一个字段msgEvents的值为操作的类型, 具体类型如下：
- msgEvents, 推送事件对象数组，数组对象中包含以下一些字段
  - msgEvents[i].account，发布对应事件的账号
  - msgEvents[i].type，事件类型
  - msgEvents[i].value，事件值
  - msgEvents[i].clientType，客户端类型，即该事件对应的账号所在的客户端类型。
  - msgEvents[i].custom，用户发布事件的自定义消息。对于内置的在线状态事件，此字段为空。
  - msgEvents[i].idClient，消息本地客户端id
  - msgEvents[i].idServer，消息服务器id
  - msgEvents[i].serverConfig，服务器下推的配置消息（客户端不可发布）。
  - msgEvents[i].time，事件发布的时间

按账号获取订阅关系

获取自己针对指定账号的事件订阅关系

示例代码

javascript  nim.querySubscribeEventsByAccounts({
      type: 1,
      accounts: ['cs3'],
      done: querySubscribeEventDone
  });
  function querySubscribeEventDone(error, obj) {
      console.log('获取订阅列表' + (!error?'成功':'失败'), error, obj);
  }

参数解释

type, 事件类型，传1即可。
accounts, 查询订阅的账号列表。当accounts元素数量大于100时，SDK会以每100个帐号做为一组事务进行处理，按组并行执行操作(每组操作为一个事务)，任意一组失败都会抛出异常，但之前成功的组不会因后续失败的组而异常回滚；若用户有较强烈的事务处理要求，可多次调用此接口，且每次accounts元素数量小于100，进行上层实现
done, 用户自定义的结果回调函数
- 此回调会收到两个参数，第一个参数为error，如果成功则error为null；第二个参数为obj, 它有一个字段msgEventSubscribes的值为操作的类型, 具体类型如下：
- msgEventSubscribes, 事件订阅对象数组，数组对象中包含以下一些字段
  - msgEventSubscribes[i].time 订阅时间
  - msgEventSubscribes[i].to 订阅者
  - msgEventSubscribes[i].type 订阅事件类型

在线状态事件

在线状态（在线、异常断开、登出）为云信系统内置事件，支持用户订阅其他用户的在线状态事件，当登录成功后，可以即时获取订阅用户此时的在线状态，包括在线、异常断开或是登出状态。

使用在线状态订阅功能前，您需要在云信控制台开启该功能：

在控制台首页应用管理选择应用进入应用配置页面，然后单击 IM即时通讯专业版下的功能配置按钮进入 IM 即时通讯配置页。
在顶部选择基础功能页签，开启在线状态订阅。

注意事项：

每次调用接口最多只能订阅100个账号，数量较多需多次调用。在线状态事件订阅，每个account id最大有效订阅账号不超过3000个。
订阅有效期为60 - 2592000秒（即60秒到30天），过期后需要重新订阅。如果未过期的情况下重复订阅，新设置的有效期会覆盖之前的有效期。
在线状态事件会受推送的影响：如果应用被清理，但厂商推送（APNS、小米、华为、OPPO、VIVO、魅族、FCM）可达，则默认不会触发该用户断开连接的事件,若开发者需要该种情况下视为离线，请前往网易云信控制台>选择应用>IM专业版>功能配置>在线状态配置自行修改；如果没有集成推送，或者推送不可达，则当用户断开连接时，会触发断开连接事件。
系统默认的在线状态事件值(value)为：1 - 登录，2 - 登出，3 - 断开连接。若需要设置自定义状态，如忙碌等，请自行发布事件。
订阅者登录的时候，如果被订阅者是在线的，那么会收到其在线的事件回调；但是如果对方是离线的，那么订阅者无法收到其离线的事件回调(如果后续对方重新登录，才能触发在线状态事件)。建议登录时将所有账号的在线状态设置为离线，这样设置，登录时无论对方是在线，还是从离线变更为在线，都能正常触发回调。
IM的好友关系和在线状态是两个不同的功能，只添加好友是不会显示对方的在线状态的。
在线状态事件订阅是单向的，双方需要各自订阅。

如前所述，在线状态事件为云信系统内置事件，无需开发者主动发布。在A订阅了B的type=1事件后，当A登录时，若B此时在线，则会收到对应的事件；若后续B再登录上线时，且A也在线，则依旧可以监听到。

在线咨询

微信咨询

电话咨询

此文档是否对你有帮助？

有帮助

去反馈

前提条件
订阅事件
取消订阅
按账号取消订阅
按事件取消订阅
发布事件
监听所订阅的事件
按账号获取订阅关系
在线状态事件