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
fetchNuicalls to your own resource. - Anything that gives money, items or access must be checked on your server (
CustomAppAllowedplus your own rules): a page and its NUI callbacks run on the player's computer.
