Custom apps (SDK)

How another FiveM resource adds an app, widgets, notifications, and deep links to NovaOS. The release ships two complete SDK resources, each as its own zip and both at version 1.0.1: nova_example_app, a small working example, and the Browser add-on (nova_browser), a larger one that also uses mobile data and per-phone storage. The example app is a how-to rather than a feature, so it ships unencrypted (its fxmanifest.lua lists '*.lua' under escrow_ignore): read it and copy from it.

• How external apps work
• Registering an app
• The app page and the SDK
• Mobile data and app storage
• Permissions
• Notification channels
• Deep links
• Widgets
• Server exports reference
• Events
• Browser add-on: in-game sites
• Security model
• Icons

How external apps work#

your resource (server)                wd_phone (server)
  RegisterApp{ id, ui, permissions } ──► registry (memory; cleared when your resource stops)
                                          │ broadcast to every client
                                          ▼
player's phone (NUI) ── Nova Store ──► install / uninstall / update (phone_installed_apps)
  │
  └─ opens <iframe sandbox src="https://cfx-nui-<your_resource>/<ui>">
        │  window.postMessage  ◄──►  NovaSDK (sdk/nova-sdk.js)
        │                            origin + source checked on every message
        └─ fetch('https://<your_resource>/<callback>')  ──►  your client.lua NUI callbacks

