Guides

Try everything before launch. Testers, test keys and pretend $LIA, running your page from your computer, the SDK demo, and finding problems inside Lia.

#Test mode

New apps start in test. While they are:

• Only you and your testers can open the app. Ask the Lia team to add testers by their Lia usernames.
• Lia's header says Test next to your developer name.
• Payments and rewards use pretend $LIA; nobody's balance moves.
• Use your test key on your server. It only sees test sessions, charges and players.

See Test and live for everything that's different.

#Run it from your computer

Lia only opens https pages from your app's address, so a page on localhost can't open in Lia directly. Put it behind an https tunnel, and ask the Lia team to point your test app at the tunnel's address:

npx vite --port 5173
cloudflared tunnel --url http://localhost:5173

A named tunnel (or any fixed https address) saves asking for a new address each time.

#In a normal browser

Outside Lia, Lia.available is false and every call fails with not_in_lia. For working on layout in a desktop browser, a small stand in helps:

// Only when not inside Lia, and only in development.
if (!window.Lia.available && location.hostname === "localhost") {
  const fake = { player: { id: "p_dev000000000000000000", name: "you" }, session: "dev", exp: Date.now() + 9e5, mode: "test", language: "en", rtl: false, platform: "web" };
  window.Lia = Object.assign(Object.create(window.Lia), {
    init: async () => fake,
    ready() {},
    session: async () => ({ session: "dev", exp: Date.now() + 9e5 }),
    toast: async (text) => console.log("toast:", text),
    haptic: async () => null,
    pay: async (productId) => ({ chargeId: "ch_dev", productId }),
  });
}

Your server won't verify "dev" sessions, so keep a development path there too, or test server flows inside Lia.

#The SDK demo

Lia's own demo app tries every SDK call and shows what comes back: https://api.lialabs.org/sdk/demo. It opens inside Lia for people the team adds as its testers; ask if you'd like to try it. Its source is a good reference for each call.

#Finding problems inside Lia

Lia's store builds don't allow attaching a web inspector to your page. Instead:

• Show errors on screen while testing: a small log panel your testers can screenshot.
• Send errors to your server with the player id, Lia.version, Lia.platform and the error's code.
• Check every rejection's code, not just its message.

window.addEventListener("error", function (event) { report({ message: event.message, at: event.filename + ":" + event.lineno }); });
window.addEventListener("unhandledrejection", function (event) { report({ code: event.reason && event.reason.code, message: String(event.reason) }); });

#Before you go live

• Payments: buy each product, close the sheet without paying, reload mid payment and check Lia.charges() finds it, and refund one.
• Webhooks: a test purchase reaches your handler, its signature checks out, and a second delivery does nothing.
• Rewards: a duplicate key pays nothing; pool_empty and daily_limit are handled.
• Notifications: ask, send, tap one with your app closed and with it open.
• Looks: light and dark, a right to left language (Arabic), a small phone, and fullscreen if you use it.
• Your server switches to the live key in production, and nothing from your test data leaks into live.

Then ask the Lia team to switch your app to live.