Custom apps

Boomer Phone can display your resource's web UI inside an iframe. Registered apps appear on the home screen and keep the phone's Exit footer button.

Start with the Boomer app template. It provides a separate FiveM resource that you can copy and adapt. Use a Boomer Phone version that includes the custom-app exports and config/config.customApps.lua.

Call the exports from a client script. Keep your HTML, scripts and images in your own resource and list them in its manifest's files section. An embedded app does not need its own ui_page.

lua

-- fxmanifest.lua
fx_version 'cerulean'
game 'gta5'

client_script 'client.lua'
files {
    'html/index.html',
    'html/icon.png',
}
dependency 'yboomer-phone'

lua

-- client.lua
local appKey = 'my-boomer-app'

local function registerApp()
    local resource = GetCurrentResourceName()
    local ok, err = exports['yboomer-phone']:AddCustomApp({
        key = appKey,
        name = 'My App',
        ui = ('https://cfx-nui-%s/html/index.html'):format(resource),
        icon = ('https://cfx-nui-%s/html/icon.png'):format(resource),
        closeOnPhoneHide = true,
    })

    if not ok then
        print(('Could not register %s: %s'):format(appKey, err))
    end
end

CreateThread(registerApp)

AddEventHandler('onResourceStart', function(resource)
    if resource == 'yboomer-phone' then
        registerApp()
    end
end)

Start yboomer-phone before the app resource in server.cfg. The manifest dependency also enforces that order. When your resource stops, Boomer removes the apps it registered. Registering the same key again replaces the entry, keeps its position, and makes a hidden app visible again.

You can also add an entry to Config.CustomApps in yboomer-phone/config/config.customApps.lua. Both methods accept the same app fields. Choose one registration method for each app key.

lua

Config.CustomApps = {
    {
        key = 'my-boomer-app',
        name = 'My App',
        ui = 'https://cfx-nui-my-app/html/index.html',
        icon = 'https://cfx-nui-my-app/html/icon.png',
        closeOnPhoneHide = true,
    },
}

In this file, GetCurrentResourceName() refers to yboomer-phone, so use the app resource's actual name in its URLs. Ensure that resource is running and its files are included in its manifest. Config entries reload when Boomer restarts; they are not automatically removed when an external UI resource stops. Use export registration when you need that automatic cleanup.

Field	Type	Behavior
`key`	string, required	Unique identifier: 1–64 letters, digits, `_` or `-`. Built-in app and route keys are reserved.
`name`	string, required	Non-empty display name, up to 64 bytes.
`ui`	string, required	UI URL starting with `https://`, `http://` or `nui://`. Up to 2048 bytes, without whitespace. Prefer `https://cfx-nui-<resource>/<path>` for local resource files.
`icon`	string or table	Optional URL with the same URL rules as `ui`. A table selects `boomer`, then `yos`, then `humanoid`. If omitted, the launcher shows the first letter of the name.
`description`	string	Optional description, up to 512 bytes.
`closeOnPhoneHide`	boolean	If `true`, return to the home screen when the phone is hidden. Default: `false`.
`allowedJobs`	string array	Only listed jobs can access the app. An empty array allows no jobs. The app stays unavailable until the player's job is known.
`disabledJobs`	string array	Listed jobs cannot access the app. A blocked job takes precedence over `allowedJobs`.
`adminOnly`	boolean	Requires the player to pass the framework's `IsPlayerAdmin` check. Default: `false`.
`internal`	boolean	Hides the launcher icon; eligible players can still open the app through `OpenCustomApp`. Default: `false`.
`game`	boolean	Accepted for YSeries compatibility. Boomer has no app-store game category.
`defaultApp`, `storeHidden`	boolean	Accepted for YSeries compatibility; neither changes Boomer behavior because it has no app store.

Unknown fields are discarded. Invalid fields reject the whole registration: AddCustomApp returns false, err and prints a warning in the client console. Optional boolean fields must be booleans; job lists must be arrays of non-empty job names.

adminOnly uses IsPlayerAdmin in yboomer-phone/server/custom/framework/ (the admin ACE by default). Job updates are handled automatically for QBox, QBCore and ESX. After changing an ACE or updating job data through a custom integration, call:

lua

exports['yboomer-phone']:ReevaluateCustomAppsForJob()

Job and admin rules control launcher visibility and the open/message exports. Validate permissions again in your own server events and callbacks before returning restricted data or changing server state.

lua

