Build a roster for a large live event
This guide shows you how to build a server-side roster of User IDs for one live event channel. Build a roster only when the product needs names. If a viewer count is enough, use Show a viewer count for a large live event instead. Read Large-room presence for live events first for what the roster can and can't guarantee.
Before you start:
- Turn on Presence Deltas in the keyset's Presence settings. The roster reads User IDs from
join,leave, andtimeoutarrays. - Run one roster service per event channel, not one per viewer.
The roster service works like this:
Build the roster
- Subscribe the service to the channel's
-pnprescompanion channel before you read the room. Buffer the events that arrive. Subscribing to-pnpresdoesn't make the service an occupant, so the count isn't inflated. - Read the room with
Here Now. Setlimitto the largest value PubNub accepts, and never ask for a large room in one unpaged call.Here Nowaccepts alimitof up to 1,000 occupants per channel, and you paginate past that withoffset. Sendlimiton every call. Increaseoffsetbylimitafter each page. Stop when a page returns fewer User IDs thanlimit. Store the User IDs in a set. - Replay the buffered events. For each
intervalevent, remove the User IDs inleaveandtimeout, and add the User IDs injoin. Below Announce Max, apply individualjoin,leave, andtimeoutevents the same way. - If an
intervalevent hashereNowRefresh: true, read the room again. Never run two reads at once. If the flag arrives during a read, queue one more read after it finishes. - After each interval, compare the roster's size with the event's
occupancy. If they differ for two intervals in a row, read the room again.
Don't calculate the number of pages from occupancy. A page can hold several times limit User IDs.
Look up names
Look up each User ID in your own user store, in DataSync user records, or in App Context user metadata. Cache the results. Presence carries User IDs, not profiles.
Relay the count to viewers
If you relay the count, viewers don't subscribe to presence events. They still subscribe to the event channel and send heartbeats. They seed the badge with one count-only Here Now call, as in the count-only design.
- On each
intervalevent, publish theoccupancyas a signal to a count channel, such ascount.keynote-2026. Signal payloads are limited to 64 bytes. - If the room is at or below Announce Max, also publish the count after each individual
join,leave, andtimeoutevent. Use the same rule as the viewer code to skip stray events from a busy room. - If the last relayed count was above Announce Max and no new count arrives for a few intervals, fall back to a count-only
Here Nowcall. At or below Announce Max, silence is normal.
Send signals and messages on separate channels. Mixing them on the same channel interferes with how the SDK recovers missed events after a disconnect.
Leave the count channel out of your Presence Management rules.Set Access Manager grants
If Access Manager is on, grant these permissions:
-
When Access Manager is enabled, calling
Here Nowrequiresreadpermission on the queried channel. -
When Access Manager is enabled, receiving presence events requires
readpermission on the channel, which also grants access to its-pnprescompanion channel. - Viewers on the relayed count need
readon the count channel. - The roster service needs
readon the event channel andwriteon the count channel.
Related tasks
- Show a viewer count for a large live event. Count-only badge with no roster.
- Load test a large live event channel. Simulated viewers that check the roster.
- Get online users in a channel. Count-only calls and paging through a large channel.