Users may implement the design mode programming method of "Publish-Subscribe" by publishing and subscribing to events. It can be used to subscribe many scenes such as online state of designated user, individual user profile, and logical asynchronous stream processing.
At present, only the "type = 1" event subscription is available. Users may define the value (a value corresponds to the status of an event; 1-9999 is the value pre-defined by CommsEase, which the developer cannot use) as required for their business.
Rough process: A subscribes B ——> B publishes a specific event ——> A monitors any change in the event status from B ——> handles it based on the business logic analysis.
Note: it is not required to actively publish the online status event (type=1, value=1/2/3) in CommsEase system. The work will be hosted to CommsEase server.

Subscribe to events

Subscribe an event to special users. It is required to subscribe built-in online status event or custom event with The API. The maximum number of effective subscription accounts cannot exceed 3000.

The developer is recommended to keep consistent subscription duration at each client, because multi-client subscription (subscription of the same account at other types of client) will occur during the validity period of subscription. Target event is not published for the same event subscription in the same account within 30 seconds, even the service is set to be "immediate synchronization".

Sample codes

javascript  nim.subscribeEvent({
      type: 1,
      accounts: ['cs3', 'cs4'],
      subscribeTime: 70,
      sync: true,
      done: subscribeEventDone
  });
  function subscribeEventDone(error, obj) {
      console.log('subscribe event' + (!error?’succeeded'':'failed'), error, obj);
  }

Parameter description

• type: It means event type and is typed with 1.
• subscribeTime: It means valid time of subscription, in 60s~30d (2592000), 30d by default.
• sync: it is used to synchronize the latest event immediately after subscription. "True" means synchronization; "false" means non-synchronization, "true" by fault.
• vaildTime: It means valid time of publishing events by the user, and is optional, in second, in the range of 60s~7d (604,800s), 7d by default.
• broadcastType: It means event broadcast type, and is optional."1" means online only; "2" means online and offline, 2 by default (online and offline)
• done: It is an user-defined results callback function.
  • The callback contains two parameters. The first one is "error". If successful, "error" will be null. The second one is "obj", of which the field "failedAccounts" is operation type, specifically as follows:
    • failedAccounts: It means array of failed accounts. If empty, then all operations are successful.

Unsubscribe from events

Unsubscribe by account

It means to unsubscribe event under designated account.

Sample codes

