Skip to main content
AmityClient.getLiveViewerCountConfig() returns the network-level configuration that governs whether the live viewer count is shown to viewers on a livestream. Admins pick one of three modes (always show, hide entirely, or show above a minimum) at the network level; the SDK reads it as a one-shot cold read and the UIKit’s viewer-count element applies the rule.
This page covers the SDK read API. The write path is admin-only and served by the Console — the SDK does not update this setting. Console UI and permissions are documented separately in Network Settings.

Platform Surface

Modes

Three modes are available. They apply to viewers only — hosts and co-hosts always see the actual count regardless of mode.

Config Model

Read the Config

Read the config at each livestream mount. The API is a cold read — there is no observable and no real-time channel. Admin changes made mid-stream do not propagate to already-connected viewers; they take effect only on a subsequent mount (leave and rejoin).

Visibility Rule

The rule is evaluated in a fixed order — the first match wins.
  1. Role check first. If the current user is a host or co-host, show the actual count. All mode-based hiding applies to viewers only.
  2. Mode branch (viewer role):
    • alwaysShow — show.
    • hideEntirely — hide.
    • showAboveMinimum — show iff count >= threshold (inclusive).
The comparison is inclusive: at exactly count == threshold, the count is shown.

Propagation Model

The SDK reads the config once when the viewer joins a stream. Changes made by an admin while the viewer is already watching do not update the visibility state — the viewer keeps the rule that applied at join. To pick up a new config, the viewer must leave and rejoin the stream. Within a single mount, the visibility state still reacts to two things:
  • Count ticks. Under showAboveMinimum, if the viewer count crosses the threshold naturally, the count appears or disappears without a rejoin.
  • Role changes. A viewer promoted to co-host mid-stream immediately sees the actual count — no rejoin needed.

Threshold Constraints

The Console clamps admin-entered values on save: values above 1000 are clamped to 1000; values below 1 (or empty) reset to 1. Zero is explicitly rejected — use alwaysShow for “always visible” instead.

Defaults

Never-configured networks read as { mode: alwaysShow, threshold: 50 } — the backend merges defaults at read time, so no client-side fallback is required for absent fields. Every read after an admin change returns the current value; no client-side cache is required.

Error Handling

On any read error or malformed config, fail open — behave as alwaysShow (the UIKit LiveViewerCountElement does this automatically), so today’s behavior is never silently regressed.
Never treat a config error as a reason to hide the count. If the admin never selected hideEntirely, viewers should still see it. Fail open, always.

UIKit Integration

If you use UIKit, no wiring is needed — the Livestream Player Page reads this config automatically through the built-in LiveViewerCountElement. Use this API only when you build a custom viewer surface and need to enforce the same visibility rule yourself.

Live Room Viewing

Observe room playback state and hand playback URLs to your player.

Co-Host Management

Manage co-host participants — co-hosts are exempt from the visibility rule.

Livestream UIKit

Ready-to-use livestream components that apply the visibility rule automatically.