External apps API

Overview#

Any resource on your server can add its own app to the phone. It shows up on the home screen, in the app drawer (Andromeda), in search, in multitasking and in the app store, with its own icon, and opens inside the phone as an app-sized iframe.

This is the equivalent of LB Phone's AddCustomApp / RemoveCustomApp / SendCustomAppMessage. An app built for LB is usually ported by replacing exports['lb-phone'] with exports.rarx_phone (see Differences with LB Phone). The client exports are also available as exports['lb-phone'].

Register the app#

From the client (recommended, same as LB)#

local ok, err = exports.rarx_phone:AddCustomApp({
    identifier = 'my_app',
    name = 'My app',
    description = 'Text shown in the App Store.',
    developer = 'My company',
    category = 'utilities',
    icon = 'https://cfx-nui-' .. GetCurrentResourceName() .. '/html/icon.png',
    ui = GetCurrentResourceName() .. '/html/index.html',
    defaultApp = false,
    fullscreen = false,
    background = '#101418',
    onOpen = function() end,
    onClose = function() end,
    onInstall = function() end,
    onUninstall = function() end,
    onMessage = function(data) end,
})

This registers the app for that player only. Since your client code runs on every player, in practice everyone gets it. Returns true or false, reason.

From the server#

local ok, err = exports.rarx_phone:AddCustomApp({
    identifier = 'my_app',
    name = 'My app',
    ui = 'my_resource/html/index.html',
    icon = 'nui://my_resource/html/icon.png',
    onOpen = function(src) end,
    onClose = function(src) end,
    onInstall = function(src) end,
    onUninstall = function(src) end,
    onMessage = function(src, data) end,
})

This registers the app for all players, including those who join later. Callbacks receive the player's source.

Fields#

Remove the app#

exports.rarx_phone:RemoveCustomApp('my_app')

List apps#

Messages from your resource to the page#

exports.rarx_phone:SendCustomAppMessage('my_app', { type = 'refresh' })
exports.rarx_phone:SendCustomAppMessage(src, 'my_app', { type = 'refresh' })
exports.rarx_phone:SendCustomAppMessage(-1, 'my_app', { type = 'refresh' })

The page receives the data unchanged as a window message event (same as LB), and also through RarxPhone.onMessage:

window.addEventListener('message', (e) => { if (e.data && e.data.type === 'refresh') reload() })
RarxPhone.onMessage((data) => { /* ... */ })

If the app is not open, the message is discarded (when the app opens, the page loads again and should request its state). While the page is still loading, messages are queued (up to 50) and delivered when it finishes.

From the page to your resource#

There are two ways, and you can use both.

1. Your own NUI callback (same as LB). The page lives at https://cfx-nui-my_resource/..., so it can call the RegisterNUICallback handlers of its own resource:

   LuaCopy

   RegisterNUICallback('save', function(data, cb) cb({ ok = true }) end)

   JavaScriptCopy

   const res = await RarxPhone.nui('save', { text })

   RarxPhone.nui(name, data) does fetch('https://my_resource/name') and returns the JSON. It goes straight to your resource; the phone is not involved.

2. Through the phone: RarxPhone.send(data) calls onMessage(data) of the registration (client) or onMessage(src, data) (server, if registered on the server). The local event rarx_phone:customApp is also fired. Maximum 16 KB; on the server, at most 40 events every 5 seconds per player.

Local events fired by the phone, if you prefer events over callbacks:

AddEventHandler('rarx_phone:customApp', function(identifier, action, data) end)

AddEventHandler('rarx_phone:customApp', function(src, identifier, action, data) end)

action is open, close, install, uninstall or message. These are local events (not network events), so a client cannot fake them towards the server.

Page SDK (sdk.js)#

<script src="https://cfx-nui-rarx_phone/ui/dist/sdk.js"></script>

The SDK defines window.RarxPhone. All functions return a promise. Without the SDK the page still works (it opens, receives messages and can use its NUI callbacks), but it gets no theme, dialogs or proper text input handling.

The pickers (pickImage, pickContact, pickGif, pickEmoji, pickColor, takePhoto) are sheets drawn by the phone on top of the app. Only one can be open at a time (otherwise err_busy), they do not time out (they wait until the player picks or closes) and they resolve with null if the app closes. When using postMessage directly without the SDK, the message type is the same name:

{ __rarxPhone: 1, id, type: 'pickColor', payload: { value: '#ff0000' } }

Errors: the promise rejects with Error(code): err_not_allowed (action not in the list), err_busy (an app dialog is already open), err_rate_limited, err_app_unknown, err_too_big, err_timeout, err_no_phone (page opened outside the phone).

Settings object#

Returned by ready, getSettings and onSettings:

{
  "appId": "my_app", "resource": "my_resource",
  "os": "ios", "theme": "dark", "language": "en",
  "accent": "#c9564f", "accentRgb": "201, 86, 79",
  "model": "phone", "foldable": false, "wide": false,
  "fullscreen": false, "safeTop": 0, "safeBottom": 0,
  "currency": "$", "twelveHour": false, "streamerMode": false,
  "phoneNumber": "551234", "params": {}
}

