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, and timeout arrays.
  • Run one roster service per event channel, not one per viewer.

The roster service works like this:


Build the roster​

  1. Subscribe the service to the channel's -pnpres companion channel before you read the room. Buffer the events that arrive. Subscribing to -pnpres doesn't make the service an occupant, so the count isn't inflated.
  2. Read the room with Here Now. Set limit to the largest value PubNub accepts, and never ask for a large room in one unpaged call. Here Now accepts a limit of up to 1,000 occupants per channel, and you paginate past that with offset. Send limit on every call. Increase offset by limit after each page. Stop when a page returns fewer User IDs than limit. Store the User IDs in a set.
  3. Replay the buffered events. For each interval event, remove the User IDs in leave and timeout, and add the User IDs in join. Below Announce Max, apply individual join, leave, and timeout events the same way.
  4. If an interval event has hereNowRefresh: 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.
  5. 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.

  1. On each interval event, publish the occupancy as a signal to a count channel, such as count.keynote-2026. Signal payloads are limited to 64 bytes.
  2. If the room is at or below Announce Max, also publish the count after each individual join, leave, and timeout event. Use the same rule as the viewer code to skip stray events from a busy room.
  3. 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 Now call. 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 Now requires read permission on the queried channel.
  • When Access Manager is enabled, receiving presence events requires read permission on the channel, which also grants access to its -pnpres companion channel.
  • Viewers on the relayed count need read on the count channel.
  • The roster service needs read on the event channel and write on the count channel.

Was this page useful?

Last updated on