> ## Documentation Index
> Fetch the complete documentation index at: https://learn.social.plus/llms.txt
> Use this file to discover all available pages before exploring further.

# Live Viewer Count Config

> Read the network-level configuration that governs whether viewers see the live viewer count on a livestream.

`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.

<Note>
  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](/analytics-and-moderation/social+-apis-and-services/network-settings).
</Note>

## Platform Surface

| Platform   | Entry point                                  | Return type                           | Signature                       |
| ---------- | -------------------------------------------- | ------------------------------------- | ------------------------------- |
| TypeScript | `client.getLiveViewerCountConfig()`          | `Promise<AmityLiveViewerCountConfig>` | Zero-argument, async            |
| iOS        | `client.getLiveViewerCountConfig()`          | `AmityLiveViewerCountConfig`          | `async throws` on `AmityClient` |
| Android    | `AmityCoreClient.getLiveViewerCountConfig()` | `Single<AmityLiveViewerCountConfig>`  | Zero-argument, RxJava           |

## Modes

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

| Mode               | Threshold applied | Viewer behavior                                                 |
| ------------------ | ----------------- | --------------------------------------------------------------- |
| `alwaysShow`       | No                | Count is always visible. Default for never-configured networks. |
| `hideEntirely`     | No                | Viewers never see the count. Hosts and co-hosts still see it.   |
| `showAboveMinimum` | Yes (inclusive)   | Viewers see the count only when `count >= threshold`.           |

## Config Model

| Field       | Type                       | Description                                                                                               |
| ----------- | -------------------------- | --------------------------------------------------------------------------------------------------------- |
| `mode`      | `AmityLiveViewerCountMode` | Selected display mode.                                                                                    |
| `threshold` | `Int`                      | Positive integer in `[1, 1000]`. **Always present**, default `50`. Applied only under `showAboveMinimum`. |

## 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).

<CodeGroup>
  ```typescript TypeScript theme={null}
  import { Client, AmityLiveViewerCountMode } from "@amityco/ts-sdk";

  async function shouldShowViewerCount(
    client: Amity.Client,
    currentCount: number,
    isHostOrCoHost: boolean,
  ): Promise<boolean> {
    if (isHostOrCoHost) {
      return true;
    }

    const config = await client.getLiveViewerCountConfig();

    switch (config.mode) {
      case AmityLiveViewerCountMode.ALWAYS_SHOW:
        return true;
      case AmityLiveViewerCountMode.HIDE_ENTIRELY:
        return false;
      case AmityLiveViewerCountMode.SHOW_ABOVE_MINIMUM:
        return currentCount >= config.threshold;
    }
  }
  ```

  ```kotlin Android theme={null}
  import com.amity.socialcloud.sdk.api.core.AmityCoreClient
  import com.amity.socialcloud.sdk.model.core.settings.AmityLiveViewerCountMode

  fun observeShouldShowCount(
      currentCount: Int,
      isHostOrCoHost: Boolean,
  ) {
      if (isHostOrCoHost) {
          showSuccessMessage(true)
          return
      }

      AmityCoreClient.getLiveViewerCountConfig()
          .subscribe(
              { config ->
                  val visible = when (config.mode) {
                      AmityLiveViewerCountMode.ALWAYS_SHOW -> true
                      AmityLiveViewerCountMode.HIDE_ENTIRELY -> false
                      AmityLiveViewerCountMode.SHOW_ABOVE_MINIMUM ->
                          currentCount >= config.threshold
                  }
                  showSuccessMessage(visible)
              },
              { error -> handleGeneralError(error) }
          )
  }
  ```

  ```swift iOS theme={null}
  import AmitySDK

  func shouldShowViewerCount(
      client: AmityClient,
      currentCount: Int,
      isHostOrCoHost: Bool
  ) async throws -> Bool {
      if isHostOrCoHost {
          return true
      }

      let config = try await client.getLiveViewerCountConfig()

      switch config.mode {
      case .alwaysShow:
          return true
      case .hideEntirely:
          return false
      case .showAboveMinimum:
          return currentCount >= config.threshold
      }
  }
  ```
</CodeGroup>

## 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

| Constraint | Value                            |
| ---------- | -------------------------------- |
| Type       | Positive integer                 |
| Minimum    | `1`                              |
| Default    | `50`                             |
| Maximum    | `1000`                           |
| Comparison | Inclusive (`count >= threshold`) |

<Info>
  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.
</Info>

## 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.

<Warning>
  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.
</Warning>

## UIKit Integration

If you use UIKit, no wiring is needed — the [Livestream Player Page](/uikit/components/social/livestream) 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.

## Related Topics

<CardGroup cols={3}>
  <Card title="Live Room Viewing" icon="signal-stream" href="./live-viewing">
    Observe room playback state and hand playback URLs to your player.
  </Card>

  <Card title="Co-Host Management" icon="users" href="./co-host-management">
    Manage co-host participants — co-hosts are exempt from the visibility rule.
  </Card>

  <Card title="Livestream UIKit" icon="tv" href="/uikit/components/social/livestream">
    Ready-to-use livestream components that apply the visibility rule automatically.
  </Card>
</CardGroup>