Viewer counter
streamvi-plugin-counter demonstrates a widget built with React, TypeScript and Vite. Its settings page changes appearance, while a separate /obs page displays viewers per channel and the total. Broadcast and template updates arrive through Centrifugo.
Preparation
You need Git, npm and a supported Node.js release matching engines in the example package.json. Create a Widget application, install it in a test project and create a template using the widget guide. That guide also illustrates the application URL and opening template settings.
The example reads project information (project:read), the broadcast (broadcast:read), the saved template (integration:read) and obtains WebSocket tokens (centrifuge:read). These permissions serve the example's specific operations; integration:read is not a general requirement for creating any plugin.
Local launch
git clone https://github.com/StreamVi/streamvi-plugin-counter.git
cd streamvi-plugin-counter
npm installCreate .env.local. To connect to production StreamVi, use:
PORT=5511
VITE_STREAMVI_API_HOST=https://api-v2.streamvi.io
VITE_CENTRIFUGO_HOST=wss://events.streamvi.io
The repository's .env.example points to local API and Centrifugo servers. Vite does not start them; replace the addresses if you do not have those servers. The example appends /connection/websocket to the WebSocket host itself.
npm run devSettings are available at http://localhost:5511/, and the OBS display at http://localhost:5511/obs. Both use template_id and token query parameters. These are the template ID and installation API token from the widget launch parameters, not the application secret or iframe messaging token. Do not publish the complete URL with its token.
To open it inside production Cabinet, host the page at an accessible HTTPS address. The local HTTP address is for local testing; embedding it in an HTTPS page may be blocked by the browser. Opening / directly with parameters does not create Cabinet messaging or save template settings by itself.
Example structure
| File or directory | Purpose |
|---|---|
| App.tsx | Selecting settings or /obs |
| settings/ | Preview, appearance and OBS URL |
| useCabinetBridge.ts | Template init, ready, sync and update messages |
| client.ts | HTTP requests with the API token in the widget parameter |
| useViewerWidget.ts | Broadcast state, channel list and viewer total |
| realtime/ | Centrifugo connection and subscriptions |
Appearance data is stored in the template payload. Cabinet messaging is described in the widget protocol. Sending update is not a separate acknowledgement of a saved change: reopen the template to verify the result.
Live updates
HTTP requests first load the template, project, broadcast state and channels. For the connection, the example obtains a separate token through /method/centrifuge/auth/connect?v=1. Private subscriptions use tokens from /method/centrifuge/auth/channel?v=1 with channel_name.
| Subscription | Use in the example |
|---|---|
project#PROJECT_ID | Broadcast start and end |
$broadcast:BROADCAST_ID | Viewer and restream list updates |
$widget_template:TEMPLATE_ID | Template data updates |
The API token, connection token and subscription token serve different purposes. A successful HTTP request does not confirm a WebSocket connection. If viewer counts stop updating, check HTTP responses, connection state and the subscription to the correct broadcast separately. Check method formats in the API reference.
The payload supports testMode, which displays generated values for appearance testing. These are not real viewers, and this is not a fully offline mode: loading the template and connecting to events remain part of the example. In normal mode, account for loading, error and offline broadcast states.
Adapting the example
Keep the repository's pinned @streamvi/streamvi-ui dependency. The new UI Kit has a different API and requires migration.
In the example, the installation token is included in the OBS URL, and the message handler checks data shape without restricting the sender before accepting it. For your application, apply the event.origin and event.source validation from the widget example. Verify the launch signature on the server and use separate restricted access for the public display, as described in OBS usage. This React example does not implement server-side token storage or that signature verification.
Run npm run build to check TypeScript and generate static files. It does not create a StreamVi application, project access or a template.