# SDK overview

> Loading the Lia SDK, the Lia object's properties, how calls answer and fail, and an index of every method. From the Lia developer docs: https://docs.lialabs.org/reference/sdk

## Loading it

```html
<script src="https://api.lialabs.org/sdk/lia-apps-v1.js"></script>
```

Load it from Lia, before your own scripts. It defines one global, `window.Lia`, once (loading it twice does nothing). It's plain JavaScript with no dependencies, and works with any framework or none. This page describes version 1.6.0.

In TypeScript, declare the global until there's a types package:

```ts
declare global {
  interface Window { Lia: any }
}
const Lia = window.Lia;
```

## How calls answer

- **Most methods return a promise.** It resolves with the answer described for each method, or rejects with an `Error` that has a `code` (and a `message` in English for you, not for players).
- **Bad arguments reject too**, with a code like `bad_text`, before anything reaches Lia. A few methods that don't return promises (`Lia.inviteLink`, `Lia.on`, the buttons' setters) throw instead.
- **Outside the Lia app**, every call rejects with `not_in_lia`. `Lia.available` tells you up front.
- **Lia must answer within 20 seconds**, or the call rejects with `timeout`. Calls that wait on the person (the pay sheet, ads, dialogs, the friend picker, the notifications ask, the scanner, the clipboard, Face ID, share) wait as long as it takes.

```js
try {
  const result = await Lia.pay("extra-lives");
} catch (error) {
  switch (error.code) {
    case "cancelled": return; // they changed their mind
    case "not_in_lia": return showOpenInLia();
    default: Lia.toast("Something went wrong", { tone: "error" });
  }
}
```

Every code is listed in [Error codes](/reference/errors).

## Properties

Read these after [`Lia.init()`](/reference/sdk-lifecycle#lia-init) has answered; before that they hold defaults. Most are kept current by Lia's events.

| Property | Type | What it is |
| --- | --- | --- |
| `Lia.version` | string | The SDK's version, for example `"1.6.0"`. |
| `Lia.available` | boolean | `true` inside the Lia app. Known as soon as the script loads. |
| `Lia.platform` | string | `"ios"` or `"android"` (`"unknown"` before `init()`). |
| `Lia.language` | string | The person's language in Lia: `en`, `es`, `pt`, `fr`, `tr`, `ru`, `vi`, `id`, `fil`, `sw`, `hi`, `ar` or `zh`. See [Language](/concepts/look-and-feel#language). |
| `Lia.rtl` | boolean | Whether that language reads right to left (Arabic). |
| `Lia.colorScheme` | string | `"light"` or `"dark"`. |
| `Lia.theme` | object | Lia's colours, as `bg_color`, `text_color` and the rest. See [Lia's theme](/concepts/look-and-feel#lias-theme). |
| `Lia.viewport` | object | `{ height, expanded }`: your page's height in px, and whether a sheet is at full height. |
| `Lia.safeArea` | object | `{ top, bottom, left, right }`: the phone's safe area in px. |
| `Lia.contentSafeArea` | object | `{ top, bottom, left, right }`: also clear of Lia's floating controls in fullscreen. |
| `Lia.display` | string | How your app opened: `"sheet"`, `"full"` or `"fullscreen"`. |
| `Lia.isFullscreen` | boolean | Whether it's edge to edge right now. |
| `Lia.startParam` | string or null | What it was opened with: an invite's, a link's or a notification's startParam. `null` when opened from the Apps Center. |
| `Lia.soundOn` | boolean | Whether the person wants your app's sounds. |
| `Lia.notificationsAllowed` | boolean | Whether this person lets your app send them notifications. |

### Lia.isVersionAtLeast(version)

Whether the SDK is at least this version, for features added later.

```js
if (Lia.isVersionAtLeast("1.3")) Lia.inviteFriend({ startParam: room });
```

| Parameter | Type | |
| --- | --- | --- |
| `version` | string | Like `"1.3"` or `"1.3.0"`. |

Returns a boolean (not a promise).

## CSS variables

After `init()`, the SDK sets these on your page's root and keeps them current: Lia's theme (`--lia-bg-color` and the rest), `--lia-color-scheme`, `--lia-viewport-height`, `--lia-safe-area-inset-*` and `--lia-content-safe-area-inset-*`. See [Look and feel](/concepts/look-and-feel).

## Every method

| Area | Methods |
| --- | --- |
| [Startup and lifecycle](/reference/sdk-lifecycle) | `Lia.init`, `Lia.ready`, `Lia.session`, `Lia.close`, `Lia.on`, `Lia.off`, `Lia.onPause`, `Lia.onResume` |
| [Payments and ads](/reference/sdk-payments-and-ads) | `Lia.pay`, `Lia.charges`, `Lia.onCharge`, `Lia.showAd`, `Lia.showRewardedAd`, `Lia.showRewardedInterstitialAd`, `Lia.showInterstitialAd`, `Lia.onAd` |
| [Notifications and invites](/reference/sdk-notifications-and-invites) | `Lia.requestNotifications`, `Lia.inviteFriend`, `Lia.inviteLink`, `Lia.share` |
| [Dialogs](/reference/sdk-dialogs) | `Lia.confirm`, `Lia.showPopup`, `Lia.showAlert`, `Lia.showConfirm`, `Lia.toast` |
| [Layout, colours and buttons](/reference/sdk-layout) | `Lia.expand`, `Lia.requestFullscreen`, `Lia.exitFullscreen`, `Lia.enableExpand`, `Lia.disableExpand`, `Lia.enableVerticalSwipes`, `Lia.disableVerticalSwipes`, `Lia.enableClosingConfirmation`, `Lia.disableClosingConfirmation`, `Lia.setBackgroundColor`, `Lia.setHeaderColor`, `Lia.mainButton`, `Lia.secondaryButton`, `Lia.backButton`, `Lia.settingsButton` |
| [Device](/reference/sdk-device) | `Lia.haptic`, `Lia.scanQr`, `Lia.copyText`, `Lia.readClipboard`, `Lia.openLink`, `Lia.openLiaLink`, `Lia.biometric`, `Lia.accelerometer`, `Lia.gyroscope`, `Lia.deviceOrientation` |
| [Scores and storage](/reference/sdk-scores-and-storage) | `Lia.submitScore`, `Lia.leaderboard`, `Lia.cloudStorage`, `Lia.deviceStorage`, `Lia.secureStorage` |

## Coming from Telegram

Lia's SDK follows Telegram's Mini Apps where it fits, so most ideas carry over:

| Telegram | Lia |
| --- | --- |
| `Telegram.WebApp.initData` | `Lia.init()` answers with a session token your server verifies with [`POST /session/verify`](/reference/server-api#post-session-verify). |
| `themeParams`, `--tg-theme-*` | `Lia.theme`, `--lia-*` (same names) |
| `MainButton`, `SecondaryButton`, `BackButton`, `SettingsButton` | `Lia.mainButton`, `Lia.secondaryButton`, `Lia.backButton`, `Lia.settingsButton` |
| `HapticFeedback` | `Lia.haptic(kind)` |
| `CloudStorage`, `DeviceStorage`, `SecureStorage` | `Lia.cloudStorage`, `Lia.deviceStorage`, `Lia.secureStorage` (promises, not callbacks) |
| `showPopup`, `showAlert`, `showConfirm` | The same, as promises |
| `openInvoice` and Stars | `Lia.pay(productId)`, paid in $LIA |
| `start_param` | `Lia.startParam` |