• Your UI is a page served by your own resource. It runs in a sandboxed iframe (allow-scripts allow-same-origin allow-forms) and cannot reach the phone's DOM, stores, or NUI callbacks.
• Your UI talks to your own client scripts with normal NUI callbacks (https://<your_resource>/<name>), and to NovaOS only through the SDK.
• Install state, permission grants, notification-channel preferences and app storage are per phone and persist across restarts. Your app definition does not persist: register it every time your resource (or Wolfden Phone) starts.

Registering an app#

-- server.lua in your resource
local function register()
    local ok, reason = exports.wd_phone:RegisterApp({
        id = 'novanews',                 -- letter first, then letters/digits/_ (2-32)
        label = 'Nova News',             -- 24 chars max
        icon = 'newspaper',              -- a registered icon name (see Icons)
        color = '#e5484d',
        version = '1.1.0',               -- MAJOR.MINOR.PATCH; raise it to offer an update
        category = 'news',               -- Nova Store grouping
        developer = 'Nova Example Co.',
        description = 'Headlines from around Los Santos.',
        ui = 'html/index.html',          -- relative .html/.htm path inside THIS resource
        permissions = { 'notifications', 'location' },
        channels = {
            { id = 'breaking', label = 'Breaking news',
              defaults = { enabled = true, banner = true, sound = true, lockscreen = true } },
        },
        deepLinks = { 'story/<id>' },    -- documentation shown to players/admins
        preinstalled = false,            -- true installs on currently open phones
    })
    if not ok then print('RegisterApp failed: ' .. tostring(reason)) end
end

AddEventHandler('onResourceStart', function(resource)
    if resource == GetCurrentResourceName() or resource == 'wd_phone' then
        SetTimeout(500, register)        -- wd_phone may (re)start after you
    end
end)

Your fxmanifest.lua must list the UI files:

files { 'html/index.html', 'html/*.js', 'html/*.css' }

Rules enforced by RegisterApp (it returns false, reason otherwise):

Operators can also install or remove an app on a known device:

exports.wd_phone:InstallApp(deviceId, 'novanews')   --> ok, errorCode
exports.wd_phone:UninstallApp(deviceId, 'novanews')

The phone model's apps whitelist (for example the Wolfden Phone Secure model) applies to external apps too. An app that is not on the whitelist is "Not on this model" in the Store.

Versions and updates#

Raise version and re-register. Devices that installed an older version see Update in the Nova Store and a single "updates available" notification the next time the phone opens (Config.AppPlatform.notifyUpdates). The installed version is informational for your app; read it from NovaSDK.getContext().version if you need migrations.

The app page and the SDK#

Include the SDK from Wolfden Phone:

<script src="https://cfx-nui-wd_phone/sdk/nova-sdk.js"></script>
<script>
  // Attach listeners first: the phone delivers a pending deep link right after
  // the ready() handshake, and pushes any later ones while the app is open.
  NovaSDK.on('context', (c) => { /* the phone's theme changed: same shape as getContext() */ });
  NovaSDK.on('deepLink', (route) => { /* { path: ['story','42'], query: {}, uri } */ });
  NovaSDK.on('message', (data) => { /* from exports.wd_phone:SendAppMessage */ });

  (async () => {
    const ctx = await NovaSDK.ready();          // { appId, version, locale, theme, ..., route }
    document.documentElement.dataset.theme = ctx.theme;
  })();
</script>

Every call returns a Promise that rejects with an Error whose .code is one of PERMISSION_DENIED, PERMISSION_UNKNOWN, RATE_LIMITED, APP_NOT_INSTALLED, INVALID_LINK, INVALID_PAYLOAD, DATA_KIND_UNKNOWN, STORAGE_LIMIT, UNKNOWN_METHOD, TIMEOUT (15 s; requestPermission and pickMedia wait 2 minutes), NOT_EMBEDDED or INTERNAL, or (from useData) one of the offline reasons below. A call that reaches the server can also fail the phone's own checks (NO_SESSION, NOT_POSSESSED, DEVICE_LOCKED, DEVICE_LOST).

Messages are limited to 8 KB (Config.AppPlatform.sdk.maxMessageBytes); a larger one is dropped and the call times out.

Mobile data and app storage#

useData(kind)#

Anything your app fetches "from the internet" in roleplay terms (a feed, a web page, a photo) should cost the phone mobile data like the built-in apps. Call NovaSDK.useData(kind) before loading it:

try {
  await NovaSDK.useData('page');
  loadThePage();
} catch (e) {
  showOffline(e.message);   // e.code: AIRPLANE_MODE, DATA_OFF, NO_SIM, SIM_LOCKED,
}                            // LINE_SUSPENDED, NO_SERVICE, OUT_OF_DATA, NO_DATA, RATE_LIMITED

The server decides the size from its own config (Config.AppPlatform.sdk.dataKinds maps each kind to a usage key); your app never reports one. A joined Wi-Fi network in range is free, exactly as for built-in apps. Calls are rate limited per player (Config.RateLimits.platformData) and the app must be installed on the phone. e.message is already translated into the phone's language.

getItem / setItem / removeItem#

A small key/value store per phone and per app (phone_app_storage), for data that should follow the phone item rather than the player's PC: history, drafts, preferences. Values are any JSON (objects, arrays, strings, numbers, booleans).

Storage is erased when the app is uninstalled from that phone and when the phone is erased. It is not included in Nova Cloud backups or phone transfers. Rate limit: Config.RateLimits.platformStorage. Never store secrets: the player's own client can read and write it through the SDK.

Permissions#

• Declare every permission you might need in RegisterApp. Undeclared permissions are always denied.
• requestPermission shows a system prompt the first time; the answer is stored per device (phone_app_permissions). Players change it later in Settings → Apps → your app (allowing there shows the same prompt). The server raises the prompt, so an app frame cannot grant itself anything. A denied permission is not asked again by the app.
• An app ID belongs to the resource that first registered it. If another resource later registers the same ID, every phone's grants, notification channels and app storage for it are reset.
• Permission checks happen in the NUI and again on the server for anything that reads server data or delivers a notification.
• Built-in NovaOS apps are system apps and are not permission-gated.

Notification channels#

Every notification belongs to an app channel. Players toggle each channel (enabled / banners / sound / lock screen) in Settings → Apps.

From your app page, use NovaSDK.notify({ channel: 'breaking', ... }). From your server:

exports.wd_phone:SendNotification(source, {
    app = 'novanews',          -- your app id
    channel = 'breaking',      -- unknown channels fall back to 'default'
    title = 'Breaking',
    content = 'Storm warning issued for Blaine County',
    persistent = true,
    data = { deepLink = 'nova://novanews/story/43' },   -- tap target (validated)
})

It goes to the player's open phone, else the phone they last looked at, else the first phone they carry (nil when they carry none). A notification is not delivered when the app is not installed, when an external app lacks the notifications permission, or when the channel is off. SendNotification then returns { suppressed = true }.

Built-in channels, for reference: phone/missed, phone/voicemail, messages/direct, messages/groups, bank/activity, bank/requests, social/interactions, social/follows, snapgram/activity, snapgram/messages, ember/likes, ember/matches, ember/messages, mail/inbox, services/requests, calendar/reminders, clock/alarms, clock/timers, marketplace/listings, business/orders, business/campaigns, simManager/billing, store/updates, store/available, findmy/security and findmy/accessories (Locate), news/breaking, garage/valet, homes/keys, shade/dms, shade/mentions, bites/orders, bites/couriers, rides/trips, rides/offers, racing/lobbies, racing/results, racing/crew, racing/bets, clips/activity, clips/follows, clips/live, clips/deals.

Deep links#

nova://<appId>/<segment>/<segment>?key=value

Built-in routes:

A link to an app that is not installed opens its Nova Store page (nothing happens on a phone without the Nova Store). A link to an app the server currently hides for that player, such as Racing without its Racing USB, does nothing. nova:// links in Messages and Mail render as tappable chips.

Server helpers:

exports.wd_phone:OpenDeepLink(source, 'nova://novanews/story/42')   --> boolean
exports.wd_phone:BuildDeepLink('maps', { 'location' }, { x = 12.5, y = -40, label = 'Pier' })

OpenDeepLink routes the link on the player's phone screen; it does not open the phone.

Widgets#

exports.wd_phone:RegisterWidget({
    id = 'novanews_headlines',
    label = 'Headlines',
    icon = 'newspaper',
    app = 'novanews',                    -- only offered/kept where the app is installed
    deepLink = 'nova://novanews/story/42',
    layout = 'list',                     -- 'value' (default) | 'list' | 'progress'
    sizes = { 'small', 'medium' },
    defaultSize = 'medium',
})

exports.wd_phone:UpdateWidget('novanews_headlines', {
    items = { { label = 'Harbour bridge reopens', value = '#41' } },  -- list layout, max 5
    detail = 'Updated just now',
}, target)                               -- a source, or omit/-1 for everyone

exports.wd_phone:UnregisterWidget('novanews_headlines')

Data fields: value, status, detail, unit (strings ≤ 64 or numbers), progress (0–1, progress layout), color (#rrggbb), items (≤ 5 label/value pairs), deepLink. Payloads over 2 KB are rejected. Only the registering resource may update or unregister a widget. Widgets are removed when your resource stops and from the home screen when the owning app is uninstalled.

Server exports reference#

To plug in banking, economy, garage, housing, business, City, Services, Mail actions or dispatch, see Exports & integrations.

Events#

Server events (AddEventHandler), metadata only:

Browser add-on: in-game sites#

The Browser (nova_browser) is a separate resource that registers with the phone as an SDK app; players download it from the Nova Store. Start it after wd_phone. It shows in-game sites that resources serve under made-up domains, and only the real HTTPS websites you list in its config.lua (allowedOrigins, empty by default, because a real website sees the player's IP address). Its README, inside the zip, covers configuration.

Any resource can add an in-game site from its server script:

exports.nova_browser:RegisterSite('lifeinvader.ls', {
    title = 'Lifeinvader',
    url = 'html/index.html',   -- an .html file inside THIS resource
    icon = 'html/icon.png',    -- optional image inside THIS resource
    color = '#e5484d',         -- optional tile colour
}) --> ok, reason
exports.nova_browser:UnregisterSite('lifeinvader.ls')
exports.nova_browser:GetSites()  --> { ['lifeinvader.ls'] = { title, resource } }

• Register again whenever nova_browser starts (listen for onResourceStart), as with RegisterApp. A resource's sites are removed when it stops.
• Domains are lowercase letters, digits and dashes in dot-separated labels, 4-64 characters (www. is dropped). The first resource to register a domain owns it. allowedResources in the Browser's config can limit who may register, and maxSites (default 100) caps the total.
• List the page and its icon in your fxmanifest.lua files { ... }.
• The page runs with its own resource's origin, so it can call its own NUI callbacks like an SDK app page. The path after the domain arrives as the URL hash: lifeinvader.ls/u/42 loads html/index.html#/u/42; listen for hashchange.
• A site page talks to the Browser with window.parent.postMessage(msg, '*'):

The Browser accepts these only from the current tab's frame, and only when the sender's origin is that site's resource. Each page load uses the phone's mobile data (useData('page')).

Security model#

• The NUI accepts SDK messages only when event.source is your iframe's window and event.origin equals https://cfx-nui-<your_resource>.
• The iframe is sandboxed and cannot navigate the phone or read its storage.
• Everything that touches server data (notifications, contacts, mobile data, app storage) is re-checked on the server: device possession, install state, permission, rate limit. App storage is keyed by the server's device ID and the calling app ID, so an app only ever sees its own keys on that phone.
• Never trust data coming back from your own UI either. Validate it in your client/server scripts exactly as NovaOS does.
• Your app gets no access to phone numbers, device ids, PINs, wallet data, messages or other apps' data unless you are granted the matching permission and the SDK method exists.

Icons#

The NUI bundles a curated icon set. Besides the built-in app icons, these are available to external apps and widgets: app-window, gamepad-2, music, radio, newspaper, globe, shopping-cart, utensils, dumbbell, graduation-cap, stethoscope, fuel, bike, ticket, coffee, book-open, tv, car-front, badge-dollar-sign, chart-line, qr-code, key, siren, store, link, external-link, car, truck, home, heart, star, wrench, shield, briefcase, map-pin, package. Unknown names render as a circle.