Custom apps

Browser bridge

The Pocketbook object your app's page uses: the context with theme, colours and signal, requests to your server actions, messages from Lua and the way home.

Your app's page runs in a frame inside the notebook, from your own resource (https://cfx-nui-<your-resource>/...). It talks to the notebook through sdk/pocketbook.js, which ships in fx-pocketbook. Copy it into your page folder and load it before your own script:

html<script src="pocketbook.js"></script>
<script src="app.js"></script>

It defines window.Pocketbook.

Member What it does
Pocketbook.version 1
Pocketbook.context The last context, or null before the first one
Pocketbook.onContext(fn) Calls fn(context) now if a context is known, and on every change. Returns a function that stops it.
Pocketbook.onMessage(fn) Calls fn(data) for every SendCustomAppMessage from your Lua. Returns a function that stops it.
Pocketbook.request(action, payload) Runs one of your server actions. Returns a promise of the result table.
Pocketbook.home() Leaves the app and goes to the notebook's home page.

#Context

The notebook sends the context when the page has loaded, and again when the book's colour or the signal changes.

jsPocketbook.onContext((context) => {
  document.documentElement.style.setProperty('--ink', context.colors.ink);
  document.documentElement.style.setProperty('--muted', context.colors.muted);
  document.documentElement.style.setProperty('--accent', context.colors.accent);
  document.querySelector('#bars').textContent = context.signal;
});
Field What it is
version 1
theme The notebook colour: standard, dark, pink, white, red, darkred, forest, midnight, tobacco, sand, mustard, slate, olive, teal or plum
colors.ink Main ink colour for text
colors.muted Lighter ink for secondary text and lines
colors.accent Accent ink
signal Signal bars, 0 to 5
preview true when the notebook runs in a normal browser for preview, not in the game

Wait for the first context before you send requests. Requests sent earlier answer { ok: false } at once. The context object is frozen; read it, do not change it.

#Requests

jsconst result = await Pocketbook.request('balance', { account: 'main' });
if (!result.ok) showError(result.error);
  • action is the name of a function you passed to [RegisterApplication](/phone/docs/pocketbook/exports/server/custom-apps): letters and numbers, starting with a letter, up to 32 characters.
  • payload is a plain object. With the request it must stay under 32 KiB as JSON and 8 levels deep.
  • The promise always resolves; it never rejects. Errors come back as { ok: false, error }:
  • the notebook has not sent a context yet,
  • 4 requests are already waiting,
  • no answer within 15 seconds,
  • the server refused (no character, no notebook item, app not installed, another request still running),
  • your action returned ok = false.
  • A timeout does not mean the action failed on the server. For writes, send a stable nonce in the payload and read the saved result before you offer a retry.

#Messages from Lua

jsconst stop = Pocketbook.onMessage((data) => {
  if (data?.kind === 'hint') showHint(String(data.text));
});

Messages arrive only while the page is mounted. They are not stored.

#Leaving the page

The frame is destroyed when the player goes to another app or closes the book. Stop your listeners and timers:

jsconst stopContext = Pocketbook.onContext(applyColours);
const stopMessage = Pocketbook.onMessage(onMessage);
window.addEventListener('pagehide', () => { stopContext(); stopMessage(); }, { once: true });

#The frame

  • The frame may run scripts. Links that open other pages, pop-ups and navigation of the notebook are blocked.
  • The bridge accepts messages only from the notebook window, and the notebook accepts messages only from the mounted frame of your resource.
  • Use your own fonts and images from your resource; nothing has to come from the internet.
  • The page is drawn on the notebook's paper. Keep the background transparent and use the context colours so it fits every notebook colour.