The SDK also sets on <html>: data-os="ios|android", data-theme="light|dark", lang, and the CSS variables --phone-safe-top, --phone-safe-bottom (0 when not fullscreen), --phone-accent and --phone-accent-rgb. This lets the page look like iFruitOS or Andromeda and follow dark mode:

:root { --bg: #f2f2f7; --text: #111 }
:root[data-theme='dark'] { --bg: #000; --text: #f5f5f7 }
body { padding-top: var(--phone-safe-top, 0px); padding-bottom: var(--phone-safe-bottom, 0px) }

Behaviour inside the phone#

• Home, drawer, search and multitasking: installed external apps appear after the built-in ones. Their order can be changed in edit mode like any other app.
• app store: every external app is listed with its description, category and developer. Installing or uninstalling an external app is saved in the player's settings (settings.external.installed), not in rarx_phone_apps. defaultApp apps are always installed.
• Gestures: the island / punch-hole, the status bar and the home gesture bar sit above the iframe; swiping the bar closes the app like any other. The iFruitOS edge "back" gesture does not exist inside the iframe: the page handles its own navigation.
• On close the iframe is unloaded; when the app opens again the page reloads (onOpen in Lua, ready in the SDK).
• Game key blocking: with the SDK, focusing an editable field enables setTyping and leaving it releases the keys. Without the SDK, keys are blocked while focus is inside the iframe until it returns to the phone.

Security#

• Only server resources can register apps (the exports are not reachable by players). Each app stores the resource that registered it, and only that resource can remove it or send it messages.
• The page can only come from https://cfx-nui-<resource> (or nui://<resource>) of an existing resource. This is validated in Lua and again in the UI.
• The iframe uses sandbox="allow-scripts allow-same-origin allow-forms": it cannot navigate the phone, open windows or show native dialogs.
• The phone only handles messages whose event.source is that app's iframe, and only the SDK actions listed above (with size and rate limits). Anything else returns err_not_allowed. The iframe cannot call the phone's RPCs through the bridge.
• The phone ignores { action, data } messages coming from any child iframe (at any depth), so an external app cannot impersonate messages from Lua.

Differences with LB Phone#

To port an LB app: replace exports['lb-phone'] with exports.rarx_phone, GetResourceState('lb-phone') with 'rarx_phone', and if it reads globalThis.settings.display.theme, use RarxPhone.ready.then((s) => s.theme) with the SDK.

Minimal example#

A complete resource called rarx_ejemplo_app. Start it after rarx_phone, open the app store on the phone and install the app. The /ejemploapp <text> command sends a message to the open app.

fx_version 'cerulean'
game 'gta5'
lua54 'yes'

name 'rarx_ejemplo_app'

client_script 'client.lua'

files {
    'html/index.html',
    'html/app.js',
    'html/style.css',
    'html/icon.svg',
}

dependency 'rarx_phone'

local APP = 'ejemplo'
local RESOURCE = GetCurrentResourceName()

local function register()
    if GetResourceState('rarx_phone') ~= 'started' then return end
    local ok, err = exports.rarx_phone:AddCustomApp({
        identifier = APP,
        name = 'Example',
        description = 'Example app for the rarx_phone external apps API.',
        developer = 'Rarx Network',
        category = 'utilities',
        icon = ('https://cfx-nui-%s/html/icon.svg'):format(RESOURCE),
        ui = RESOURCE .. '/html/index.html',
        onOpen = function()
            print('[example] app opened')
        end,
        onClose = function()
            print('[example] app closed')
        end,
        onMessage = function(data)
            if type(data) == 'table' and data.tipo == 'ping' then
                exports.rarx_phone:SendCustomAppMessage(APP, { tipo = 'pong', hora = ('%02d:%02d'):format(GetClockHours(), GetClockMinutes()) })
            end
        end,
    })
    if not ok and err ~= 'already_exists' then
        print(('[example] could not register the app: %s'):format(tostring(err)))
    end
end

AddEventHandler('onClientResourceStart', function(res)
    if res == 'rarx_phone' or res == RESOURCE then
        SetTimeout(500, register)
    end
end)

RegisterNUICallback('saludo', function(data, cb)
    local name = type(data) == 'table' and type(data.nombre) == 'string' and data.nombre:sub(1, 30) or 'unknown'
    cb({ texto = ('Hello, %s. This is the Lua client answering.'):format(name), id = GetPlayerServerId(PlayerId()) })
end)

RegisterCommand('ejemploapp', function(_, args)
    exports.rarx_phone:SendCustomAppMessage(APP, { tipo = 'aviso', texto = table.concat(args, ' ') })
end, false)

<script src="https://cfx-nui-rarx_phone/ui/dist/sdk.js"></script>
<input id="nombre" type="text">
<button id="saludar">Say hello</button>
<script>
  RarxPhone.ready.then((s) => console.log(s.os, s.theme))
  RarxPhone.onMessage((d) => console.log('from the resource', d))
  document.querySelector('#saludar').onclick = async () => {
    const r = await RarxPhone.nui('saludo', { nombre: document.querySelector('#nombre').value })
    RarxPhone.toast(r.texto, 'success')
  }
</script>