# How apps run in Lia

> Your page runs in a locked frame inside the Lia app and reaches Lia only through the SDK. The three looks, Lia's header and menu, and the rules your page runs under. From the Lia developer docs: https://docs.lialabs.org/concepts/how-apps-run

## The frame

When someone opens your app, Lia asks its server whether they may (see [Test and live](/concepts/test-and-live)), signs them in as a player of your app, and loads your page in a frame inside the Lia app. Your page is a normal web page: any framework, any host, served over https.

The frame is locked down so people can trust every app in Lia:

- **Only your own pages load.** The frame stays on your app's origin (its scheme, host and port). A link or redirect to any other site is blocked. Open other sites with [`Lia.openLink`](/reference/sdk-device#lia-openlink).
- **Your page can still fetch.** Scripts, images, fonts and `fetch()` calls to other addresses work as on the web (with CORS, as usual).
- **No popups or new windows**, no camera, microphone or location, and no payments of your own. Money, ads and anything on the phone happen in Lia's own screens over your app.
- **Lia only hears your page in the top frame.** SDK calls from an iframe inside your page, or from a page on another origin, are ignored.
- **Messages are small and paced.** A call over 16,000 characters is ignored (and times out). More than 20 calls in one second are refused with `slow_down`.

Lia's frame reports `LiaApps/1` at the end of its user agent, if you want to recognise it on your server.

## The bridge

The SDK talks to Lia through the frame's bridge. Each call your page makes is a message with an id; Lia answers it once, and the SDK turns that into a promise. Lia also sends events (the theme changed, the app paused) that you listen to with [`Lia.on`](/reference/sdk-lifecycle#lia-on).

Calls that wait on the person (the pay sheet, an ad, the scanner, Face ID, a dialog) have no time limit. Every other call fails with `timeout` if Lia hasn't answered within 20 seconds. Outside the Lia app there is no bridge, and every call fails with `not_in_lia`.

> **Note** Load the SDK from `https://api.lialabs.org/sdk/lia-apps-v1.js`, never a copy. Lia serves it so that fixes reach every app; it's cached for a minute.

## Three looks

Each app opens in one of three looks, set by the Lia team for your app. Your page can switch between them with the SDK.

| Look | What it is |
| --- | --- |
| `sheet` | Over Lia like a Telegram mini app, about four fifths of the screen high. The person can pull it up to full height, or your page calls [`Lia.expand()`](/reference/sdk-layout#lia-expand). A swipe down closes it. Most apps open this way. |
| `full` | The whole screen, under Lia's header. |
| `fullscreen` | Edge to edge, with only Lia's floating Close and ⋯ buttons over your page. Keep your content below [`Lia.contentSafeArea.top`](/concepts/look-and-feel#safe-areas). |

`Lia.display` says how your app opened, and `Lia.isFullscreen` whether it's edge to edge right now. [`Lia.requestFullscreen()`](/reference/sdk-layout#lia-requestfullscreen) and `Lia.exitFullscreen()` switch to and from fullscreen.

## Lia's header and menu

In `sheet` and `full`, Lia draws a header over your page: your app's icon and name (and **Test** with your developer name while in test), a ⋯ menu and Close. You can [colour it](/reference/sdk-layout#lia-setheadercolor) and show a [back button](/reference/sdk-layout#lia-backbutton) in it.

The ⋯ menu always has:

- **Settings**, when your page shows [`Lia.settingsButton`](/reference/sdk-layout#lia-settingsbutton).
- **Notifications on or off**, when your app may send them (see [Notifications](/concepts/notifications)).
- **Mute or unmute sounds**, which your page hears as [`soundChanged`](/concepts/look-and-feel#sound).
- **Reload** and **Close**.

## While your page loads

Lia shows its own loader over your app from the moment it opens until your page calls [`Lia.ready()`](/reference/sdk-lifecycle#lia-ready) (or finishes loading). Call it as soon as your first screen is drawn. If your page fails to load, Lia shows a message with Try again.

## Pause and resume

Your page hears `pause` when Lia goes to the background or covers your app with one of its own screens (the pay sheet, an ad, a dialog, the scanner), and `resume` when it's back. Pause timers, music and game loops on `pause`. See [Lifecycle and events](/reference/sdk-lifecycle).

## One sheet at a time

Lia shows one of its own screens over your app at a time. While the pay sheet, an ad, a dialog, the friend picker, the notifications ask, the scanner or Face ID is open, another such call fails with `busy`.

## Who may open your app

- People need a Lia **username** to open any app.
- While your app is in **test**, only you and your testers can open it. When it's **live**, everyone can. When it's **paused**, nobody can. See [Test and live](/concepts/test-and-live).
- If the Lia team set a **minimum streak** for your app, people need a check-in streak that long to open it. Lia shows them how to get there.