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);
actionis 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.payloadis 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.