SDK reference

Payments and ads

Copy page

Lia.pay, Lia.charges and Lia.onCharge for Lia's pay sheet, and Lia.showAd and its shortcuts for full screen ads.

#Payments

See Payments and the pay sheet for how they work, and Sell an item for the whole flow.

#Lia.pay(productId, options)

Opens Lia's pay sheet for one of your products. Resolves once it's paid; rejects if it isn't.

JavaScript

const { chargeId, productId } = await Lia.pay("extra-lives");

// With your own key (SDK 1.5): asking again with the same key charges once and answers with the same chargeId.
const order = "order-" + crypto.randomUUID();
const paid = await Lia.pay("extra-lives", { idempotencyKey: order });

Parameter	Type
`productId`	string	One of your products' ids, up to 64 characters.
`options.idempotencyKey`	string	Optional, 1 to 64 of letters, digits, `_`, `-`, `.` and `:`. See Idempotency keys.

Resolves with { chargeId, productId }. Then send the chargeId to your server to deliver it.

Error	When
`cancelled`	The person closed the sheet without paying.
`no_product`	No active product with that id.
`busy`	Another of Lia's screens is open over your app.
`bad_productId`	The id isn't text up to 64 characters.
`bad_idempotency_key`	The key isn't in the right shape.
`not_ready`, `not_in_lia`	Lia isn't ready, or this isn't Lia.

If the page reloads while the sheet is open, the charge arrives as a "charge" event instead (see Lia.onCharge).

#Idempotency keys

From SDK 1.5, the calls that change something (Lia.pay, Lia.inviteFriend, Lia.submitScore and cloud storage's writes) take an optional idempotencyKey. The same key again, within 24 hours, doesn't do it twice: it answers as the first call did.

Lia already keeps each call once when it retries it itself (a dropped connection). Your own key adds the same safety across your page's retries and reloads: keep it (in Lia.deviceStorage, say) until the call is answered.
Make one key per action (crypto.randomUUID() is fine) and reuse it only to retry that action.
The same key with different arguments is refused. Use a new key for a new action.
For a payment, the pay sheet still opens for the person to confirm; confirming with a key that already paid answers with that first charge and charges nothing more.
A Lia app older than SDK 1.5's release ignores the key, so the call still works, just without your key.

#Lia.charges()

This player's paid charges that your server hasn't delivered yet, oldest first, up to 50. Call it when your app opens, and deliver any you find.

JavaScript

const pending = await Lia.charges(); // [{ chargeId, productId }]
for (const charge of pending) await deliverOnServer(charge.chargeId);

Resolves with an array of { chargeId, productId }.

#Lia.onCharge(listener)

Hears a charge that was confirmed while no Lia.pay() was waiting for it, such as after a reload. The listener gets { chargeId, productId }. Returns a function that stops listening. The same as Lia.on("charge", listener).

#Ads

See Ads for the formats, pacing and checking on your server.

#Lia.showAd(options)

Plays a full screen ad over your app. Resolves once it's closed.

JavaScript

const result = await Lia.showAd({ format: "rewarded" });
if (result.watched) giveReward(result.adId);

Option	Type
`format`	string	`"rewarded"` (the default), `"rewardedInterstitial"` or `"interstitial"`.
`onState`	function	Optional. Hears each stage: `"loading"`, `"showing"`, `"closed"`.

Resolves with:

Field	Type
`watched`	boolean	A rewarded ad was watched to the end.
`shown`	boolean	An ad went on screen.
`adId`	string	Present when `watched` is true, and when an interstitial was shown. Check it on your server with `POST /ads/verify`.
`reason`	string	When `watched` is false: `cancelled`, `skipped`, `no_ad`, `too_soon`, `failed` or a connection problem.

Errors: bad_format, busy. Not having an ad to show isn't an error: it resolves with reason: "no_ad".

#Lia.showRewardedAd(options)

The same as Lia.showAd({ format: "rewarded", onState }). A video the person chose to watch.

#Lia.showRewardedInterstitialAd(options)

The same as Lia.showAd({ format: "rewardedInterstitial", onState }). Lia first asks the person, with Watch and Skip; Skip resolves with reason: "skipped".

#Lia.showInterstitialAd(options)

The same as Lia.showAd({ format: "interstitial", onState }). Paced by Lia: when it isn't its turn, it resolves straight away with shown: false, reason: "too_soon".

JavaScript

// Between rounds: ask every time, and let Lia decide.
await Lia.showInterstitialAd();
startNextRound();

#Lia.onAd(listener)

Hears every ad's stages, { state, format }, with state one of "loading", "showing" and "closed". Returns a function that stops listening. The same as Lia.on("ad", listener).