Concepts

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.

#The frame

When someone opens your app, Lia asks its server whether they may (see 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.
• 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.

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.

#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.

Lia.display says how your app opened, and Lia.isFullscreen whether it's edge to edge right now. 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 and show a back button in it.

The ⋯ menu always has:

• Settings, when your page shows Lia.settingsButton.
• Notifications on or off, when your app may send them (see Notifications).
• Mute or unmute sounds, which your page hears as soundChanged.
• 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() (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.

#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.
• 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.