Getting started

The Kappapps SDK is loaded automatically by the platform into every app and every widget. By the time your code runs, the SDK is already up and every service is available through the global k object.

App or widget?

	App	Widget
Nature	An interactive game or tool, with a lifecycle	A triggered overlay element (media, announcement, short script)
SDK class	Appli	Widget
Extra services	preferences, dataStorage, userDataStorage, logsStorage, dynamicTriggers, dynamicContent, rewards, plugin	—

Both extend the abstract App class, which carries the shared set of services (chat, users, media, overlay…).

The global k / kapp object

Everywhere in your code, two globals point to the current app/widget instance:

k;     // shorthand
kapp;  // identical alias

It is your entry point to every service:

await k.chat.say('Hey chat!');
const viewer = await k.users.get('toto');
await k.medias.playAudio('https://.../win.mp3', 80);

Available services

A few of the most used ones (full list in the API Reference):

Access	Service	Role
k.chat	Chat	Send messages, listen to messages & commands
k.users	Users	Fetch viewers, currency, roles, moderation
k.medias	Media	Play sounds / videos / images on the overlay
k.announces	Announcements	Composed announcements (chat + TTS + screen)
k.overlay	Overlay	Communicate with the overlay core
k.api	API	Authenticated HTTP calls to the backend
k.twitch / k.stream	Twitch / Stream	Info about the ongoing stream
k.dataStorage (app)	Storage	Persist the app's state
k.preferences (app)	Preferences	Read/write the app's config

Global helpers

Beyond k, the SDK exposes a few global shortcuts:

text('welcome');                  // resolves a textset key (i18n / editable text)
text('welcome', { name: 'Bob' }); // with interpolation
await wait(2000);                 // 2 s pause (Promise)
prefs;                            // the app's preferences object (shortcut for k.preferences)

Lifecycle

An app/widget goes through these stages — bootstrapping (execute) is handled by the platform; you mostly drive the end and the display.

k.display();    // show the app on the overlay
k.undisplay();  // hide it
await k.finish(); // finish cleanly (sends out rewards for an app)
await k.abort('reason'); // interrupt

Hooking code before exit

k.onBeforeFinish(async () => {
    // final save, goodbye message…
    await k.chat.say('Game over!');
});

k.onBeforeAbort(() => {
    // cleanup on interruption
});

k.onBeforeExit('*', () => {
    // runs in both cases (finish or abort)
});

A first complete example

A tiny app that reacts to the !hello command and rewards the viewer:

k.chat.onCommand('hello', async (user, event) => {
    await k.chat.say(`Welcome ${user.display_name} 👋`);
    await k.users.currency.add(user, 100);
});

// Show the app, then finish it after one minute
k.display();
await wait(60_000);
await k.finish();

What's next?

Everything is in the API Reference: every service is documented method by method, with examples. Use the search box (top right) to find a specific function.