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 AddCustomApp client export from your resource. This is the usual way.
  • Declare it in Config.CustomApps in configs/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 ui address must be https://. Resource pages are, as https://cfx-nui-<resource>/. Anything else opens as a blank page.
  • Files served from your resource must be listed under files { } in its fxmanifest.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 AddCustomApp again with the same id updates the app.
  • When your resource stops, its apps are removed.
  • RemoveCustomApp(id) removes an app by hand. It returns false, '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:opened and closed client events fire for them.
  • SendCustomAppMessage(identifier, data) reaches their page, from any resource.
  • The page's nuiCallback messages are relayed as <resource>:phoneApp:event only when the entry names its resource with resource = 'my-menu'. Without it there is no resource to deliver to and the page's call is answered not_found.
  • Nothing removes them when another resource stops.
  • An entry with a bad id or ui is skipped. The reason is printed when debug output is on.
  • A price here is charged as written. AppPriceMax does 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.