javascript  nim.unSubscribeEventsByAccounts({
      type: 1,
      accounts: ['cs3'],
      done: unSubscribeEventDone
  });
  function unSubscribeEventDone(error, obj) {
      console.log('unsubscribe event' + (!error?'succeeded'':'failed'), error, obj);
  }

Parameter description

• type: It means event type and is typed with 1.
• accounts: It is the list of unsubscribed accounts. If the number of accounts is larger than 100, SDK will set every 100 accounts as a group of transactions for processing and execute operation in parallel by group (with every group of operations as a transaction). It will throw exception if any group is failed, but previously successful groups will not abroll back due to subsequent failed groups. If an user has a strong demand for transaction processing, this API can be called repeatedly and the number of accounts every time is smaller than 100 for upper implementation.
• done: It is an user-defined results callback function.
  • The callback contains two parameters. The first one is "error". If successful, "error" will be null. The second one is "obj", of which the field "failedAccounts" is operation type, specifically as follows:
    • failedAccounts: It means array of failed accounts. If empty, then all operations are successful.

Unsubscribe by event

• It is used to unsubscribe event of designated type

Sample codes

javascript  nim.unSubscribeEventsByType({
      type: 1,
      done: unSubscribeEventDone
  });
  function unSubscribeEventDone(error, obj) {
      console.log('unsubscribe event' + (!error?'succeeded'':'failed'), error, obj);
  }

Parameter description

• type: It means event type and is typed with 1.
• done: It is an user-defined results callback function.
  • The callback contains two parameters. The first one is "error". If successful, "error" will be null. The second one is "obj", of which the field "failedAccounts" is operation type, specifically as follows:
    • failedAccounts: It means array of failed accounts. If empty, then all operations are successful..

Publish events

Publish an event to subscribers. If built-in online status of CommsEase system cannot accommodate application demands or the developer requires some independent custom events, event can be published with The API.

Sample codes

javascript  nim.publishEvent({
    type: 1,   //input 1.
    value: 10001, //value is greater than 10000(1-9999 are pre-defined by CommsEase, unavailable for the developer)
    custom: 'hello world',
    vaildTime: 60,
    sync: false,
    done: publishEventDone
  });
  function publishEventDone(error, obj) {
    console.log('publish event' + (!error?'succeeded'':'failed'), error, obj);
  }

Parameter description

• type: It means event type and is typed with 1.
• value: The value is 10,000 and later (1-9,999 pre-defined by CommsEase., unavailable for the developers).
• custom: It is the extended attribute of user-defined event, and is optional, with maximum size of 256 bytes.
• vaildTime: It means valid time for the user to publish events, and is optional (optional for v4.2.0+, required for old version), in second, in the range of 60s~7d(604800s), 7d by default.
• broadcastType: It means event broadcast type, and is optional."1" means online only; "2" means online and offline, 2 by default (online and offline).
• sync: It means the status of synchronization to the user, and is optional "true/false", "false" by default.
• done: It is an user-defined results callback function. The first parameter is "error". If successful, "error" will be null.

Monitor subscribed event

Monitor the subscribed event which is pushed down from CommsEase server by callback from onPushEvents.

Sample codes

javascript  var nim = NIM.getInstance({
    onpushevents: onPushEvents
  });
  function onPushEvents(param) {
    console.log('subscribe event', param.msgEvents);
  }

Parameter description

• onpushevents: It is a callback function for server pushed event. The callback will be returned if:
  • You have subscribed related type of events from related account; the subscription is valid, and related time is published.
  • The callback will receive a "param" of which the field "msgEvents" is operation type, specifically as follows:
  • msgEvents: It means the object array of pushed events. The array object contains some fields as below:
    • msgEvents[i].account: It is the account for publishing corresponding event.
    • msgEvents[i].type: It means event type.
    • msgEvents[i].value: It means event value.
    • msgEvents[i].clientType: It means client type, i.e. client type of corresponding event account.
    • msgEvents[i].custom: It means user-defined message for an user to publish event. For built-in online state event, the field is null.
    • msgEvents[i].idClient: It means local client ID of message.
    • msgEvents[i].idServer: It means message server ID.
    • msgEvents[i].serverConfig: It means configuration message pushed under the server, not published by client.
    • msgEvents[i].time: It means the time of publishing event.

Get subscription relationship by account

It is used to get event subscription relationship for designated account.

Sample codes

javascript  nim.querySubscribeEventsByAccounts({
      type: 1,
      accounts: ['cs3'],
      done: querySubscribeEventDone
  });
  function querySubscribeEventDone(error, obj) {
      console.log('get subscription list' + (!error?'succeeded'':'failed'), error, obj);
  }

Parameter description

• type: It means event type and is typed with 1.
• accounts: It is the list of accounts for querying subscription. If the number of accounts is larger than 100, SDK will set every 100 accounts as a group of transactions for processing and execute operation in parallel by group (with every group of operations as a transaction). It will throw exception if any group is failed, but previously successful groups will not abroll back due to subsequent failed groups. If an user has a strong demand for transaction processing, this API can be called repeatedly and the number of accounts every time is smaller than 100 for upper implementation.
• done: It is an user-defined results callback function.
  • The callback will receive two parameters. The first one is "error". If successful, "error" will be null. The second one is "obj", of which field "msgEventSubscribes" is operation type, specifically as follows:
  • msgEventSubscribes: It means the object array of subscribed events. The array object contains some fields as below:
    • msgEventSubscribes[i].time: It means subscription time.
    • msgEventSubscribes[i].to: It means the subscriber.
    • msgEventSubscribes[i].type: It means type of subscribed event.

Online status event

Online status (online, abordinary disconnection, logout) is a built-in event of CommsEase system. Before the use, it is only required to make an application to the sales department and obtain the approval for the application. It is not required to actively publish event status. if A has subscribed an online status event from B, A may obtain B's online status after login: online, abordinary disconnection or logout.

Note:

• By calling The API each time, up to 100 accounts can be subscribed. The API should be called frequently for a larger number of accounts. In relation to online status event subscription, the maximum number of valid subscription accounts is not more than 3,000 for each accid.
• The subscription remains valid in 60 - 2,592,000 s (i.e. 60 s-30 days), and another subscription is required after expiry. In the event of repeated subscription within the validity term, the new validity term will replace the previous one.
• Online status events will be affected by push: if the application is cleared, but the vendor pushes (APNS, Xiaomi, Huawei, OPPO, VIVO, Meizu, FCM) are reachable, the disconnection event will not be triggered in default. If the offline status is required in such an event, the developer should make modifications with CommsEase Console>Select Application>IM Professional>Feature Configuration>Online Status Configuration; if no integrated push is available or the push is unreachable, user disconnection will trigger the disconnection event.
• Default value of online state event in system: 1 - login; 2 - logout; 3 - offline. If it is required to set the custom status, such as busy, please publish event.
• At login, the subscriber will receive the callback of the online event if the subscribed is online; but if the subscribed is offline, the subscriber will be unable to receive the callback of the offline event (subsequent login of the subscribed will trigger the online status event). We recommend setting the status of all accounts from online to offline at login, so that callback will be triggered no matter whether the other is online or the status is changed from offline to online.
• Friendship and online status are two different features of IM. When a friend is added, his/her online status will not be displayed.
• One-way subscription applies to an online status event, to which both parties should subscribe respectively.

As mentioned above, an online status event is a built-in event of CommsEase system, which the developer is not required to actively publish. After subscribing the "type -1" event from B, A will receive the corresponding event at login if B is online; if B logs in to the account again and both B and A are online, A still can monitor the event.