Kappapps SDK

Appearance

Class: PreferenceService ​

Access to the app preferences: the settings configured by the streamer for this app installation on their channel. Lets you read the current values and modify them.

Remarks ​

Accessible everywhere via k.preferences. You never have to instantiate this service yourself — it is created by the SDK when the app/widget starts up, already populated with the current preferences.

Preferences are persisted server-side: they survive refreshes and sessions. When they change (from the config interface), the service automatically resynchronizes and emits EVENTS.UPDATED.

Example ​

ts
// Read a preference at a given path
const color = k.preferences.get('theme.color');

// React to a preferences change
k.preferences.events.on(k.preferences.EVENTS.UPDATED, (changeset) => {
    console.log('Preferences refreshed', Object.keys(changeset));
});

Implements ​

Properties ​

events ​

ts
events: PreferenceEvents;

Subscribe to updates carrying PreferenceChangedPaths.

EVENTS ​

ts
EVENTS: typeof EVENTS;

Preference event names.

Implementation of ​

ts
Omit.EVENTS

preferences ​

ts
preferences: AppliPreferencesData;

The complete tree of the app's preferences, as resolved server-side.

Remarks ​

Automatically resynchronized on every update. To read a specific value, prefer get, which handles nested paths.

Methods ​

get() ​

ts
get(path?): Record<string, any>;

Reads an app preference, possibly nested, via a path.

Parameters ​

path? ​

string = null

Path of the preference to read (e.g. 'theme.color', 'items[0].label'). Bracket indices and dots are supported. If null, returns the complete preferences tree.

Returns ​

Record<string, any>

The value found at the requested path, the complete tree if path is null, or undefined if the path does not exist.

Default Value ​

null

Example ​

ts
const fontSize = k.preferences.get('display.fontSize') ?? 16;

See ​

set to modify preferences.

set() ​

ts
set(changes): Promise<PreferenceSetResult>;

Applies a series of modifications to the app's preferences.

Parameters ​

changes ​

ChangeSet[]

List of modifications to apply — see ChangeSet for the details of each field (path, data).

Returns ​

Promise<PreferenceSetResult>

A PreferenceSetResult: changeset contains the effective changed paths (PreferenceChangedPaths), and errors lists the rejected modifications. Unlike changes, changeset is a path map, not a list of writes: { 'theme.color': true }, or [] for no effective change. { '': true } signals a global refresh.

Remarks ​

Changes are persisted server-side. After awaiting this method, local reads include the confirmed write. Refreshes run in order so older responses cannot overwrite a newer snapshot. An update event is delivered when the effective preferences change.

With conditional preferences, an existing override in the winning variant receives the write; otherwise the main preferences receive it. Groups are routed field by field and collections as a whole.

Example ​

ts
const { changeset, errors } = await k.preferences.set([
    { path: 'theme.color', data: '#ff0000' },
]);
if (errors.length) console.warn('Rejected settings', errors);
const paths = Object.keys(changeset); // [] when nothing changed
if (paths.includes('')) console.log('All preferences', k.preferences.get());
else paths.forEach(path => console.log(path, k.preferences.get(path)));

See ​

get to read preferences.