Skip to main content
SDK v7.x · Last verified March 2026 · iOS · Android · Web · Flutter
// 1. Enable presence for the current user
await PresenceManager.enable();

// 2. Start heartbeat to stay online
PresenceManager.startHeartbeat({ intervalMs: 10000 });

// 3. Observe a channel's online members
ChannelRepository.Membership.getMembers(
  { channelId: 'ch-123', filter: 'online' },
  ({ data }) => { renderOnlineUsers(data); }
);

// 4. Subscribe to real-time topic events
Client.on('post.created', (event) => {
  showNewPostIndicator(event.data);
});
Full walkthrough below ↓
Platform note — code samples below use TypeScript. Every method has an equivalent in the iOS (Swift), Android (Kotlin), and Flutter (Dart) SDKs — see the linked SDK reference in each step.
Presence makes your app feel alive. When users can see who’s online, which communities are active, and get instant content updates, engagement increases. This guide covers enabling user presence, syncing channel activity, managing heartbeats, and subscribing to real-time social events.
Prerequisites: SDK installed and authenticated → SDK Setup. Presence features must be enabled for your network — check Admin Console → Settings.
After completing this guide you’ll have:
  • Online/offline presence indicators on user avatars throughout the app
  • Channel-level presence (who is currently viewing a community or room)
  • Real-time event subscriptions for platform-wide activity tracking

​
Quick Start: Enable User Presence

TypeScript
import { PresenceManager, UserPresenceRepository } from '@social-plus/sdk';

try {
  const presence = new PresenceManager();
  await presence.enable();
  presence.startHeartbeat();

  // Track another user's online status
  const userPresence = new UserPresenceRepository();
  await userPresence.syncUserPresence('user-123');
} catch (error) {
  console.error('Presence setup failed:', error);
}
Full reference → Presence Overview

​
Part 1: User Presence (Online/Offline)

1

Enable presence and start heartbeat

Enable presence tracking for the current user and start the automatic heartbeat. The SDK sends a heartbeat every 20-30 seconds to keep the user’s online status current.
TypeScript
import { PresenceManager } from '@social-plus/sdk';

const presence = new PresenceManager();

const isAvailable = await presence.isEnabled();
if (isAvailable) {
  await presence.enable();
  presence.startHeartbeat();
}
Full reference → Heartbeat Sync
2

Query user presence

Check whether specific users are online. Query up to 220 users at once for a member list or chat contact screen.
TypeScript
import { UserPresenceRepository } from '@social-plus/sdk';

const presenceRepo = new UserPresenceRepository();
const presences = await presenceRepo.getUserPresence(['user-1', 'user-2', 'user-3']);

presences.forEach(p => {
  console.log(`${p.userId}: ${p.isOnline ? 'Online' : 'Offline'}`);
});
Full reference → User Presence
3

Sync presence for real-time updates

For users visible on screen (profile page, chat list), sync their presence to get live updates when they come online or go offline. Max 20 synced users at a time.
TypeScript
const presenceRepo = new UserPresenceRepository();

// Start syncing (call for each visible user)
await presenceRepo.syncUserPresence('user-123');

// Observe changes
presenceRepo.getSyncingUserPresence().subscribe(presences => {
  presences.forEach(p => {
    updateStatusDot(p.userId, p.isOnline);
  });
});

// Stop when user scrolls off screen
await presenceRepo.unsyncUserPresence('user-123');
Full reference → User Presence
4

Get online users count

Display a global “X users online” counter for your platform.
TypeScript
const presenceRepo = new UserPresenceRepository();
const count = await presenceRepo.getOnlineUsersCount();
console.log(`${count} users online`);
Full reference → User Presence
5

Handle app lifecycle

Stop the heartbeat when the app goes to the background and restart it when the app returns to the foreground. This prevents false “online” status while the app is minimized.
TypeScript
// Web: use visibility change
document.addEventListener('visibilitychange', () => {
  if (document.hidden) {
    presence.stopHeartbeat();
  } else {
    presence.startHeartbeat();
  }
});
Full reference → Heartbeat Sync

​
Part 2: Channel Presence

1

Sync channel presence

Track which channels have active members. Useful for chat lists showing “2 members active” or highlighting active communities.
TypeScript
import { ChannelPresenceRepository } from '@social-plus/sdk';

const channelPresence = new ChannelPresenceRepository();
await channelPresence.syncChannelPresence('channel-123');

channelPresence.getSyncingChannelPresence().subscribe(updates => {
  updates.forEach(cp => {
    console.log(`Channel ${cp.channelId}: ${cp.activeUserCount} active`);
  });
});
Full reference → Channel Presence
2

