Show a viewer count for a large live event

This guide shows you how to show the viewer count of one live event channel to every viewer. The count comes from Presence, so you don't need a server-side roster. Read Large-room presence for live events first to see what the count can and can't tell you at this size.

Before you start:

  • Turn on Presence for the event channel in Presence Management.
  • Keep Presence Deltas off for the keyset. A count-only design doesn't use them.
  • Note your keyset's Announce Max and Interval values. The code needs them.

Set the heartbeat settings​

Each viewer must keep sending heartbeats, or PubNub drops it from the count.

  1. Check the Subscribe heartbeats (implicit) switch. By default, only explicit heartbeats keep a client present. Subscribe requests count as heartbeats only when the keyset's Subscribe heartbeats (implicit) setting is on. The Subscribe heartbeats (implicit) setting is under Channel rules → ⋯ → Legacy tracking settings in the keyset's Presence settings, and it's off on new keysets.
  2. Keep the switch off unless some viewers can't send explicit heartbeats. Older software development kit (SDK) versions are the usual case. Turning it on without a reason can delay timeout events and add transaction costs.
  3. Set presenceTimeout and heartbeatInterval on every viewer, to matching values. Explicit presence heartbeats are off by default in PubNub SDKs, because heartbeatInterval defaults to 0. PubNub SDKs set presenceTimeout to 300 seconds by default, which is how long PubNub waits without a heartbeat before marking a client offline. The code below uses 120 and 59 seconds.
  4. Keep heartbeatInterval a little under half of presenceTimeout, so one lost heartbeat doesn't drop the viewer. Each heartbeat is a billable call to the application programming interface (API). For the recommended values, see API limits.

Write the viewer code​

Store the User ID with the viewer's account or in local storage, and reuse it on every reload. A new User ID on each reload counts the viewer twice until the old ID times out.

Use this code for each viewer. Replace the keyset values in the first two lines, and implement renderWatching in your user interface (UI).

1const ANNOUNCE_MAX = 20;     // match your keyset's Announce Max
2const INTERVAL_MS = 10_000; // match your keyset's interval
3
4const pubnub = new PubNub({
5 subscribeKey: 'mySubscribeKey',
6 userId: storedUserId, // the same ID on every reconnect and page reload
7 presenceTimeout: 120,
8 heartbeatInterval: 59, // explicit heartbeats keep a subscribed viewer counted
9});
10
11const eventChannel = 'live.keynote-2026';
12const subscription = pubnub.channel(eventChannel).subscription({ receivePresenceEvents: true });
13
14let watching = null; // the count on screen
15let lastTimetoken = 0n; // newest event rendered
show all 71 lines

Seed the badge​

The code makes one count-only Here Now call at startup, so a late joiner doesn't wait for the next interval. Every viewer makes this call. At 40,000 viewers, that's up to 40,000 calls in the first minute. To skip that call, delete the await recount() line. The badge then fills at the next interval event.

Check the count​

  1. Compare the badge with the occupancy in the next interval event. The two should match within one interval.
  2. If the badge stays busy after the room drains, wait one minute. The code's once-a-minute check fetches a fresh count. That check costs one Here Now call per viewer per minute while interval events are missing. At 40,000 viewers, that's about 670 calls a second. Don't check more often than once a minute.

Was this page useful?

Last updated on