SDK reference

Startup and lifecycle

Copy page

Lia.init, Lia.ready, Lia.session and Lia.close, and every event Lia sends your page.

#Lia.init()

Call it first. It answers with who the player is and everything about how your app is shown, and fills in the SDK's properties and CSS variables.

JavaScript

const me = await Lia.init();

Resolves with:

Field	Type	What it is
`player`	object	`{ id, name }`: the player's id in your app, and their Lia username. See Players.
`session`	string	A session token for your server, `lias_…`.
`exp`	number	When the session ends, in milliseconds since 1970 (15 minutes after opening).
`mode`	string	`"test"` or `"live"`.
`language`	string	The person's language in Lia, such as `"en"`.
`rtl`	boolean	Whether it reads right to left.
`platform`	string	`"ios"` or `"android"`.
`theme`	string	`"light"` or `"dark"`.
`themeParams`	object	Lia's colours (`bg_color`, `text_color`…).
`display`	string	`"sheet"`, `"full"` or `"fullscreen"`.
`isFullscreen`	boolean	Edge to edge or not.
`viewport`	object	`{ height, expanded }`
`safeArea`	object	`{ top, bottom, left, right }` in px
`contentSafeArea`	object	`{ top, bottom, left, right }` in px
`startParam`	string or null	What your app was opened with.
`link`	string	Your app's invite link, without a startParam.
`sound`	boolean	Whether the person wants your app's sounds.
`notifications`	object	`{ allowed, available }`: whether they allowed your notifications, and whether your app may ask.

Errors: not_in_lia, not_ready (Lia is still opening the app; try again shortly), timeout.

#Lia.ready()

Tells Lia your page is drawn, so it takes its loader away. Call it once your first screen is on the page. Returns nothing.

JavaScript

Lia.init().then(function (me) {
  renderHome(me);
  Lia.ready();
});

#Lia.session()

A fresh session token for your server. Sessions last 15 minutes, so get a new one before calls your server must trust.

JavaScript

const { session, exp } = await Lia.session();

Resolves with { session, exp }. Errors: not_open (the person hasn't opened your app in Lia yet; call init() first), timeout.

#Lia.close()

Closes your app. Resolves with null. If you turned on closing confirmation, this closes without asking.

#Lia.on(event, listener)

Listens for one of Lia's events. Returns a function that stops listening.

JavaScript

const stop = Lia.on("theme", function (data) { redraw(data.colorScheme); });
// later
stop();

Throws bad_listener if listener isn't a function. A listener that throws doesn't stop the others.

#Lia.off(event, listener)

Stops a listener added with Lia.on.

#Lia.onPause(listener)

The same as Lia.on("pause", listener). Returns a function that stops listening.

#Lia.onResume(listener)

The same as Lia.on("resume", listener).

#Events

Event	Data	When
`"pause"`	none	Lia went to the background, or one of Lia's screens (the pay sheet, an ad, a dialog) covered your app. Pause timers and sound.
`"resume"`	none	Back again.
`"theme"`	`{ theme, colorScheme }`	The person switched Lia between light and dark. `theme` is the new colours. CSS variables are already updated.
`"viewport"`	`{ height, expanded, isStateStable }`	Your page's height changed (a sheet pulled up, bottom buttons shown).
`"fullscreenChanged"`	`{ isFullscreen, contentSafeArea }`	Your app went to or from fullscreen.
`"languageChanged"`	`{ language, rtl }`	The person changed Lia's language.
`"startParam"`	`{ startParam }`	A notification or invite for your app was opened while it was already open.
`"notificationsChanged"`	`{ allowed }`	The person allowed or stopped your app's notifications.
`"soundChanged"`	`{ on }`	The person muted or unmuted your app from Lia's ⋯ menu.
`"charge"`	`{ chargeId, productId }`	A payment was confirmed while no `Lia.pay()` was waiting (after a reload). Also `Lia.onCharge`.
`"ad"`	`{ state, format }`	An ad's stage: `"loading"`, `"showing"` or `"closed"`. Also `Lia.onAd`.
`"mainButtonClicked"`	none	The main button was pressed. Also `Lia.mainButton.onClick`.
`"secondaryButtonClicked"`	none	The secondary button was pressed.
`"backButtonClicked"`	none	The header's back button was pressed.
`"settingsButtonClicked"`	none	Settings was chosen in the ⋯ menu.
`"accelerometerChanged"`	`{ x, y, z }`	A reading, while the accelerometer runs.
`"gyroscopeChanged"`	`{ x, y, z }`	A reading, while the gyroscope runs.
`"deviceOrientationChanged"`	`{ alpha, beta, gamma }`	A reading, while orientation runs.
`"accelerometerStarted"`, `"accelerometerStopped"`	none	The sensor started or stopped. Also for `gyroscope` and `deviceOrientation`.

The SDK updates its own properties (Lia.colorScheme, Lia.viewport, Lia.language, Lia.soundOn and the rest) before your listeners run.