exports['yboomer-phone']:ToggleOpen(true)       -- Show the phone if needed.
local opened = exports['yboomer-phone']:OpenCustomApp('my-boomer-app')

exports['yboomer-phone']:HideCustomApp('my-boomer-app')
exports['yboomer-phone']:CloseApp()
exports['yboomer-phone']:RemoveCustomApp('my-boomer-app')

OpenCustomApp selects the app; it does not show a hidden phone. It returns false for unknown apps or players who fail the job/admin rules. HideCustomApp removes the launcher icon but still permits eligible players to use OpenCustomApp. Call AddCustomApp again to unhide it. RemoveCustomApp unregisters it completely. Hiding and removing return false if the key does not exist.

CloseApp returns to the home screen. The client event yboomer:custom-app:closing identifies an app when its mounted UI closes, while the app is still registered:

lua

AddEventHandler('yboomer:custom-app:closing', function(appKey)
    if appKey == 'my-boomer-app' then
        -- Stop app-specific effects or release local state.
    end
end)

This event applies to apps regardless of closeOnPhoneHide. Do not depend on it for resource-stop cleanup: the registry entry may already have been removed. Handle your own resource lifecycle separately.

Use SendAppMessage from client Lua. The app receives the payload as event.data through the browser's message event:

lua

local accepted = exports['yboomer-phone']:SendAppMessage('my-boomer-app', {
    action = 'my-app:update',
    data = { balance = 250 },
})

window.addEventListener('message', (event) => {
    if (event.source !== window.parent) return;

    if (event.data?.action === 'my-app:update') {
        document.querySelector('#balance').textContent = event.data.data.balance;
    }
});

// Install your message handlers before announcing readiness.
window.parent.postMessage({ action: 'nui:ready' }, '*');

Messages wait until the iframe announces nui:ready. For apps that omit the handshake, the bridge starts delivering messages 100 ms after iframe load. Send readiness only after your app can process messages. Up to 100 messages are queued per app; additional messages discard the oldest. A true return means the phone accepted the payload, not that the iframe has received or processed it.

Your app's web page calls its own resource, not yboomer-phone. Register the callback in the client script of the resource that serves your app:

lua

RegisterNUICallback('getGreeting', function(_, cb)
    cb({ message = 'Hello from Lua' })
end)

For an app loaded from https://cfx-nui-<resource>/html/index.html, derive the callback resource from the iframe URL:

const appResource = window.location.hostname.replace(/^cfx-nui-/, '');

async function getGreeting() {
    const response = await fetch(`https://${appResource}/getGreeting`, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json; charset=UTF-8' },
        body: JSON.stringify({}),
    });

    return response.json();
}

Always call cb in your Lua handler so the request completes. If you host the UI remotely, supply your FiveM resource name explicitly instead of deriving it from the remote hostname.

Build for the small phone screen and keypad navigation. The parent forwards keys to the iframe in this format:

window.addEventListener('message', (event) => {
    if (event.source !== window.parent) return;
    if (event.data?.action !== 'boomer:key') return;

    const key = event.data.data.key;
    if (key === 'up') moveSelection(-1);
    if (key === 'down') moveSelection(1);
    if (key === 'enter') activateSelection();
});

Supported key names are up, down, left, right, enter, opt, green, 0–9, * and #. Physical right Shift maps to opt. Backspace and the phone's Exit button return to the home screen; Backspace is not forwarded as an app key. Key forwarding pauses during calls.

Keep keyboard focus in the parent phone when using boomer:key. Focusing an input or clicking inside the iframe moves physical keyboard events into that iframe, so the parent cannot forward those events or handle physical Backspace. Avoid autofocus for keypad-driven apps. The phone's visible Exit control remains outside your app.

The registration and messaging export names match YSeries. Change the resource name in calls from yseries to yboomer-phone, update the closing event to yboomer:custom-app:closing, and adapt the UI to Boomer's keypad and smaller screen.

Boomer selects an icon table's boomer URL before yos or humanoid. It validates registration fields and reserves built-in keys. It removes export-registered apps when their registering resource stops. There is no installation flow or app store: registered, eligible apps appear immediately unless hidden or internal.

See the client export reference for all custom-app signatures.

Custom apps

Register an app from your resource

Register an app in the phone config

App fields

Open, hide, close and remove

Send messages to the UI

Call your resource's Lua callbacks

Handle the Boomer keypad

Port a YSeries app

On this page