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.
- 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.
- 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
timeoutevents and add transaction costs. - Set
presenceTimeoutandheartbeatIntervalon every viewer, to matching values. Explicit presence heartbeats are off by default in PubNub SDKs, becauseheartbeatIntervaldefaults to0. PubNub SDKs setpresenceTimeoutto 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. - Keep
heartbeatIntervala little under half ofpresenceTimeout, 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 linesSeed 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
- Compare the badge with the
occupancyin the nextintervalevent. The two should match within one interval. - 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 Nowcall per viewer per minute whileintervalevents are missing. At 40,000 viewers, that's about 670 calls a second. Don't check more often than once a minute.
Related tasks
- Build a roster for a large live event. Server-side User ID list when the product needs names.
- Load test a large live event channel. Simulated viewers that check the count and badge.
- Presence events. Announce and interval modes, deltas, and heartbeat timing.
- Large-room presence for live events. What the count can and can't tell you at this size.