@broadcastingplatforms/web-connectors

Analytics and watch-signal connectors for @broadcastingplatforms/player.

Installation

npm install @broadcastingplatforms/web-connectors @broadcastingplatforms/player
# or
pnpm add @broadcastingplatforms/web-connectors @broadcastingplatforms/player

Mux Analytics

Connect analytics via the ready event. The connector automatically destroys itself when the player is destroyed.

Web Component

<bp-player
  id="player"
  source='{"sources":[{"type":"video","url":"..."}]}'
></bp-player>

<script type="module">
  import { createMuxConnector } from '@broadcastingplatforms/web-connectors/mux';

  document.getElementById('player').addEventListener('ready', (e) => {
    createMuxConnector(e.detail, {
      envKey: 'your-mux-env-key',
      data: {
        video_title: 'Big Buck Bunny',
        video_id: 'bbb-001',
      },
    });
  });
</script>

React

import { BPDefaultUI, type PlayerCore } from '@broadcastingplatforms/player-react';
import { createMuxConnector } from '@broadcastingplatforms/web-connectors/mux';

function Player() {
  const handleReady = (player: PlayerCore) => {
    createMuxConnector(player, {
      envKey: 'your-mux-env-key',
      data: {
        video_title: 'Big Buck Bunny',
        video_id: 'bbb-001',
      },
    });
  };

  return (
    <BPDefaultUI
      source={{ sources: [{ type: 'video', url: '...' }] }}
      onReady={handleReady}
    />
  );
}

Update Metadata

Update metadata during playback:

const connector = createMuxConnector(player, { envKey: '...' });

// Later, update metadata
connector.updateMetadata({
  video_title: 'New Title',
});

Configuration

MuxAnalyticsConfig

| Option | Type | Required | Description | |--------|------|----------|-------------| | envKey | string | Yes | Your Mux environment key | | debug | boolean | No | Enable debug logging | | disableCookies | boolean | No | Disable cookie usage | | data | Record<string, unknown> | No | Video/viewer metadata |

Common Metadata Fields

| Field | Type | Description | |-------|------|-------------| | video_id | string | Unique video identifier | | video_title | string | Video title | | video_series | string | Series/channel name | | video_duration | number | Video duration in seconds | | video_stream_type | 'live' \| 'on-demand' | Stream type | | viewer_user_id | string | Unique viewer identifier |

BPLive Integration

When using BPLive sources, metadata is automatically populated from the stream/clip data:

• video_id from stream/clip ID
• video_title from stream/clip title
• video_series from channel name
• viewer_user_id from auth token (if present)

Watch Connector (Stream Rewards)

Reports livestream watch activity over a dedicated WebSocket so the platform can measure verified watch time. Import from the ./watch subpath — pusher-js is only bundled when you do.

The connector subscribes private-watch.{streamId}.{sub} (sub is the access token's JWT subject), emits client-watching { playing, reason } on play/pause transitions plus a still-watching pulse every 10 seconds while playing, and obeys the server directives playback.suspend (pauses the player) and playback.resume (plays, falling back to muted playback when autoplay is blocked). Participation is decided server-side: the channel authorization refuses viewers who are not enrolled, and the server independently validates every signal.

import { BPDefaultUI, type PlayerCore } from '@broadcastingplatforms/player-react';
import { createWatchConnector } from '@broadcastingplatforms/web-connectors/watch';

function Player({ accessToken, streamId }) {
  const handleReady = (player: PlayerCore) => {
    const connector = createWatchConnector(player, {
      accessToken,
      streamId,
      sockudo: {
        appKey: 'your-app-key',
        wsHost: 'rt.example.com',
        authEndpoint: 'https://api.example.com/api/broadcasting/auth',
      },
    });

    // App-driven pause with a semantic reason (e.g. a pending claim blocks playback):
    // connector.reportPause('paused_pending_claim');
  };

  return (
    <BPDefaultUI
      source={{ sources: [{ type: 'bplive', streamId }] }}
      config={{ bpLive: { discoveryUrl: '...', authToken: accessToken } }}
      onReady={handleReady}
    />
  );
}

WatchConnectorConfig

| Option | Type | Required | Description | |--------|------|----------|-------------| | accessToken | string | Yes | Viewer access token (JWT); its sub claim is the viewer's user id and the token authorizes the channel subscription | | streamId | number | Yes | The id of the livestream being played | | sockudo.appKey | string | Yes | WebSocket app key | | sockudo.wsHost | string | Yes | WebSocket hostname | | sockudo.authEndpoint | string | Yes | Channel authorization endpoint | | sockudo.wsPort / wssPort | number | No | Ports (default 443) | | sockudo.forceTLS | boolean | No | Default true |

The connector subscribes only while a bplive stream source is loaded: it re-subscribes when a new livestream session starts and unsubscribes when the source is unloaded or switches to a clip or plain URL. Call reportPause(reason) when your app pauses playback for a semantic reason; the reason is emitted with the pause signal (and still emitted if the player was already paused).

When the channel authorization refuses the subscription (HTTP 403 — the viewer is not enrolled), the connector disconnects and stays silent; it asks again only when a new (different) livestream source loads or a new connector is created. Other authorization failures (network errors, 5xx) are retried with bounded backoff. Playback is never affected.

Lifecycle

Both connectors listen to the player's destroy event and clean themselves up automatically. No manual cleanup is required in most cases.