Custom apps
Custom apps overview
What a custom app is, how it is registered and which definition fields FX Phone reads.
#What a custom app is
A custom app is a web page from your own resource that FX Phone shows inside the phone in an iframe. It gets its own home screen icon and its own App Store page. The page talks to the phone with postMessage and to your resource with normal NUI callbacks.
There are two ways to add one:
- Call the
AddCustomAppclient export from your resource. This is the usual way. - Declare it in
Config.CustomAppsinconfigs/config_apps.lua. This needs no Lua and suits a page hosted elsewhere.
The pages in this section:
- Getting started: a complete three-file app.
- App API: the iframe, every message in both directions, pickers, dialogs and focus.
- Performance: what to do so the app costs nothing while idle.
The Lua exports used here are documented in Client exports: Custom apps.
#Registering an app
Call AddCustomApp on the client. FX Phone accepts the lb-phone and the cylex_phone definition shapes.
lb-phone shape:
luaexports['fx-phone']:AddCustomApp({
identifier = 'garage',
name = 'Garage',
description = 'Your vehicles, wherever you are.',
developer = 'My Server',
defaultApp = true,
size = 24000,
price = 0,
category = 'utilities',
jobs = nil,
images = { 'my-garage/html/shots/1.webp', 'my-garage/html/shots/2.webp' },
ui = 'my-garage/html/index.html',
icon = 'my-garage/html/icon.png',
})
cylex_phone shape:
luaexports['fx-phone']:AddCustomApp({
appId = 'garage',
label = 'Garage',
ui = 'https://cfx-nui-my-garage/html/index.html',
icon = 'https://cfx-nui-my-garage/html/icon.png',
defaultInstalled = true,
})
AddCustomApp returns true, or false and an error code:
| Error | Meaning |
|---|---|
invalid |
the definition is not a table |
invalid_id |
the id is missing, longer than 40 characters, or has characters other than letters, digits, _ and - |
invalid_ui |
ui is missing or cannot be resolved to an address |
reserved_id |
the id belongs to one of the phone's own apps |
#Definition fields
| Field | Also read as | Meaning |
|---|---|---|
identifier |
appId, id |
Letters, digits, _ and -, up to 40 characters. Must not be the id of a core app |
name |
label |
Name under the icon, up to 40 characters. Defaults to the id |
ui |
The page. Required. See the path rules below | |
icon |
Icon image, same path rules as ui |
|
description |
App Store text, up to 500 characters | |
developer |
App Store developer line, up to 60 characters. Defaults to the resource name | |
defaultApp |
defaultInstalled |
Installed on every phone. Otherwise players install it from the App Store |
category |
App Store category. Defaults to other |
|
images |
App Store screenshots, same path rules as ui |
|
size |
App Store size line, in KB | |
price |
App Store price, taken from the bank on the first install. Reinstalling is free. Capped at Config.Limits.AppPriceMax |
|
jobs |
List of job names. Only those jobs see the app | |
keepOpen |
The page stays loaded after the app is closed or leaves the app switcher, until the app is removed. It receives visibility messages instead of being unloaded |
|
landscape |
The app supports landscape. It turns sideways when the player rotates the phone in Control Centre or a script calls SetLandscape(true) |
|
fixBlur |
Accepted for lb-phone compatibility. No effect |
#Paths for ui, icon and images
| You write | FX Phone loads |
|---|---|
https://example.com/app/ |
as written |
nui://my-garage/html/index.html |
https://cfx-nui-my-garage/html/index.html |
my-garage/html/index.html |
https://cfx-nui-my-garage/html/index.html |
index.html (no slash) |
https://cfx-nui-<calling resource>/index.html |
The first part before a slash is always read as a resource name. Write my-garage/html/index.html, not html/index.html.
Other rules from the code:
- A path is at most 512 characters and must not contain whitespace, quotes, angle brackets, backslashes or backticks.
- The final
uiaddress must behttps://. Resource pages are, ashttps://cfx-nui-<resource>/. Anything else opens as a blank page. - Files served from your resource must be listed under
files { }in itsfxmanifest.lua.
#When to register
The registration lives in FX Phone's client state. Register when your resource starts, and again whenever the phone loads. The second call also covers an FX Phone restart.
lualocal function register()
exports['fx-phone']:AddCustomApp({ ... })
end
AddEventHandler('fx-phone:client:phoneLoaded', register)
CreateThread(function()
if GetResourceState('fx-phone') == 'started' then register() end
end)
- Calling
AddCustomAppagain with the same id updates the app. - When your resource stops, its apps are removed.
RemoveCustomApp(id)removes an app by hand. It returnsfalse, 'not_found'for an unknown id.
#Opened and closed events
FX Phone fires two client events with the app id when a custom app comes to the front or leaves it:
luaAddEventHandler('fx-phone:customApp:opened', function(appId) end)
AddEventHandler('fx-phone:customApp:closed', function(appId) end)
The same events are also fired as cylex_phone:customApp:opened and cylex_phone:customApp:closed.
#Config.CustomApps
Apps that need no Lua can be declared in configs/config_apps.lua with the same fields:
luaConfig.CustomApps = {
{
identifier = 'wiki',
name = 'City Wiki',
description = 'Rules, laws and maps.',
ui = 'https://wiki.example.com/phone',
icon = 'https://wiki.example.com/icon.png',
defaultApp = true,
category = 'utilities',
},
{
identifier = 'menu',
name = 'Burger Shot',
ui = 'my-menu/html/index.html',
icon = 'my-menu/html/icon.png',
jobs = { 'burgershot' },
resource = 'my-menu',
},
}
These apps go through the same registry as apps added with AddCustomApp:
- The
fx-phone:customApp:openedandclosedclient events fire for them. SendCustomAppMessage(identifier, data)reaches their page, from any resource.- The page's
nuiCallbackmessages are relayed as<resource>:phoneApp:eventonly when the entry names its resource withresource = 'my-menu'. Without it there is no resource to deliver to and the page's call is answerednot_found. - Nothing removes them when another resource stops.
- An entry with a bad
idoruiis skipped. The reason is printed when debug output is on. - A
pricehere is charged as written.AppPriceMaxdoes not apply. - The admin tablet can switch these apps off like core apps.
Fetching your own resource's NUI callbacks from the page works either way.
#Apps written for lb-phone or cylex_phone
An app written for lb-phone or cylex_phone usually works after changing exports['lb-phone'] or exports['cylex_phone'] to exports['fx-phone'] in its Lua. Both definition shapes, the iframe messages and the lb-phone componentsLoaded signal are understood.
When the app cannot be edited, FX Phone ships shim resources that answer under the other phone's name. See LB Phone compatibility and Cylex Phone compatibility.