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 visibility reports false.
  • 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:phoneToggled reports 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 insetTop and insetBottom. Headers under the status bar and buttons under the home indicator cannot be tapped reliably.
  • Theme. Read theme from the query string for the first paint, then follow the ready and theme messages. The phone uses #f2f2f7 and #000000 backgrounds, and #ffffff and #1c1c1e cards.
  • Text input. Always pair setFocus with focused: true on focus with focused: false on blur.
  • Opening with data. OpenApp(id, data) reaches your page as an open message after ready, 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 AddCustomApp again 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.