Realtime Events

Realtime events in web is a way to get realtime updates on different entities of the social SDK. This means that whenever a user updates a community, adds/edits a new post within that community feed or adds/edits a comment within that post, the changes will be reflected immediately to all the users that choose to subscribe to the said community, post or comment.

The changes will be reflected through the same liveObject/liveCollection and its dataUpdated event. The SDK currently supports realtime events subscription to the following models:

• Community

• Post

• Comment

• User

• Follow/Unfollow

Topics

A topic is just a unique path<string> which has to be constructed for each model that we want to subscribe to in realtime. For each model type, SDK has helper methods to create these topics.

The five helper methods we have right now for the five different model types that support realtime events are:

• getCommunityTopic

• getPostTopic

• getCommentTopic

• getUserTopic

• getUserFollowTopic

These methods, except for getUserFollowTopic, have two parameters :

1. Data model (required) This is the model that we want to subscribe to and it can be the model of any liveObject that we want to subscribe to.

2. Subscription level (optional) This is a way to determine the level of events within that model that we want to get realtime updates. The SDK has a SubscriptionLevels enum which can be used. If not provided, the default subscription level will be the model type that is passed.

SubscriptionLevels = { 
  COMMUNTIY: 'community',
  POST: 'post',
  COMMENT: 'comment',
  POST_AND_COMMENT: 'post_and_comment',
  USER: 'user',
};

Community Topic

Community model supports the following subscription levels:

• COMMUNITY

• POST

• COMMENT

• POST_AND_COMMENT

The default value is COMMUNITY.

import { getCommunityTopic, SubscriptionLevels } from '@amityco/js-sdk';

// Community topic to subscribe to all events of that community model only
// Example events: community joined, community left, community updated 
const topic = getCommunityTopic(communityModel, SubscriptionLevels.COMMUNTIY);

// Community topic to subscribe to all post events of that community model
// Example events: post created, post deleted, post updated
const topic = getCommunityTopic(communityModel, SubscriptionLevels.POST);

// Community topic to subscribe to all comment events of that community model
// Example events: comment created, comment deleted, comment updated
const topic = getCommunityTopic(communityModel, SubscriptionLevels.COMMENT);

// Community topic to subscribe to all posts and comment events of that community model
// Example events: comment created, comment deleted, comment updated
const topic = getCommunityTopic(communityModel, SubscriptionLevels.POST_AND_COMMENT);

Post Topic

Post model supports the following subscription levels:

• POST

• COMMENT

The default is POST.

import { getPostTopic, SubscriptionLevels } from '@amityco/js-sdk';

// Post topic to subscribe to all events of that post model only
// Example events: post edited, reactions added 
const topic = getPostTopic(postModel, SubscriptionLevels.POST);

// Post topic to subscribe to all comment events of that post model
// Example events: comment created, comment deleted, comment updated
const topic = getPostTopic(postModel, SubscriptionLevels.COMMENT);

Comment Topic

Comment model supports only COMMENT subscription level as there are no lower level models.

import { getCommentTopic, SubscriptionLevels } from '@amityco/js-sdk';

// Comment topic to subscribe to all comment events of that post model
// Example events: comment created, comment deleted, comment updated
const topic = getCommentTopic(commentModel, SubscriptionLevels.COMMENT);

User Topic

User model is similar to the community model in terms of topic creation. User model supports the following subscription levels

• USER

• POST

• COMMENT

• POST_AND_COMMENT

The default value is USER.

import { getUserTopic, SubscriptionLevels } from '@amityco/js-sdk';

// User topic to subscribe to all events of that user model only
const topic = getUserTopic(userModel, SubscriptionLevels.USER);

// User topic to subscribe to all post events of that user model
// Example events: post created, post deleted, post updated
const topic = getUserTopic(userModel, SubscriptionLevels.POST);

// User topic to subscribe to all comment events of that user model
// Example events: comment created, comment deleted, comment updated
const topic = getUserTopic(userModel, SubscriptionLevels.COMMENT);

// User topic to subscribe to all posts and comment events of that user model
// Example events: comment created, comment deleted, comment updated
const topic = getUserTopic(userModel, SubscriptionLevels.POST_AND_COMMENT);

Follow Topic

Refer to Getting Realtime Updates to implement realtime events for follow and unfollow.

Subscribe and Unsubscribe

After creating a topic, you can subscribe and unsubscribe to the topic using EventSubscriberRepository class.

import { 
	getCommunityTopic,
	EventSubscriberRepository,
	SubscriptionLevels } from '@amityco/js-sdk';

let topic = getCommunityTopic(communityModel, SubscriptionLevels.POST);

// Subscription has an optional error callback parameter that can be used.
EventSubscriberRepository.subscribe(topic, (err) => {
	if (err) { // handle subscription error here}
	// handle subscription success here.
});

// Unsubscribe
EventSubscriberRepository.unsubscribe(topic);

Subscription Topics limit

The maximum limit for the number of topics that can be subscribed to is 20. Developers should maintain the list of subscriptions themselves and unsubscribe when it's not needed.

There are a few ways we can manage the subscription limit:

• We advise the developers to use higher level of topics. For example, instead of creating a topic for each post within a community and for each comment within the posts, it's better to create a single community topic for all the posts and comments within that community by using the getCommunity topic method with SubscriptionLevel of POST_AND_COMMENT.

  getCommunityTopic(communityModel, SubscriptionLevel.POST_AND_COMMENT)

• We advise the developers to subscribe to a topic when a liveObject is rendered and unsubscribe when not. For example, if you have a list of communities rendered on a page, and you click on one and move to a page that shows the details of that community, you might want to subscribe when user is only viewing community details in details page and unsubscribe when user moves back to community list page.

Observing Realtime events

After subscribing to data models from liveObjects, the changes from the realtime event will also be reflected on the dataUpdated event of the same liveObject.

Example usage for subscribing and observing realtime events for a community:

const [community, setCommunity] = React.useState();

React.useEffect(() => {
  const liveObject = CommunityRepository.communityForId('communityId');

	// The realtime event for any changes to the community will also reflect here. 
  liveObject.on('dataUpdated', setCommunity);

  return () => liveObject.dispose();
}, []);

React.useEffect(() => {
  if (community.communityId) {
		let topic = getCommunityTopic(community, SubscriptionLevels.COMMUNITY);
    EventSubscriberRepository.subscribe(topic);
   
    return EventSubscriberRepository.unsubscribe(topic);
  }
}, [community.communityId]);

If the session is logged out, all the existing subscriptions will be removed.