In the context of channels, subchannels, and message collections, receiving real-time events is an automatic process for conversation and community channels; you do not need to perform any additional actions. However, for a live channel still needs to be established.

Similar to the process for social real-time events, a topic is a unique path that must be constructed for each model you wish to receive updates about in real-time. The SDK offers helper methods for creating these topics for each model type. Each topic includes an events enum that developers can select to subscribe to, based on their business context and preferences.

To receive updates from a channel or any content created within that channel, the user must hold 'Member' status within that channel. Once the user leaves the channel, they will no longer receive real-time events.

Subchannel Topic

d

A topic is a distinct path that must be constructed for each model to which you wish to subscribe in real-time. The SDK provides helper methods to create these topics for each model type. Each topic encompasses an events enum, which developers can select to subscribe to based on their business context and interests.

To subscribe to updates from a community or any content created within that community, the user must have the 'Member' status in that community. Once the user leaves the community, they will no longer receive real-time events.

Community Topic

• COMMUNITY - subscription to changes of the community object

• POSTS - subscription to changes of post objects in the community

• COMMENTS - subscription to changes of comment objects in the community

• POST and COMMENTS - subscription to changes of post and comment objects in the community

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 - subscription to changes of the post object

• COMMENTS - subscription to changes of comment objects on the post

The default value 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 - subscription to changes of the comment object

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 - subscription to changes of the user object

• POSTS - subscription to changes of post objects in the user feed

• COMMENTS - subscription to changes of comment objects in the user feed

• POST and COMMENTS - subscription to changes of post and comment objects in the user feed

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

• MY_FOLLOWERS - subscription to changes related users that current user follows

• MY_FOLLOWING - subscription to changes related users that follows current user

The SDK supports real-time events of various data models through a robust event-driven mechanism. For instance, when a user modifies their profile, these changes can seamlessly be reflected in another user's device. This reflection is achieved via the same that the user is observing in real-time.

Currently, the SDK supports real-time event subscriptions for the following models:

• Community

• Post

• Comment

• User

• Follow/Unfollow

• Subchannel

Usage

To subscribe or unsubscribe from the relevant real-time events, you need to create a Subscription Topic. Upon constructing the subscription topic, the SDK exposes methods for subscribing and unsubscribing, allowing you to listen to specific events without needing to create a new topic.

Construct Subscription Topic

The subscription topic construction, excluding Follow/Unfollow topics, requires two parameters:

1. Data Model (required): This represents the model to which we wish to subscribe, which can be any model.

2. Subscription Level (optional): This allows specifying the event level within that model for real-time updates. The SDK includes an enum for this purpose. If not provided, the default subscription level corresponds to the passed model type.

Observe updates

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]);

Unsubscribe Events

To ensure the number of active subscriptions stays within the limit, it is recommended to unsubscribe from topics when they are no longer needed. This could mean unsubscribing when leaving a particular screen or during periods of inactivity.

Each topic subscription in the SDK provides an unsubscribe method. For unsubscribing, use the Unsubscribe topic method.

If the logout() method is invoked at any point, the current session will be terminated and all existing subscriptions will be automatically removed. This functionality assists in efficiently managing active subscriptions and preventing unwanted data consumption.

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);

By adopting these practices, you can efficiently manage the subscription limit and maintain a responsive and performant application.

Subscription Topics limit

The SDK imposes a maximum limit of 20 for the number of topics that can be subscribed to simultaneously. Developers are advised to manage their list of subscriptions and unsubscribe as necessary.

For instance, suppose you have two screens: one displays a list of communities, and the other displays community details. You may want to subscribe when a user is viewing community details and unsubscribe when the user returns to the community list screen.

Even if you subscribe to the same topic and event multiple times, the SDK maintains only one subscription.

Strategies for Managing Subscription Limit

1. Use higher-level topics: Instead of creating a topic for each post within a community or each comment within a post, it's recommended to create a single community topic for all posts and comments within that community. This can be achieved by using the getCommunityTopic method with a SubscriptionLevel of POST_AND_COMMENT.

2. Subscribe when rendered, unsubscribe when not: Developers should consider subscribing to a topic when a liveObject is rendered and unsubscribing when it's no longer needed. For instance, if you have a list of communities on a page and you navigate to a page showing a community's details, you may want to subscribe when the user is viewing community details and unsubscribe when the user returns to the community list page.