Custom apps

Custom apps overview

How another resource adds its own app to the notebook: the three parts, the settings, the limits and the rules an app must follow.

All 29 built-in apps ship inside fx-pocketbook. Another resource can add its own app to the notebook's launcher without editing the core. The app lives in that resource: its page, its server code and its data.

This is the Pocketbook extension API, version 1. It is not a drop-in copy of another phone's API.

#The three parts

Part Where What it does
Launcher entry client, [AddCustomApp](/phone/docs/pocketbook/exports/client/custom-apps) Puts the app's name and icon in the launcher and says which page to load
Page browser, [pocketbook.js](/phone/docs/pocketbook/custom-apps/browser-bridge) Your HTML, shown inside the notebook. It reads the theme and signal and sends requests.
Server actions server, [RegisterApplication](/phone/docs/pocketbook/exports/server/custom-apps) The functions that answer the page's requests

A request travels like this:

  1. The page calls Pocketbook.request('balance', { ... }).
  2. The notebook sends it to the server as the action balance of your app.
  3. The server checks the player (character, notebook item, app installed) and calls your function with source, character and the payload.
  4. Your function returns { ok = true, ... } or { ok = false, error = '...' }. The page gets that table.

A full working resource is in Getting started.

#Settings

config.lua:

luaConfig.CustomApps = { Enabled = true, Maximum = 24, RequireInstall = true }
Key Default What it does
Enabled true Custom apps on or off. Off: AddCustomApp and RegisterApplication refuse every app.
Maximum 24 Custom apps that may be registered at the same time.
RequireInstall true The player must install the app from the App Store before its server actions work. It is listed there as a custom app. false: it works without installing.

To give your app its own log webhook, add PocketServerConfig.Apps['<your id>'].Logs in the core's config_server.lua, in the same shape as a built-in app's config_server.lua. Never put a webhook in a client or shared file.

#Your resource

luafx_version 'cerulean'
game 'rdr3'
rdr3_warning 'I acknowledge that this is a prerelease build of RedM, and I am aware my resources *will* become incompatible once RedM ships.'

dependency 'fx-pocketbook'
client_script 'client.lua'
server_script 'server.lua'
files { 'ui/index.html', 'ui/app.js', 'ui/style.css', 'ui/pocketbook.js', 'ui/icon.png' }
  • List every file the page loads under files.
  • Do not set a ui_page for the app. The notebook makes the frame and owns the focus.
  • Copy sdk/pocketbook.js from fx-pocketbook into your page folder and load it before your own script. It needs nothing from the internet.
  • Start your resource after fx-pocketbook.

#Restarts

  • When your resource stops, its launcher entry, page and server actions are removed.
  • When fx-pocketbook restarts, it forgets every custom app. Register again:
  • client: on your own resource start and on [fx-pocketbook:ready](/phone/docs/pocketbook/events/client-events),
  • server: on onResourceStart for your resource and for fx-pocketbook.
  • Registering an id that is already registered returns false and keeps the first one. Never remove another resource's app when your registration fails.

#Limits

What Limit
App id Lowercase letters, numbers and _, starts with a letter, up to 32 characters, not a built-in id
App name Up to 64 bytes
Server actions per app 1 to 32; names of letters and numbers, starting with a letter, up to 32 characters
Payload, result and messages 32 KiB as JSON, 8 levels deep, 128 keys per table, strings up to 16384 bytes
Requests waiting in one page 4
Request timeout in the page 15 seconds
Requests per player One at a time for the whole notebook, at least 250 ms apart

#Rules your app must follow

  1. Decide everything on the server. source and character come from the core; never take a player id, character id, price, job or permission from the payload.
  2. Check your own rules (ownership, job, grade) in every action. Registering an app gives it no money or inventory rights.
  3. After an awaited query, and right before a change, call [ValidateApplicationPlayer](/phone/docs/pocketbook/exports/server/custom-apps) and your own checks again.
  4. Make writes safe to repeat: send a stable nonce from the page and an expected revision. A timeout does not mean the change failed. Reuse the same nonce and read the saved result before you offer a retry, above all for money and items.
  5. Call [CanUseOnline](/phone/docs/pocketbook/exports/server/notifications-and-signal) when an action needs a telegraph line. The core does not check it for you.
  6. Put text on the page with textContent or escaped templates, not raw HTML.
  7. Wait for the first onContext before you send requests. Theme and signal can change while the page is open; update colours without resetting a form.
  8. The page is destroyed when the player leaves the app. Remove your listeners and timers, keep data on the server, and do not play world audio inside the page.
  9. Filter customAppOpened and customAppClosed by your own id.
  10. Test: players without permission, copied ids, two saves at once, a character switch or disconnect, the notebook item removed, a resource restart during an action, a lost response, no signal and a small screen.