Manage visible channels

Sync/unsync channels as the user scrolls through a chat list. Max 20 synced channels at a time.
TypeScript
// When a new channel becomes visible
await channelPresence.syncChannelPresence('channel-456');

// When a channel scrolls off screen
await channelPresence.unsyncChannelPresence('channel-123');

// Cleanup on unmount
await channelPresence.unsyncAllChannelPresence();
Full reference → Channel Presence

​
Part 3: Real-time Social Event Subscriptions

Beyond presence, you can subscribe to content events — new posts, comments, reactions — so your UI updates instantly without polling.
1

Subscribe to community events

Subscribe at different granularity levels: community-level, post-level, or comment-level.
TypeScript
import { getCommunityTopic, SubscriptionLevels } from '@amityco/ts-sdk';

// Subscribe to all post events in a community
const topic = getCommunityTopic(community, SubscriptionLevels.POST);

// Subscribe to posts AND comments
const fullTopic = getCommunityTopic(community, SubscriptionLevels.POST_AND_COMMENT);
Full reference → Social Real-time Events
2

Subscribe to post and comment events

For a post detail screen, subscribe to comment-level events on a specific post.
TypeScript
import { getPostTopic, getCommentTopic, SubscriptionLevels } from '@amityco/ts-sdk';

// Subscribe to comment events on a post
const postCommentTopic = getPostTopic(post, SubscriptionLevels.COMMENT);

// Subscribe to a specific comment's events
const commentTopic = getCommentTopic(comment);
Full reference → Social Real-time Events
3

Subscribe to follow events

Get real-time updates when someone follows or unfollows the current user.
TypeScript
import { getMyFollowersTopic, getMyFollowingsTopic } from '@amityco/ts-sdk';

const myFollowers = getMyFollowersTopic();
const myFollowings = getMyFollowingsTopic();
Full reference → Social Real-time Events

​
Connect to Moderation & Analytics

Track daily active concurrent users and peak online times in Admin Console → Analytics Dashboard. This helps with capacity planning and understanding peak engagement windows.
Enable or disable presence features for your network in Admin Console → Settings. Presence can be toggled per-network without code changes.
Combine SDK real-time events with webhook events for server-side workflows. For example, subscribe to post.created in the SDK for instant UI updates, and also handle it via webhook for server-side indexing.→ Webhook Events

​
Common Mistakes

Forgetting to stop the heartbeat on logout — If you start PresenceManager.startHeartbeat() but don’t stop it when the user logs out, the user appears “online” indefinitely.
// ❌ Bad — heartbeat leaks
async function logout() {
  await Client.logout(); // heartbeat still running
}

// ✅ Good — stop heartbeat first
async function logout() {
  PresenceManager.stopHeartbeat();
  await Client.logout();
}
Setting the heartbeat interval too low — Intervals under 5 seconds waste bandwidth and may trigger rate limits. The recommended minimum is 10 seconds.
Subscribing to too many topics at once — Each topic subscription maintains a WebSocket channel. Subscribe only to topics visible on screen and unsubscribe when the user navigates away.

​
Best Practices

  • Use a green dot for “online”, grey dot for “offline”, and show “Last seen X min ago” for recently active users
  • Don’t show exact “last seen” timestamps for privacy — round to “a few minutes ago”, “an hour ago”, etc.
  • Let users opt out of showing their online status in profile settings
  • Combine presence with typing indicators in chat for a “User is typing…” experience
  • Respect the 20-user sync limit — sync only users currently visible on screen
  • Unsync users/channels as they scroll off screen; re-sync when they scroll back
  • Use getUserPresence() for one-time queries (member lists); use syncUserPresence() only for screens that need live updates
  • Stop heartbeat in background to avoid battery drain on mobile
  • Use viewId when the same user is displayed in multiple UI components to avoid duplicate unsubscriptions
  • Subscribe at the highest useful level: one getCommunityTopic(community, POST_AND_COMMENT) subscription is better than separate post + comment subscriptions
  • Unsubscribe when the component/screen unmounts — don’t leak subscriptions
  • Use real-time events for UI updates; use webhooks for server-side workflows
  • Don’t subscribe to everything globally — only subscribe to topics the user is actively viewing
Dive deeper: Real-time Communication Reference has full parameter tables, method signatures, and platform-specific details for every API used in this guide.

​
Next Steps

Your next step → Notifications & Engagement

Presence is live — now pair it with push notifications to keep users informed across sessions.
Or explore related guides:

Build a Social Feed

Use Live Collections for real-time feed updates

Notifications & Engagement

Combine presence with notification delivery

User Profiles & Social Graph

Show online status on user profiles