Custom apps
Custom app performance
How to keep a custom app idle while it is not on screen, and other advice for app pages and their Lua side.
#Why it matters
A custom app is a web page that keeps running inside the player's game. The iframe stays loaded while the app is in the app switcher, and a keepOpen app stays loaded until it is removed. Whatever the page does in the background, it does on every player's client.
#Stop work when hidden
The phone tells the page when it is in front with the visibility message. visible is true only while your app is in front and the phone is open and unlocked.
jslet timer = null;
window.addEventListener('message', ({ data: msg }) => {
if (msg?.type !== 'fx-phone' || msg.action !== 'visibility') return;
if (msg.visible) {
timer ??= setInterval(tick, 1000);
} else {
clearInterval(timer);
timer = null;
}
});
- Stop timers and animations when
visibilityreportsfalse. - Start them again when it reports
true.
#Push, do not poll
Do not poll your resource from the page. Send updates from Lua when something changes:
luaexports['fx-phone']:SendCustomAppMessage('garage', { action = 'vehicles', list = vehicles })
On the Lua side, use fx-phone:customApp:opened and fx-phone:customApp:closed to start and stop any work that only matters while the app is in front.
#keepOpen
Use keepOpen = true only for apps that must keep running in the background, such as a radio or a timer. A keepOpen page is never unloaded, so it must pause its own work when visibility is false.
#Dynamic Island updates
Every tray update is a message to the phone's UI.
- Change only what changed.
UpdateMusicTray(id, 'playing', false)instead of showing the whole tray again. - Send a moving position at most once a second.
- Send it only while the phone is open.
fx-phone:phoneToggledreports the open state.
lualocal phoneOpen = false
AddEventHandler('fx-phone:phoneToggled', function(open) phoneOpen = open end)
CreateThread(function()
while true do
Wait(1000)
if track and phoneOpen and MyPlayer.IsPlaying() then
exports['fx-phone']:UpdateMusicTray('myradio', 'position', position())
end
end
end)
Update a live activity from your own distance or progress check, not every frame.
#Page size
- Keep the page light. A single screen does not need a large framework.
- Size images for a 390 px wide screen.
#Layout and input
- Insets. Pad your page with
insetTopandinsetBottom. Headers under the status bar and buttons under the home indicator cannot be tapped reliably. - Theme. Read
themefrom the query string for the first paint, then follow thereadyandthememessages. The phone uses#f2f2f7and#000000backgrounds, and#ffffffand#1c1c1ecards. - Text input. Always pair
setFocuswithfocused: trueon focus withfocused: falseon blur. - Opening with data.
OpenApp(id, data)reaches your page as anopenmessage afterready, so a deep link works even when the page was not loaded yet.
#Registration
- Register once when your resource starts and once on
fx-phone:client:phoneLoaded. Do not register in a loop. - Calling
AddCustomAppagain with the same id updates the app; it does not add a second one.
#Server side
Anything your page sends to your resource comes from the player's client. Validate it on the server, and keep stored values small: app data is limited to 16 KB per key.