Browser SDK

Overview

gamecoin.js is the SDK for the browser. It is one file, with no dependency and no build step (ES2020). It talks to the client API (/api/v1/client/**) with your publishable key.

A browser can read, spend, buy an item with a currency, consume an item, pay for a pack, redeem a gift code and open the shop widget. It can never credit a player by itself: the SDK has no grant, no item grant, no refund. Coins come from a paid order or from your server, with one exception: a gift code that your studio created, which gives free coins and items, once per player, and with a limited number of uses (see redeemCode()). See the Security model.

The SDK runs in two modes:

Install

Load the file with a classic script tag, from your GameCoin host. It adds a global GameCoin and takes the host it was loaded from as the place to call.

<script src="https://gamecoin.apilow.com/sdk/gamecoin.js"></script>
<script type="module">
  const gc = await GameCoin.init({ publishableKey: "gc_pk_test_…" });

  gc.on("change", ({ wallet, inventory }) => console.log(wallet.balances, inventory));
  console.log(gc.balance("gems"));
</script>

The file is also a CommonJS module (module.exports), for a bundler or a test. There, it cannot know where it was loaded from, so pass baseUrl. Download it and ship it with your game if you prefer not to load it from our host.

const GameCoin = require("./gamecoin.js");
const gc = await GameCoin.init({ publishableKey: "gc_pk_test_…", baseUrl: "https://gamecoin.apilow.com" });

GameCoin.version is the version of the file ("1.2.0").

GameCoin.init()

GameCoin.init(options) → Promise<GameCoinClient>

init makes the player ready (it creates or recognizes them), reads their wallet and inventory, and returns the client. Await it before anything else.

init fails with a GameCoinError when the key is missing, is a secret key, is not a publishable key, or when baseUrl is needed and absent. These errors are raised before any request. Anonymous players that are turned off for the game make init fail with FORBIDDEN.

A page that comes back from a redirect checkout also has ?order=…&status=… in its address. init reads that order, removes the parameters from the address, and exposes the order as gc.returnedOrder.

The client

const gc = await GameCoin.init({ publishableKey: "gc_pk_test_…" });

Properties

Methods at a glance

Every call that talks to GameCoin returns a promise and fails with a GameCoinError. One function does not need a client or the server: GameCoin.packStatus(pack, now?) tells whether a pack of the catalog is scheduled, on sale, sold out or ended, see Pack status.

Reading

getCatalog()

gc.getCatalog() → Promise<{ currencies, items, packs, prelaunch, launchAt }>

The active currencies, items and packs of your game. It needs only the publishable key, so it works before a player exists. Prices of packs are in euro cents, VAT included.

const { currencies, items, packs } = await gc.getCatalog();
console.log(packs.map((p) => `${p.name}: ${(p.priceCents / 100).toFixed(2)} €`)); // [ 'Starter pack: 0.99 €', 'Bag of gems: 4.99 €' ]

The catalog is what the API answers, with one change: the dates are Date objects, not strings. They are the ones of the founder packs and of the launch of your game:

The catalog also lists the packs that are scheduled, ended or sold out: you decide what to show. A date that cannot be read becomes null, never an invalid Date.

Pack status

GameCoin.packStatus(pack, now = new Date()) → "scheduled" | "on_sale" | "sold_out" | "ended"

A pure function: it makes no request and needs no client. It applies the rules of the server to a pack of getCatalog() (or of the raw API answer: ISO strings are accepted). now is a Date, a timestamp in milliseconds or an ISO string; a value that is none of these fails with VALIDATION_FAILED.

The window comes first: a pack that has ended is "ended" even when it is also sold out, as on the server.

const catalog = await gc.getCatalog();
for (const pack of catalog.packs) {
  const status = GameCoin.packStatus(pack);
  if (status === "scheduled") showSoon(pack, pack.availability.startsAt);
  else if (status === "on_sale") showBuyButton(pack, pack.availability?.remaining); // "312 left", or null
  else showGreyedOut(pack, status); // "sold_out" or "ended"
}
if (catalog.prelaunch && catalog.launchAt) showBanner("Launch on " + catalog.launchAt.toLocaleDateString());

getWallet(), getInventory() and refresh()

gc.getWallet()     → Promise<Wallet>
gc.getInventory()  → Promise<InventoryItem[]>
gc.refresh()       → Promise<{ wallet, inventory }>

Each one reads the server (one request, GET /client/me) and updates the cache. If the wallet or the inventory changed, a change event fires with reason: "refresh". Use refresh() after your server changed something, for example a reward it granted.

await fetch("/api/level-complete", { method: "POST" }); // your server grants gems
await gc.refresh();
console.log(gc.balance("gems"));

balance() and owned()

gc.balance(currency) → number
gc.owned(sku)        → number

Synchronous reads of the cache: balance is the total of a currency, owned is the quantity of an item. Both return 0 for a code the SDK does not know. They make no request, so call them as often as you draw the screen.

Changing

The calls below take a last argument options. Its main key is idempotencyKey: see idempotency.

spend()

gc.spend(currency, amount, reason?, options?) → Promise<{ entry, balance }>

Spends currency with no item: "continue?", a skip, an entry fee.

const { entry, balance } = await gc.spend("gems", 5, "continue");
console.log(entry.type, balance.total); // spend 95

buyItem()

gc.buyItem(sku, quantity = 1, options?) → Promise<{ entry, balance, item }>

Buys an item with its own price, in its own currency. The wallet is debited and the item added in one step. Only items marked « Achetable depuis le jeu (API cliente) » in the dashboard can be bought from the browser.

const { balance, item } = await gc.buyItem("potion", 2);
console.log(balance.total, item.quantity); // 55 2

consume()

gc.consume(sku, quantity = 1, options?) → Promise<{ item }>

Uses up units of a consumable item. The returned item is the item as it now stands, even when it reaches quantity: 0.

const { item } = await gc.consume("potion");
console.log(item.quantity); // 1

redeemCode()

gc.redeemCode(code, options?) → Promise<{ grants, items, skipped }>

Redeems a gift code that your studio created, for the current player. It is the only call of the browser SDK that adds coins, and it is safe because the value is decided by your studio, not by the browser: the code is random, it has a limited number of uses, a player can use it once, and it gives free coins (never paid ones) and items. See Codes API.

try {
  const { grants, items, skipped } = await gc.redeemCode(input.value);
  showMessage(`You received ${grants.map((g) => g.amount + " " + g.currency).join(", ")}!`);
} catch (error) {
  if (!(error instanceof GameCoin.GameCoinError)) throw error;
  if (error.details.fieldErrors?.code) showMessage("This code is not valid.");
  else if (error.code === "LIMIT_REACHED") showMessage("You already have this reward.");
  else if (error.code === "RATE_LIMITED") showMessage("Too many tries. Wait a little.");
  else throw error;
}

The cached balances take the value of the answer, the cached quantities of the items go up by what was added, and a change event fires with reason: "code". If you need the exact inventory after a long time, call refresh().

The call is idempotent like the others: it sends a key (yours, or a random one), replays on a network error with the same key, and a replay credits nothing twice. A code the player already redeemed is a refusal like any other: typing it again, with a new key, gives CODE_INVALID.

With a playerToken from your backend, the call works too: the token is the player's, so the code is redeemed for them and the cache follows. If your backend must decide who may redeem (a login, a quota of your own), do not offer the code field in the browser: call the server route from your server.

checkout()

gc.checkout(packSku, options?) → Promise<Order>

Sells a pack for euros. It opens the hosted payment page and resolves when the order is over. Call it straight from a click: the SDK opens the payment window synchronously, before any request, and browsers block windows that are not opened by a user action.

document.getElementById("buy").onclick = async () => {
  const order = await gc.checkout("gems-500");
  console.log(order.status); // "fulfilled", "failed" or "pending"
};

What it resolves with, in a window:

The SDK listens to the window's postMessage (only from the GameCoin origin) and reads the order from the API every 2 seconds. A message is only a signal: the status always comes from the API, never from the message.

Redirect. When the browser blocks the window, or with mode: "redirect", the current tab goes to the payment page and returns to the current address. The promise then resolves at once with the pending order plus redirected: true, since the page is about to leave. On the way back, init() reads the order, removes ?order=&status= from the address, exposes it as gc.returnedOrder, and fires a change event with reason: "return" and the order.

const gc = await GameCoin.init({ publishableKey: "gc_pk_test_…" });
gc.on("change", ({ reason, order }) => {
  if (reason === "return") console.log("back from payment:", order.status);
});
if (gc.returnedOrder) console.log(gc.returnedOrder.status);

Only one checkout can run at a time: a second call while the first runs fails with CONFLICT.

See Selling packs for VAT, return URLs and the life of an order.

Creator code

A buyer who has a creator code (a streamer's code) types it at checkout. Pass it as it was typed:

const order = await gc.checkout("gems-500", { creatorCode: input.value || undefined });
console.log(order.creatorCode); // { code: "LEAPLAY", creatorName: "Léa Play" }, or null without a code

• It goes in the field creatorCode of the order. The SDK does not change it (the API ignores the case). Anything but a non-empty string fails at once with VALIDATION_FAILED, before any window or request: pass undefined when the buyer typed nothing.
• The Order that checkout() resolves with (and gc.returnedOrder) has creatorCode: { code, creatorName }, or null. It never carries the rates of the creator.
• A code that cannot be used (unknown, disabled, not valid for this pack, or the creator's own player) is refused by the API with VALIDATION_FAILED and details.fieldErrors.creatorCode equal to ["CODE_INVALID"], one answer for every cause. The SDK passes that error on as it is, never replays it, and closes the payment window it had opened: no order was created. Tell the player the code is not valid, and let them try again or buy without it.
• The bonus coins that the code gives are added by GameCoin when the order is delivered, with the pack, so the wallet that checkout() refreshes already has them.

Open the shop

gc.openShop(options) → Promise<{ close() }>

Opens the shop widget over your game, as the player of this SDK. The SDK holds the player token, so you do not have to make one, keep one or pass one around: that is the way to use the widget in a game without a server.

document.getElementById("shop").onclick = async () => {
  const shop = await gc.openShop({ gameSlug: "my-game", locale: "en", theme: "dark" });
  // later, if you need to: shop.close();
};

gc.on("change", ({ wallet, reason }) => {
  if (reason === "shop") draw(wallet); // the player bought something, or typed a code, in the shop
});

Wrong options fail at once with VALIDATION_FAILED (status: 0), before anything is loaded. The other options of the widget (baseUrl, token) are not options here: the SDK uses its own base and its own token.

What the SDK does, in this order:

1. Loads the widget once. If window.GameCoinShop does not exist, it adds one <script src> for gamecoin-widget.js, from the same place as the SDK (<baseUrl>/sdk/gamecoin-widget.js), and waits for it. It never uses eval. The script is added once per page, however many times you call openShop(). If it cannot be loaded (network, or a Content-Security-Policy whose script-src does not allow your GameCoin host), the call fails with NETWORK_ERROR, and the next call tries again.
2. Makes sure the token is fresh. A token that has less than 5 minutes left is renewed first, the way the SDK renews it after a 401. See The token of a backend game for your own tokens.
3. Opens the shop with GameCoinShop.open, and gives it the token.

What the shop tells your game

The events of the widget are relayed on the client, with gc.on(event, handler):

Before "shop:purchased", the SDK reads the player (GET /client/me) and, if the wallet or the inventory changed, fires change with reason: "shop". It does the same when the shop shows a balance that is not the one in the cache, which is what happens when the player types a gift code in the shop. The balance that the widget announces is only a signal: the numbers always come from the API.

Only one shop is open at a time: openShop() while another is open closes it first ("shop:close" fires once for it), and the handle of the old one no longer closes anything. A second openShop() while the first is still opening fails with CONFLICT.

The token of a backend game

With a playerToken from your server, openShop() opens the shop as that player, with that token: nothing is created and nothing is refused. The SDK cannot read the end of a token that your server made, so it first reads the player (one request). If the token is refused, it goes through onTokenExpired like any other call, and the shop opens with the new token. Without onTokenExpired, the call fails with UNAUTHENTICATED and the shop does not open. A token that is accepted but about to end is not renewed: the shop swaps it for its own session of one hour as soon as it loads. Pass onTokenExpired, as for every backend game.

Language

Three calls send e-mails or show a page to the player: checkout() (payment page, receipt and e-mails of the order), requestEmailCode() and signInWithEmail() (the e-mail with the code). They accept the same locale option, "fr", "en" or "nl":

await gc.checkout("gems-500", { locale: "nl" });
await gc.requestEmailCode("alice@example.com", { locale: "en" });

Without it, the SDK uses the language of your page, the lang attribute of <html>, when it is one of the three ("fr-BE" counts as "fr"). For any other language, or none, it sends nothing and the server follows the browser's Accept-Language, then French. A locale that is not one of the three is not sent either, because the API ignores it. A locale that is not a string fails with VALIDATION_FAILED, before any request or any window.

E-mail sign-in

An anonymous player lives in the browser's storage. With an e-mail address and a six-digit code (no password) they can find the same player, with their coins and their items, on another device or after clearing the storage. The Sign in players with their e-mail guide explains the idea and the routes; this section is the SDK.

The four methods are for anonymous players. With a playerToken from your backend they fail at once with FORBIDDEN (status: 0, no request): in that mode your backend owns the identity of the player. All four are idempotent like the other calls, and take a last options argument with idempotencyKey, and with locale for the two that send a code.

// 1. The player types their address; GameCoin e-mails a 6-digit code.
await gc.requestEmailCode("alice@example.com", { locale: "en" }); // { sent: true, expiresInSeconds: 600 }

// 2. The player types the code. Keep it a string: "042917" starts with a zero.
try {
  const { player, merged, switched } = await gc.verifyEmailCode("alice@example.com", "042917");
  if (switched) console.log("welcome back, you are now player", player.id);
} catch (error) {
  if (error instanceof GameCoin.GameCoinError && error.details.fieldErrors?.code) showMessage("That code is not valid. Ask for a new one.");
  else throw error;
}

Sending a code always answers { sent: true, expiresInSeconds }, whether the address is known or not.

What the check returns and keeps

verifyEmailCode and verifySignIn resolve with { player, merged, switched }:

The new token and the new playerSecret that the API returns never reach your code: the SDK keeps them, the way it keeps the token and the secret of an anonymous player. The token replaces the current one. A new secret replaces the remembered { playerId, playerSecret } in the storage, so the next visits and every token renewal act as the player you got back. If the player changed, the SDK reads the wallet and the inventory of the new player and fires change with reason: "email" (after verifyEmailCode) or "sign-in" (after verifySignIn), even when the numbers are the same: gc.player is not the same player any more. If that read fails, the cache is emptied rather than left showing the previous player's coins, and the next refresh() fills it again.

Wrong codes

A wrong, expired, used up, already used or never requested code always gives the same error, so that nobody learns anything from it: a GameCoinError with code: "VALIDATION_FAILED", status: 400 and details.fieldErrors.code equal to ["CODE_INVALID"]. The session and the storage do not change. Five wrong tries kill a code: ask for a new one with requestEmailCode or signInWithEmail. code must be a string: a number fails locally with VALIDATION_FAILED, because 42917 is not "042917". Spaces and dashes in the string are ignored by the API.

Events

change

The SDK keeps a copy of the wallet and the inventory. It fires change whenever that copy actually changes.

gc.on("change", handler) → unsubscribe function
gc.off("change", handler)

handler receives { wallet, inventory, reason, order? }. wallet and inventory are copies. reason says what caused the change:

An error in your handler does not break the SDK or the other handlers. It is reported as an uncaught error. A call that fails changes nothing and fires nothing. on returns a function that removes the handler:

const stop = gc.on("change", ({ wallet }) => draw(wallet));
// later
stop();

Shop events

gc.on also takes "shop:purchased", "shop:close" and "shop:error", the events of the shop opened by openShop(). They have no wallet in their payload: read it with gc.wallet, or wait for change. Any other event name fails with VALIDATION_FAILED.

Idempotency and retries

Every call that changes something (spend, buyItem, consume, checkout, redeemCode and the e-mail calls) sends an idempotency key. By default the SDK makes a random one per call and reuses it for every automatic replay of that call. A retry therefore cannot count twice.

To make a call safe across a page reload, give your own key as the last argument:

await gc.spend("gems", 5, "level-3-entry", { idempotencyKey: "level-3-entry-2026-10-05" });

The SDK replays a request, with the same key, in these cases:

Each attempt has a timeout of timeoutMs (20 seconds by default).

Expired tokens

A player token lasts one hour. When a request is refused with 401:

• Anonymous player. The SDK exchanges the stored secret for a new token by itself, then replays the request with the same idempotency key. You do nothing.
• Your player (playerToken). The SDK calls onTokenExpired once. Return a new token from your server, and the SDK replays the request.

const getToken = async () => (await fetch("/api/gamecoin-token", { method: "POST" })).json().then((r) => r.token);

const gc = await GameCoin.init({
  publishableKey: "gc_pk_test_…",
  playerToken: await getToken(),
  onTokenExpired: getToken,
});

Without onTokenExpired, a refused token is raised as UNAUTHENTICATED (and the SDK never creates a player in its place). If the new token is refused too, the SDK stops: it does not loop. Several requests that fail together cause a single renewal.

To swap the token yourself, for example after the player logged in again, use gc.setPlayerToken(token).

Errors

Every failure is a GameCoinError, available as GameCoin.GameCoinError for instanceof.

try {
  await gc.buyItem("fire-sword");
} catch (error) {
  if (!(error instanceof GameCoin.GameCoinError)) throw error;
  switch (error.code) {
    case "INSUFFICIENT_FUNDS":
      showShop(error.details.required - error.details.available);
      break;
    case "LIMIT_REACHED":
      showMessage("You already own it.");
      break;
    case "NETWORK_ERROR":
      showMessage("No connection. Try again.");
      break;
    default:
      throw error;
  }
}

Arguments the SDK can judge itself (an empty sku, an amount of 0 or 1.5) fail with VALIDATION_FAILED and status: 0, with no request. A NETWORK_ERROR after the last attempt means the write may or may not have happened: read the wallet with refresh(), or pass your own idempotencyKey so that a retry cannot count twice. All codes are in Errors.

The player and the browser's storage

On an anonymous player's first visit, the SDK creates the player and keeps { playerId, playerSecret } in the browser's storage, under a name that includes your publishable key. The next visits use that secret to get a token. Two different publishable keys give two different players in the same browser.

• If the stored player is refused (401), the SDK creates a new one. Any other error creates nothing.
• If localStorage is not available (private mode, blocked data, a sandboxed frame), the SDK uses memory: the game works, and the player is new on the next visit.
• storage: null keeps nothing at all.
• To use your own store (an engine's save system), pass { getItem, setItem, removeItem }.

The secret never leaves that browser, and it cannot be recovered. Clearing the data makes a new player, unless the player linked an e-mail address: they can then get the same player back with signInWithEmail().

Browsers and limits

• ES2020, fetch and AbortController. Every modern browser has them.
• crypto.randomUUID() only exists on secure pages (https:, localhost); elsewhere the SDK makes its keys from random bytes.
• The client API answers only the origins listed in the game's settings (any origin in test while the list is empty). The SDK never sends cookies.
• A page served from file:// has no real origin: pass baseUrl. For anything that involves a payment, serve the game over http://localhost or https://.

Where next

• A game without a backend: the SDK from first line to a working page.
• A game with a backend: the SDK with a player token.
• Selling packs
• Gift codes and creator codes and Founder packs
• Shop widget: the shop inside your web game.