Class: UserDataStorageService

Persistent per-viewer storage for the app: associates a free-form data object with each user (identified by their user_id), kept on the server side from one session to the next.

Remarks

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

Unlike k.dataStorage (a single global state for the app), this service stores state that is specific to each viewer (progression, personal statistics, player preferences, etc.). The data is then accessible on the User side via its appli_data.

Reserved for apps (kapp.isApp()): when called from a widget, the methods throw an AppMethodError.

Example

// Store a viewer's best score
k.chat.onCommand('win', async (user) => {
    await k.userDataStorage.set(user.id, { bestScore: 100 });
});

Implements

• ServiceInterface

Methods

reset()

reset(labels): Promise<void>;

Resets selected top-level fields for all viewers accessible to this app on the current channel.

Parameters

labels

string[]

Non-empty list of field names (keys) to reset.

Returns

Promise<void>

A promise resolved once the reset has been performed.

Remarks

Fields declared in player_stats.config.json return to their typed default values. Other selected fields are deleted. Unselected fields are preserved; missing fields without a configured default are ignored. Viewers without stored data are left unchanged. An unreadable or invalid statistics configuration rejects the reset before any data changes. An omitted or empty list is rejected: use resetAll to clear all user data. Viewers who blocked this app are excluded. Reload already-loaded viewer data with k.users.get(user.id, 'id') before reading it.

Reserved for apps: throws an AppMethodError if called outside an app context (kapp.isApp() false).

Example

// Reset the configured score and delete the free-form inventory field
await k.userDataStorage.reset(['score', 'inventory']);

See

set to write a viewer's data.

Deprecated

Use userDataStorageV2.reset().

---

resetAll()

resetAll(): Promise<void>;

Deletes all persistent user data for all viewers accessible to this app on the current channel.

Returns

Promise<void>

A promise resolved once the data has been deleted.

Remarks

Clears configured statistics and free-form fields. The next server read recreates the defaults from player_stats.config.json, or an empty object if no defaults exist. Reload already-loaded viewer data with k.users.get(user.id, 'id') before reading it. Other apps, other channels, global dataStorage, preferences and logs are unaffected. Viewers who blocked this app are excluded.

Reserved for apps: throws an AppMethodError outside an app context.

Example

// Start a new season without any saved viewer progression
await k.userDataStorage.resetAll();

See

reset to reset only selected fields.

Deprecated

Use userDataStorageV2.resetAll().

---

set()

set(user_id, data): Promise<void>;

Saves the app's persistent data for a given viewer.

Parameters

user_id

number

Identifier of the viewer concerned (e.g. user.id).

data

Record<string, any>

The data object to associate with this viewer.

Returns

Promise<void>

A promise resolved once the data has been saved.

Remarks

Reserved for apps: throws an AppMethodError if called outside an app context (kapp.isApp() false).

Example

await k.userDataStorage.set(user.id, { level: 3, xp: 1250 });

See

reset to clear this data.

Deprecated

Use userDataStorageV2.set().