Kappapps SDK

Appearance

Class: OverlayService ​

Service for communicating with the host overlay (the layer that displays the app/widget on top of the stream): showing on-screen notifications and announcements, and a low-level message bridge between the app and the platform core.

Remarks ​

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

Read layout for the current iframe dimensions, subscribe to EVENTS.LAYOUT_CHANGED, or resolve a saved placement with resolveArea. The app owns its responsive UI; visual scaling is already applied by the parent.

Example ​

ts
// Show an on-screen notification for 5 seconds
await k.overlay.notification('GG! 🎉', { duration: 5, title: 'Victory' });

Implements ​

Properties ​

displayMode ​

ts
displayMode: OverlayDisplayMode;

Actual display context of this execution.

  • overlay: OBS/main or secondary broadcast overlay.
  • external: interactive external/externable popout.

This describes the hosting runtime, not the app's lifecycle. Use isExternal() to identify the actual display surface.

events ​

ts
events: OverlayEvents;

Subscribe to layout changes and overlay preference updates.

EVENTS ​

ts
EVENTS: typeof EVENTS;

Event names, including LAYOUT_CHANGED for the current drawing surface.

Implementation of ​

ts
Omit.EVENTS

layout ​

ts
layout: OverlayLayout;

Current logical drawing surface. Read its dimensions or use CSS/native resize.

Methods ​

announce() ​

ts
announce(message, options?): Promise<void>;

Shows an announcement on screen, on top of the stream (more prominent than a notification).

Parameters ​

message ​

string

Announcement text (or HTML).

options? ​

AnnounceOptions = {}

Display options (duration, title, HTML…) — see AnnounceOptions.

Returns ​

Promise<void>

A promise resolved once the request has been sent to the backend.

Default Value ​

{}

Example ​

ts
await k.overlay.announce('The game is starting!', { duration: 6, title: 'Grab your controllers' });

See ​

notification for a discreet notification.

debug() ​

ts
debug(id, message): void;

Sends a debug message to the host overlay (the debugData channel).

Parameters ​

id ​

string

Free-form identifier grouping related debug messages.

message ​

string

Debug message to send.

Returns ​

void

isExternal() ​

ts
isExternal(): boolean;

Returns whether this execution is running in the interactive external popout rather than on a non-clickable OBS overlay.

Returns ​

boolean

Remarks ​

This is independent from the app manifest's launch-mode and from the technical overlay OverlayService.type | type. In particular, never use type === 'oneshot' as an external-mode check.

notification() ​

ts
notification(message, options?): Promise<void>;

Shows a notification on screen, on top of the stream.

Parameters ​

message ​

string

Notification text (or HTML).

options? ​

NotificationOptions = {}

Display options (duration, title, HTML…) — see NotificationOptions.

Returns ​

Promise<void>

A promise resolved once the request has been sent to the backend.

Default Value ​

{}

Example ​

ts
await k.overlay.notification('New follower!', { duration: 4 });

See ​

announce for a more prominent announcement.

resolveArea() ​

ts
resolveArea(area): OverlayRect;

Resolve a saved horizontal/portrait placement without modifying it.

Parameters ​

area ​

OverlayArea

Returns ​

OverlayRect