Kappapps SDK

Appearance

Class: PluginService ​

Viewer plugin service: a real-time bridge between the overlay (streamer side) and the app's "viewers" page (spectator side). Lets you emit events in both directions and retrieve the public URL of the viewers page.

Remarks ​

Available everywhere via k.plugin. You never have to instantiate this service yourself — it is created by the SDK when the app/widget starts.

Incoming events are received via k.plugin.events: EVENTS.PLUGIN_VIEWERS (event coming from a viewer, with the emitting User) and EVENTS.PLUGIN_STREAMER (event coming from the streamer).

Example ​

ts
// Overlay: push a state to all viewers
await k.plugin.emitViewers(null, 'round.start', { round: 3 });

// Overlay: react to a viewer click
k.plugin.events.on(k.plugin.EVENTS.PLUGIN_VIEWERS, ({ viewer, event, data }) => {
    console.log(`${viewer.display_name} sent ${event}`, data);
});

Implements ​

Properties ​

events ​

ts
events: PluginEvents;

Subscribe to typed plugin messages via on, once and off.

EVENTS ​

ts
EVENTS: typeof EVENTS;

Event names for incoming viewers and streamer plugin messages.

Implementation of ​

ts
Omit.EVENTS

Methods ​

callStreamer() ​

ts
callStreamer(): Promise<void>;

Triggers a call to the streamer (notification on the overlay side) with no data.

Returns ​

Promise<void>

A promise resolved after relay acceptance, not recipient processing. Rejects with code PAYLOAD_TOO_LARGE (413) or RELAY_UNAVAILABLE (503) on relay failure.

Example ​

ts
await k.plugin.callStreamer();

emitStreamer() ​

ts
emitStreamer(event, data?): Promise<void>;

Emits an event to the streamer (overlay), received via EVENTS.PLUGIN_STREAMER.

Parameters ​

event ​

string

Name of the event to emit.

data? ​

Record<string, any> = {}

Arbitrary data associated with the event.

Returns ​

Promise<void>

A promise resolved after relay acceptance, not recipient processing. Rejects with code PAYLOAD_TOO_LARGE (413) or RELAY_UNAVAILABLE (503) on relay failure.

Default Value ​

{}

Example ​

ts
await k.plugin.emitStreamer('viewer_ready', { viewerId: 123 });

See ​

emitViewers to emit to the viewers.

emitViewers() ​

ts
emitViewers(
   users, 
   event, 
data?): Promise<void>;

Emits an event to the viewers page, either to targeted viewers or to everyone.

Parameters ​

users ​

User[]

The recipient viewers (User). Pass null to emit to all viewers.

event ​

string

Name of the event to emit.

data? ​

Record<string, any> = {}

Arbitrary data associated with the event.

Returns ​

Promise<void>

A promise resolved after relay acceptance, not recipient processing. Rejects with code PAYLOAD_TOO_LARGE (413) or RELAY_UNAVAILABLE (503) on relay failure. A targeted send may have partially succeeded; never blindly resend it.

Default Value ​

{}

Example ​

ts
// To all viewers
await k.plugin.emitViewers(null, 'reveal', { answer: 42 });

// To a specific viewer
await k.plugin.emitViewers([user], 'you_won', { coins: 100 });

See ​

emitStreamer to emit on the streamer side.

getViewersPluginUrl() ​

ts
getViewersPluginUrl(): string;

Builds the public URL of the app's viewers page for the current channel.

Returns ​

string

The absolute URL of the viewers page (host + /viewers/<channel>/<app slug>).

Example ​

ts
const url = k.plugin.getViewersPluginUrl();
// e.g. https://kappapps.com/viewers/MyChannel/my-app