Suty Phone

Custom apps

Custom apps

Any resource can add its own app to the phone. The app shows up in the Store (section From this server), players download it like any other app, and it opens full screen inside the phone. Its page is your own HTML/JS (any framework), loaded from your resource.

The quickest start is the example resource suty-phone-app-template, in suty-phone/install/suty-phone-app-template: copy it into your resources, rename the folder, change the app id and texts in client.lua, and build your page in ui/. The same guide is in suty-phone/install/custom-apps.md.


1. Add the app (client)

CreateThread(function()
    while GetResourceState('suty-phone') ~= 'started' do Wait(500) end
    local ok, reason = exports['suty-phone']:AddCustomApp({
        identifier = 'my-app',                                   -- required, unique
        name = 'My App',                                         -- required
        ui = GetCurrentResourceName() .. '/ui/index.html',       -- required (or a full https:// address)
        icon = 'https://cfx-nui-' .. GetCurrentResourceName() .. '/ui/icon.png',
    })
end)

-- The phone restarted: add it again.
AddEventHandler('onClientResourceStart', function(resource)
    if resource == 'suty-phone' then --[[ same AddCustomApp call ]] end
end)

AddCustomApp returns true, or false, reason (invalid_identifier, identifier_taken, invalid_ui, too_many_apps, disabled). Calling it again with the same id updates the app. When your resource stops, its apps leave the phone and the Store by themselves.

Field Type
identifier string Letters, numbers, - and _, up to 32. Not one of the phone's own app ids.
name string Name under the icon (up to 30 characters).
ui string "<resource>/<path>" (served as https://cfx-nui-<resource>/<path>) or a full https:// address.
icon string Square picture (PNG / SVG / WebP), same address forms as ui.
subtitle string Line under the name in the Store.
description string Store page text.
developer, category, version, whatsNew string Store page details.
size number Size in kB shown in the Store (bigger apps take longer to download).
age, rating number Store page details (age 0-18, rating 0-5).
images string[] Up to 6 screenshots for the Store page.
background { from, to } Tile colours ('#rrggbb') shown while the icon loads.
preinstalled boolean Already on every phone; players can still delete it.
onOpen, onClose function Called when the app comes on screen / leaves it.
onUse function An app with no ui: tapping the icon only runs this.

2. Rules the server decides (server, optional)

Price and job access are never taken from the client. Set them from your server script, or in the phone's config.lua (Config.CustomApps.apps, which wins over the resource):

-- server.lua of your resource
exports['suty-phone']:AddCustomApp({
    identifier = 'my-app',
    name = 'My App',
    price = 500,              -- bought once per phone number, taken from the bank
    jobs = { 'police' },      -- only these jobs see, download and open it
    preinstalled = false,
})
-- suty-phone/config.lua
Config.CustomApps = {
    enabled = true,
    max = 40,
    apps = {
        ['my-app'] = { price = 500, jobs = { 'police', 'sheriff' }, preinstalled = true, hidden = false },
    },
}

hidden = true turns an app off without stopping its resource.

To check a player before serving your app's data:

local allowed, reason = exports['suty-phone']:CustomAppAllowed(source, 'my-app')
-- reason: 'locked' (phone away or locked), 'notinstalled', 'job'

3. Your page

Include the SDK before your own scripts (copy ui/sdk.js from the template):

<script src="sdk.js"></script>

Then window.SutyPhone is there:

const ctx = await SutyPhone.ready()        // { appId, resource, name, theme, language, intent, safeArea, screen }

await SutyPhone.fetchNui('myCallback', { a: 1 })   // your resource's RegisterNUICallback
SutyPhone.onMessage((data) => {})                  // exports['suty-phone']:SendCustomAppMessage
SutyPhone.on('theme', (theme) => {})               // 'light' | 'dark'
SutyPhone.on('language', (lang) => {})             // 'es' | 'en'
SutyPhone.on('intent', (data) => {})               // OpenCustomApp(id, data) while it is open

SutyPhone.notify({ title: 'My App', content: 'Hello' })
await SutyPhone.alert({ title: 'Title', message: 'Text', buttons: [{ label: 'OK' }] })   // -> index
await SutyPhone.confirm({ title: 'Sure?', confirm: 'Yes', cancel: 'No', destructive: false })  // -> boolean
await SutyPhone.prompt({ title: 'Your name', placeholder: 'Name' })                      // -> text | null
await SutyPhone.pickPhoto()                 // -> { url, width, height } | null  ({ camera: true } opens the Camera)
SutyPhone.call('5551234567')                // opens the Phone app calling that number
SutyPhone.sendMessage('5551234567')         // opens that Messages thread
SutyPhone.openApp('maps')                   // any app of the phone
SutyPhone.close()                           // back to the home screen

The page fills the whole screen (393 × 852). The phone sets on <html>:

  • data-theme="light" or "dark" (follows the phone, live);
  • --suty-safe-top / --suty-safe-bottom: the strips under the status bar and the home bar.
main { padding: var(--suty-safe-top) 16px var(--suty-safe-bottom); }
:root[data-theme='dark'] { --bg: #000; }

Typing in your inputs works like in the phone's own apps (keys go to the field, Escape leaves it, a second Escape puts the phone away).

4. Lua exports (client)

Export
AddCustomApp(def) / RemoveCustomApp(id) Add / remove an app of this resource.
SendCustomAppMessage(id, data) Data for the page (SutyPhone.onMessage, or window message events).
OpenCustomApp(id, data?) Takes the phone out and opens the app (data arrives as the intent).
CloseCustomApp(id?) Closes it if it is on screen.
IsCustomAppOpen(id?) The app is on screen right now.
SendCustomAppNotification(id, { title, content }) A notification of the app (only on phones that have it).

5. Apps made for other phones

Custom apps written for lb-phone run without changes while Config.Compat['lb-phone'] is on and lb-phone itself is not started: exports['lb-phone']:AddCustomApp, RemoveCustomApp, SendCustomAppMessage, SendNotification and their pages' globals (fetchNui, onNuiEvent, SetPopUp, SetContextMenu, SelectGallery, SendNotification, GetSettings, OnSettingsChange, componentsLoaded) are answered by this phone. Pickers this phone does not have (GIF, emoji, colour, contact) answer null.

Notes

  • Only the screen in use runs the page. Nearby players looking at the phone see the app's icon and name, never the page itself.
  • Keep fetchNui calls to your own resource.
  • Anything that gives money, items or access must be checked on your server (CustomAppAllowed plus your own rules): a page and its NUI callbacks run on the player's computer.

Merry Christmas.

From Suty.