Pulse Phone docs

Creator apps for Pulse Phone

Any resource can add a full app to Pulse Phone: an icon on the Home Screen, a listing in the App Hub with screenshots, ratings and reviews, a page of its own (plain HTML or React, Vue, anything that builds to a web page) shown inside the phone, and a message channel between that page and the resource's own Lua. The phone draws the frame, the status bar, notifications, badges, the permission prompts and the Home / back gestures, and hands the page its own look - colours, fonts, Dark Mode, the handset's OS and the Pulse Duo's two screens - so a creator's app looks and behaves like a built-in one on every handset.

For Pulse Phone 1.5.248 min readUpdated

What you build is yours: Pulse never maintains your app. A dispatch board, a bank, a game, a page that plays video from a site you choose - the SDK gives you the phone, you decide what the app does.

This guide is for creators (SDK v3, rspulse.js 3.0.0). Every v1 and v2 app keeps working unchanged: nothing below is required, and a page on an older rspulse.js runs as before.

The examples are not in the phone download. They ship in the optional Pulse Developer Kit: unzip it anywhere outside resources. Every example below is a folder inside the kit's optional-developer-kit/ folder; copy only the one you want into resources/.

Example (in the kit's optional-developer-kit/ folder) What it shows
pulse-phone-template-vanilla/ Start here (no build step). Plain HTML/JS: the phone's look, a server request, a client request
pulse-phone-template-react/ Start here (React). React + TypeScript + Vite, typed hooks (src/pulse.ts), hot reload inside the phone
pulse-phone-app-notes/ "Jot": notes in page storage, the back swipe, a draft saved when the app leaves, the Duo's two screens, names and icons per language and Dark Mode
pulse-phone-app-dispatch/ "Dispatch": job gating with grades, server pushes and requests, notifications that open the call, badge, Island activity, a client-side waypoint
pulse-phone-app-webview/ "Web View": a web page from your own config, with sound, video and full screen (capabilities), stopped when the player leaves
pulse-phone-sdk/ rspulse.js, its TypeScript types rspulse.d.ts, and pulse.css (optional base styles drawn from the phone's own theme)
pulse-phone-app-starter/ "Tally": the smallest SDK v2 app
pulse-phone-app-arcade/ "Lane Rush": a landscape game with a store listing, permissions and a server-checked leaderboard
pulse-phone-app-template/ "Field Notes": list, location, server storage, a deep-linking notification
pulse-phone-devapi-demo/ "Dev Kit": every native sheet, an Island activity, a script call
pulse-phone-app-compat/ Runs apps written for another phone's custom-app API (section 11)

Scripts written for another phone keep working without edits: Pulse answers lb-phone:getPhoneNumber, lb-phone:sendMail, lb-phone:sendMessage and lb-phone:notification; qb-phone:server:GetPhoneNumber, qb-phone:server:sendNewMail, qb-phone:server:sendNewMessage and qb-phone:server:sendNotification; npwd:getPhoneNumber, npwd:sendMail, npwd:sendMessage and npwd:notification; and the matching qs-smartphone, gcphone, esx_phone, high_phone and roadphone names, all server-side and built in. Apps built for the lb-phone custom-app API run unedited through the compatibility resource in the kit (section 11).

In the server console, phone_api prints a short summary of the whole API.

Quick start (5 minutes)

  1. Copy pulse-phone-template-vanilla/ (or pulse-phone-template-react/) out of the kit's optional-developer-kit/ folder into your resources/ folder (a resource inside another resource is not started) and rename the folder, e.g. my-app.
  2. Name it. In server.lua change APP_ID (letters, digits and _, unique on the server), name, developer and colour.
  3. Start it after the phone, in server.cfg:

cfg ensure phone ensure my-app

The console prints registered app "my_app" from my-app. A mistake in the declaration is printed there too, naming the field. 4. Open it. It is already on every phone's Home Screen and in App Hub > Creators. No reconnect is needed: an app appears the moment its resource starts. 5. Build your page in ui/ (React: web/, npm install, npm run dev). Open the page in a desktop browser: rspulse.js notices it is not inside the phone, keeps storage in the browser, answers your requests from RSPulse.devHandlers and plays the phone's events with RSPulse.devSimulate, so you work with live reload and test in game at the end (section 15).

Everything else in this guide is optional and added one field at a time.

1. Register the app (server)

Lua
exports.phone:RegisterApp({
    -- v1: what every app has
    id          = 'lane_rush',              -- unique, letters/digits/_ (max 32); the event namespace
    name        = 'Lane Rush',              -- Home Screen label (max 24)
    colour      = '#FF375F',                -- icon tile, #rrggbb
    icon        = 'ui/icon.svg',            -- see "Icons" below; or glyph = 'car'
    description = 'Weave through traffic.', -- App Hub (max 160)
    developer   = 'Your Studio',            -- App Hub: "by Your Studio" and the developer page (max 32)
    version     = '1.2.0',                  -- App Hub "Updates" shows version changes
    job         = { 'police' },             -- optional: only these jobs see the app (v3: grades, below)
    badge       = true,                     -- may set a count on its icon
    notify      = true,                     -- may raise notifications (default true)
    page        = { kind = 'frame', url = 'ui/index.html' },

    -- SDK v2: the App Hub listing and what the app may ask for (all optional)
    category    = 'games',                  -- the shelf (list below)
    tagline     = 'Three lanes. No brakes.',-- the line under the name (max 40)
    whatsNew    = 'Friend challenges.',     -- "What's New" for this version (max 300)
    screenshots = {                         -- up to 6: paths in your resource or https URLs
        'ui/shot-1.jpg',
        { url = 'ui/shot-2.jpg', landscape = true, caption = 'Night traffic' },
    },
    permissions = {                         -- the player is asked once, the server enforces (section 3)
        contacts      = 'To pick a friend to challenge.',
        notifications = 'To tell you when a friend challenges you.',
    },
    orientation = 'landscape',              -- 'portrait' (default), 'landscape' or 'any' (section 2)
    paid        = { url = 'https://you.tebex.io/package/123', price = '9.99 USD' },   -- section 6

    -- SDK v3 (all optional)
    names        = { fr = 'Course', de = 'Spurwechsel' },   -- the label per phone language (24)
    descriptions = { fr = 'Slalom dans le trafic.' },        -- the App Hub text per language (160)
    icons        = {                                         -- per OS and Dark Mode (Icons, below)
        default = 'ui/icon.svg', dark = 'ui/icon-dark.svg',
        duo     = { light = 'ui/icon-duo.svg', dark = 'ui/icon-duo-dark.svg' },
    },
    job          = { police = 2, sheriff = 0 },              -- these jobs, from this grade up
    items        = { 'police_badge' },                       -- and carrying one of these items
    capabilities = { web = 'Why', media = 'Why' },           -- reviewed by the server owner (section 3)
    defaultInstalled = false,                                -- players tap Get in the App Hub first
    devUrl       = 'http://127.0.0.1:5173/',                 -- your dev server, dev servers only (section 15)
})
  • Register from the server. Re-registering the same id from the same resource replaces the declaration (use it to bump version). Another running resource cannot take an id over: it is refused while the first owner runs. exports.phone:UnregisterApp(id) removes it. When your resource stops, its apps are removed automatically; when the phone restarts it forgets add-ons, so register again on onResourceStart for the phone (every example does both).
  • A rejected declaration prints the exact field and reason in the server console - an unknown category, a misspelt orientation, a seventh screenshot, an unknown permission or capability, a language code that is not one, a store link that is not https, a devUrl off this machine.
  • Players already online get the app immediately; no reconnect.

Categories: games, entertainment, social, productivity, utilities, finance, business, lifestyle, music, photo, travel, news, health, education, sports, services.

Screenshots are drawn at the handset's proportions (0.46 : 1, portrait, or 1 : 0.46 with landscape = true): capture your page at 440 x 956 (or 956 x 440). JPEG or PNG, listed under files { }. No data: or http: addresses. An app without screenshots shows a live preview of its page instead.

Who sees the app. job takes names ({ 'police', 'sheriff' }) or names with the lowest grade ({ police = 2 }, 0 = every grade). items takes item names ({ 'badge', 'mdt' }) or names with a count ({ badge = 1 }): the player must carry at least one, read through the phone's inventory adapter (every supported inventory) and checked again within a few seconds of a change. A player who is not offered the app does not see it anywhere, and every message, request and storage call they send as it is refused on the server.

Page

page.url served from
'ui/index.html' (recommended) your resource: https://cfx-nui-<your_resource>/ui/index.html
'nui://my_res/ui/index.html' rewritten to the address above
'https://…' an external page you host (still sandboxed; web keeps its own origin, section 13)

Nothing else is accepted for a page, an icon or a screenshot: no http:, data:, javascript: or file: address (the console names the field).

List the files under files { } in your fxmanifest. Do not set ui_page for it: the phone shows it inside its app frame. Load your scripts as classic <script src> tags (the React template's build does this): a page without web has no origin of its own, and a browser refuses module scripts from another origin unless the server sends CORS headers, which a resource's files do not.

No HTML at all? page.kind may instead be list, form, detail or board - declarative pages the phone renders in its own style; send SendAppMessage(src, id, 'page', {...}) to replace the page live. (Frame apps are what this document is about.)

Icons

icon may be a path in your resource ('ui/icon.png', 'ui/icon.svg'), a URL, or an inline SVG string ('<svg xmlns=… viewBox=…>…</svg>', under 16 KB). Draw it full-bleed and square; the phone applies its own rounded mask. Or use a built-in glyph (shield, cross, wrench, cart, bank, key, car, house, briefcase, radio, camera, pin, bolt, book, chart, dice, fuel, gavel, heart, lock, note, plane, tag, truck) on colour.

One icon per OS and per appearance (v3). The handsets run different OS looks - ultra, titanium, clear, flip and duo - and each has a light and a Dark Mode Home Screen. icons lets you draw for each: default, dark, and any OS as a path or as { light = …, dark = … }. The phone picks, in order: the OS's own (its dark one in Dark Mode), then dark in Dark Mode, then default, then icon. All variants together stay under 48 KB when inline; prefer files. The phone's own icons are rendered objects with one soft light from above (a lens, a paper note, a card): an icon drawn the same way sits naturally beside them.

Installing and removing

Registered apps are installed by default (an MDT must be there when the shift starts). With defaultInstalled = false an app starts under Available in the App Hub and the player taps Get. Players can remove any app from the App Hub (it stays removed across reconnects) and get it back there. Removing an app also forgets the permissions the player gave it.

2. The page (HTML/CSS/JS)

Load the SDK before your own script. Either ship the copy from the kit in your resource (recommended: it also runs in a desktop browser), or load the phone's own, always-current copy:

HTML
<script src="rspulse.js"></script>
<!-- or: <script src="https://cfx-nui-phone/web/build/sdk/rspulse.js"></script>  (if the phone's folder is named phone) -->
<script src="app.js"></script>

Pages on the SDK get sharp text automatically at any screen size and phone size: the phone gives them their real pixels and they lay out at 440 pt themselves. A page without the SDK keeps its 440 pt viewport and is scaled to fit, as before.

JavaScript
await RSPulse.ready                                               // the first context (v3)
RSPulse.on('context', ctx => { /* ctx.theme, ctx.safeArea, ctx.os, ctx.device, ctx.tokens … (ctx.number: below) */ })
const notes = await RSPulse.request('notes:list')                 // your SERVER Lua answers
const where = await RSPulse.request('where', null, { side: 'client' })  // your CLIENT Lua answers
RSPulse.send('shared', { id })               // fire-and-forget to your Lua (client + server)
RSPulse.on('message:notes:added', note => …) // pushed by your Lua
RSPulse.on('deeplink', route => …)           // opened from a notification: 'note/abc'
RSPulse.notify({ title: 'Saved', body: '…', deepLink: 'note/abc' })
RSPulse.badge(0)
RSPulse.open('messages')                     // another app (the player taps Open first); or '<yourId>/route'
RSPulse.home()                               // leave the app
RSPulse.haptic('success')                    // selection, impactLight/Medium/Heavy/Rigid/Soft, success, warning, error
RSPulse.sound('tap')                         // the phone's own sounds (below)

// SDK v2
const state = await RSPulse.permissions.request('contacts')       // 'granted' | 'denied' (section 3)
const people = await RSPulse.contacts.list({ limit: 50 })          // [{ name, number }]
const shots = await RSPulse.photos.list({ limit: 30 })             // [{ url, taken }]
const here = await RSPulse.location.get()                          // { x, y, z, heading }
await RSPulse.storage.set('best', 1215)                            // section 4
await RSPulse.setOrientation('landscape')                          // apps declared orientation = 'any'

// SDK v3 (sections 12-14)
RSPulse.on('pause', save); RSPulse.on('resume', refresh)          // the app left / came back
RSPulse.on('volume', v => player.setVolume(v * 100))              // the phone's media volume, 0..1
await RSPulse.back.enable(true); RSPulse.on('back', closeDetail)   // the phone's back swipe
await RSPulse.call('555-0142')                                     // the player confirms first
await RSPulse.messages.compose({ to: '555-0142' })                // the player presses Send
await RSPulse.fullscreen(true)                                     // turns the phone sideways

RSPulse.api is 3 on a phone with SDK v3, 2 or 1 on older ones; calls a phone does not have reject with 'unknown-method', so a page can fall back.

Sounds (RSPulse.sound(name)): tap, success, error, warning, notify, send, receive, complete, start, stop, shutter, lap - the phone's own, at the player's volume and Silent Mode; at most 6 a second.

Landscape apps

orientation = 'landscape' turns the phone sideways as the app opens - the handset itself turns, with the status bar out of the way - and stands it up again when the player leaves. Use it for games and video. orientation = 'any' opens upright and turns when the page asks:

JavaScript
RSPulse.on('orientation', o => layout(o))     // 'landscape' | 'portrait'
await RSPulse.setOrientation('landscape')     // e.g. a video going full screen

While turned, the context says orientation: 'landscape', size is 956 x 440 and the safe area keeps 48 px clear on both short sides (the Island's side and its mirror) and the Home band at the bottom. <html data-orientation> follows it, so CSS can switch layout. A portrait app is refused ('orientation-locked').

Native UI: pickers, alerts and sheets the phone draws

Your page can ask the phone to draw its own contact picker, photo picker, alert, confirm, action sheet, text prompt (with the phone's own keyboard) and camera. They look and move exactly like the phone's, and they are the only way a page gets a contact or a photo: nothing is read silently, the page receives just the one thing the player taps, and the Camera opens only after the player agrees.

Every call returns a Promise. It rejects with an Error whose message is the reason: 'cancelled' (the player said no), 'busy' (a sheet is already open), 'rate-limited', 'not-visible' (your app is not the one on screen), 'unknown-method', or 'bad-params: <what is wrong>'.

JavaScript
const who = await RSPulse.pickContact({ title: 'Send To' })       // { name, number }
const pic = await RSPulse.pickPhoto({ title: 'Evidence' })         // { url, taken }  (url: show it in an <img>)
await RSPulse.alert({ title: 'Shift Started', message: 'On duty until 18:00.', button: 'Got It' })
const yes = await RSPulse.confirm({ title: 'Delete Report?', message: 'This cannot be undone.',
                                    confirm: 'Delete', cancel: 'Keep', destructive: true })   // true | false
const pick = await RSPulse.actionSheet({ title: 'Share Location', actions: [
  { id: 'pin', label: 'Drop a Pin' }, { id: 'stop', label: 'Stop Sharing', destructive: true },
] })                                                               // 'pin' | 'stop'
const plate = await RSPulse.prompt({ title: 'Plate Number', placeholder: 'e.g. 46EEK572',
                                     maxLength: 8, keyboard: 'text' })   // the text typed
Call Parameters (all text is trimmed; longer text is refused, not cut) Answers
pickContact title? (40) { name, number } of the contact tapped
pickPhoto title? (40) { url, taken } of the photo tapped (videos and deleted photos are not offered)
alert title (80), message? (300), button? (20) nothing, once dismissed
confirm title (80), message? (300), confirm? (20), cancel? (20), destructive? true / false
actionSheet title? (80), actions: 1-6 of { id (1-32 of A-Z a-z 0-9 _ -, unique), label (40), destructive? } the id tapped
prompt title (80), message? (200), placeholder? (60), value?, maxLength? (1-500, default 120), keyboard? ('text', 'number', 'decimal', 'phone'), secure?, confirm? (20) the text
capturePhoto state? (any plain data, up to 2048 characters as JSON) see below

Unknown parameters are refused (bad-params: unknown parameter "…"), so a typo shows up at once.

Taking a photo. The phone runs one app at a time, so the Camera replaces your page while the player takes the photo, and your page loads again when they come back. The answer therefore arrives as a capture event after your page's ready, carrying the state you passed in so you can put the page back where it was:

JavaScript
RSPulse.on('capture', ({ ok, url, error, state }) => {
  if (ok) attachPhoto(state.reportId, url)       // url: the saved photo, as pickPhoto returns it
  else showNotice(error)                          // 'cancelled' | 'timeout'
})

await RSPulse.capturePhoto({ reportId: 42 })      // resolves { opened: true } once the Camera is opening

The player first sees "“Your App” Would Like to Use the Camera" with Don't Allow / Open Camera (Don't Allow rejects 'cancelled'). While the Camera is open the Island shows Photo for Your App with Cancel. The first photo saved sends the player straight back to your app; leaving the Camera without one, Cancel, or five minutes, answers ok: false. The photo is also in the player's Photos, like any photo they take.

An Island activity from your page

One Island activity per add-on, on the Island and the Lock Screen, leading back into your app:

JavaScript
await RSPulse.activity.start({ title: 'Tow truck', detail: 'On its way', countdown: 240,
                               glyph: 'truck', colour: '#FF9F0A', route: 'job/42' })
await RSPulse.activity.update({ detail: 'Arriving', compact: '1 min' })
await RSPulse.activity.end()

Fields as in EXPORTS.md section 14 (title 40, detail 60, compact 12, progress 0-1 or countdown seconds with endOnZero, glyph, colour), with two differences: a tap always opens your app, at route (there is no link), and without a glyph it shows your app's icon. Updates faster than one per 500 ms are merged (the last one wins). A second activity is refused ('limit-resource'); start again with the same id replaces it. It stays when your page closes - that is what it is for - and ends when you end it or when your resource stops.

For server- and client-side activities (no page needed) see EXPORTS.md section 14.

Look like the phone

rspulse.js sets, from the first paint (the phone puts them in the page address) and again whenever the player changes them:

  • <html data-theme="light|dark"> - follow it; the phone switches automatically at dusk if the player chose Automatic.
  • <html dir="ltr|rtl"> - the phone's language direction; use logical CSS (margin-inline-start) and right-to-left languages lay out correctly.
  • <html data-orientation="portrait|landscape">.
  • --rsp-accent - the phone's accent colour (it follows the handset), for your small controls.
  • --rsp-safe-top (status bar), --rsp-safe-bottom (the Home swipe band), --rsp-safe-left (the back-swipe edge), --rsp-safe-right.
  • --rsp-text-scale (Settings › Display › Text Size), class rsp-reduce-motion.
  • SDK v3: the handset's whole look - data-os, data-device, --rsp-bg, --rsp-label, --rsp-tint, the fonts, the Duo's hinge and more. Section 12.

Keep tappable controls out of the bottom and left bands: those strips belong to the phone (Home swipe/tap and back swipe work over your page) and do not reach it.

The phone's browser is Chromium 103: no CSS :has(), container queries, CSS nesting or color-mix(), and backdrop-filter is best avoided in a page.

Developing in a browser

Open your page directly in a browser: rspulse.js detects it is not inside the phone, sends a stand-in context (with the Ultra look's theme values), keeps RSPulse.storage in the browser's own storage, simulates a turn for setOrientation and fullscreen, answers every permission 'granted', and answers request from RSPulse.devHandlers[event]. There are no native sheets or player data in a plain browser: those calls reject 'not-in-phone' unless you give a stand-in, RSPulse.devSdk.pickContact = () => ({ name: 'Ava', number: '555-0142' }) (the same for 'contacts.list', 'photos.list', 'location.get'). RSPulse.devSimulate(…) plays the phone's events: ('lifecycle', { state: 'background' }), ('volume', { volume: 0.3 }), ('back'), ('theme', 'dark'), ('device', { form: 'duo-spread', hinge: { x: 601, width: 22 } }).

3. Permissions

Declare what your app may ask for in RegisterApp (permissions), with a sentence saying why: it is shown in the prompt, on your App Hub page and in Settings.

Permission Opens Without it
notifications your notifications (page and server) reach the player they are dropped
contacts RSPulse.contacts.list, exports.phone:GetAppContacts refused
photos RSPulse.photos.list, exports.phone:GetAppPhotos refused
location RSPulse.location.get, exports.phone:GetAppLocation refused
camera RSPulse.capturePhoto opens the Camera without asking each time refused

The player is asked once. The first call that needs a permission the player has not answered shows the phone's own prompt - "Lane Rush" Would Like to Access Your Contacts, your reason, Don't Allow / Allow - and the call continues with the answer. Ask at the moment it makes sense (the dispatch example offers it as a row the player taps, never as a prompt on launch):

JavaScript
const p = await RSPulse.permissions.query()        // { contacts: 'prompt' | 'granted' | 'denied', ... }
if (p.notifications === 'prompt') await RSPulse.permissions.request('notifications')
RSPulse.on('permission', ({ permission, state }) => …)   // changed in Settings while open

A permission the player refused is not asked again: the call rejects 'denied' and the player changes it in Settings › Apps › your app (where every answer can be switched, or reset with Ask Next Time). A permission you did not declare rejects 'not-declared'.

The server decides. The answers are stored on the server per phone, and the server checks them before it hands your app any data - whatever your page or client script sends. An app that declares notifications has its notifications delivered only once the player allowed them; an app that declares no permissions at all keeps the v1 rules (notify = true). The one-off pickers (pickContact, pickPhoto) need no permission: the player picks the one thing you get.

Your Lua:

Lua
exports.phone:HasAppPermission(src, 'lane_rush', 'contacts')   -- true / false, nil if not asked yet
exports.phone:GetAppContacts(src, 'lane_rush', function(list, reason) end)   -- reason: 'denied', 'not-asked', 'not-declared'
exports.phone:GetAppPhotos(src, 'lane_rush', function(list, reason) end)
exports.phone:GetAppLocation(src, 'lane_rush', function(pos, reason) end)
AddEventHandler('phone:app:lane_rush:permission', function(src, permission, state) end)   -- 'granted' | 'denied' | 'ask'

A contact is { name, number } and a photo { url, taken } - never more of the player's data.

Capabilities the server owner reviews (v3)

Two things a page may do beyond a plain sandboxed page are not the player's to answer but the server owner's, because they are about what the city allows, not about the player's data:

Capability What the page gets Typical app
web it keeps its own web origin, so pages and players it embeds from other sites (a video site's embed, a map, your own web app) keep their storage and work as in a browser a web view, an embedded player, a hosted web app
media sound and video may start without a tap, go full screen, play protected streams and picture-in-picture; the phone stops it when the player leaves the app a music or video app, a stream
Lua
capabilities = {
    web   = 'Shows the page this city chose, with what it embeds.',
    media = 'Plays the page’s sound and video, and full screen.',
},

The console prints what each app asks for and whether it is allowed. The owner decides in config/apps.lua (Config.AppStore.capabilities, section 6); players see both, with your reasons, in Settings › Apps › your app under Set by This City. Neither opens any player data, another app, or any of the phone's own events. A page reads what it got from context.capabilities ({ web: true, media: false }) and should say so when one is off - the Web View example does.

4. Storage

A page's own key/value storage, kept on the server per phone (it follows the player to any machine), no database work:

JavaScript
await RSPulse.storage.set('best', 1215)    // any JSON value up to 8 KB; keys: 1-64 of A-Z a-z 0-9 _ . : -
const best = await RSPulse.storage.get('best')
await RSPulse.storage.remove('best')
const keys = await RSPulse.storage.keys()

It is the same store as exports.phone:Set / Get: your Lua reads a page's key as 'page:<key>' with the phone number as owner (exports.phone:Get(APP_ID, number, 'page:best', cb)). A page can never overwrite a key your server code keeps, never read another app's keys and never read another phone's. At most 200 keys per app per phone. Like anything from the page it is player input: keep scores and money on the server. The notes example shows a layout that scales (an index key and one key per note).

5. Ratings, reviews and the App Hub

Under App Hub › Discover › Creators players see the featured apps (the server owner's picks, else the best rated with screenshots), Top Rated, New in This City (first run here in the last three weeks), every app from the city, and a page per developer. An app's page has its screenshots, rating and reviews, install count, What's New with the version history, the permissions and what the player answered, and an Updated badge when your version changes.

Every number is real: a rating is the mean of players' stars, installs are the phones that have the app. Players rate 1-5 stars with an optional title and review, one per phone per app (writing again edits it), and can delete their own. Anyone can report a review; moderators remove, restore and ban from reviewing in Settings › Moderation, exactly as for social posts. Your server hears new ratings: AddEventHandler('phone:appReviewed', function(src, appId, rating) end), and can read them: exports.phone:GetAppRating(appId, function(r) end) (r.rating, r.count, r.installs).

6. Paid apps and what the server owner controls

The phone never handles money. If you sell your app, declare where: paid = { url = 'https://you.tebex.io/package/123', price = '9.99 USD' }. Server owners buy it from you and install your resource as usual. Players always see Get and Open - they never pay - and staff (ace phone.admin) see your store link on your app and developer pages.

The server owner decides what is offered in config/apps.lua (Config.AppStore):

Setting Effect
allow = { ... } only these apps (ids or resource names); empty = all
deny = { ... } never offered; wins over everything
jobs = { app = { 'mechanic' } } or { app = { police = 2 } } per-job access, with a lowest grade, on top of the app's own job
freeHere = true or { 'app_id' } paid apps offered free to players: all, or only those listed (the rest are visible to staff only, with a note)
storeLinks = 'staff' who sees a paid app's store link: 'staff', 'everyone', 'nobody'
featured = { ... } the Featured shelf, in order
reviews = { enabled, maxLength, perHour } ratings and reviews
capabilities = { web = true, media = true } v3: true every app that declares it, false none, { 'app_id', 'resource' } only these

An app that is not offered to a player is missing from their phone and refused on the server for every message, request and data call. Config.Addons.allowCustomPages = false (config/config.lua) restricts every add-on to the declarative pages.

7. Your Lua

Server

Lua
-- fire-and-forget from the page (and 'open' / 'close' when the app is shown / left)
AddEventHandler('phone:app:rsp_notes', function(src, event, payload) end)

-- requests: call reply(result) - now or later (after a DB read). 10 s timeout.
AddEventHandler('phone:app:rsp_notes:request', function(src, event, payload, reply)
    if event == 'notes:list' then return reply(loadNotes(src)) end
    reply(nil)   -- always answer unknown events
end)

exports.phone:SendAppMessage(src, 'rsp_notes', 'notes:added', note)      -- to one player's page
exports.phone:BroadcastApp('rsp_notes', 'dispatch', data, 'police')      -- to every player (job filter optional)
exports.phone:Notify(src, { app = 'rsp_notes', title = '…', body = '…', deepLink = 'note/abc' })
exports.phone:SetBadge(src, 'rsp_notes', 3)
exports.phone:GetApps(src)                 -- the apps this player is offered (job, grade, items, owner rules)
exports.phone:GetPhoneNumber(src)          -- '481-2097' or nil
exports.phone:SourceOfNumber('481-2097')   -- src or nil
exports.phone:Set('rsp_notes', owner, 'key', value)            -- per-app key/value storage
exports.phone:Get('rsp_notes', owner, 'key', function(value) end)

A notification's deepLink is the route inside your app: tapping it opens your app and your page receives deeplink with that route (also when it is already open). For an app that declares notifications, Notify returns false (and nothing is shown) until the player allowed it. To push to everyone who may see an app (grades and items included), loop GetPlayers() and check GetApps(src) - the dispatch example does.

Client (optional)

For what only the game client knows (position, vehicle, inventory UI):

Lua
AddEventHandler('phone:app:rsp_notes', function(event, payload) end)                  -- incl. 'open'/'close'
AddEventHandler('phone:app:rsp_notes:request', function(event, payload, reply) end)   -- side = 'client'
exports.phone:SendAppMessage('rsp_notes', 'env', { inVehicle = true })  -- to the page, no server trip
exports.phone:IsAppOpen('rsp_notes')

8. Security model (read this)

  • The phone's own callbacks are the phone's. Any page in the game's browser can send a request to https://phone/<callback>, a page inside the phone included. Every one of the phone's NUI callbacks refuses a request without the phone page's own key (a random key per session, sent only to the phone's page by the game, never to a frame inside it), so an app's page cannot call them itself - not the owner panel, not the permissions, not another app's storage. The phone acts for your page only through the messages below, and always as YOUR app: the app id comes from the frame that sent the message, never from what the page wrote.
  • The phone number is personal. context.number is null unless the player allowed your app contacts; your server can always ask exports.phone:GetPhoneNumber(src).
  • Every page runs in its own frame. The page runs in an <iframe sandbox="allow-scripts allow-forms"> without allow-same-origin: it cannot read the phone's document, storage or NUI callbacks, cannot navigate the top window, cannot open popups. An app the server granted web keeps its own origin - its resource's (https://cfx-nui-<resource>) or its site's - and never the phone's or another resource's: a page whose address is on the phone's origin or on another resource's gets no origin, whatever it declared. Its messages are then checked against that exact origin both ways, so a frame that navigated elsewhere stops hearing the phone.
  • Never delegated: camera, microphone, location, screen capture, USB, serial, HID, Bluetooth, payment and clipboard reading are switched off in every app's frame (allow="… 'none'"). The player's data reaches a page only through the SDK calls above. media delegates autoplay, full screen, protected media and picture-in-picture, and only to the app it was granted to.
  • The phone accepts a message only from your iframe's window, and scopes every action to your app id: a page cannot notify, badge or message as another app. Game (NUI) messages are only accepted from the phone's own window, so a page cannot forge them. rspulse.js in turn accepts messages only from the phone (never from a frame your page embeds).
  • An app id belongs to the resource that registered it while that resource runs: another resource registering the same id is refused.
  • Messages reach only the resource that registered the app, and only for players who can see it (job, grade and items are re-checked on every message and request on the server).
  • Each page is rate-limited (60 messages/second; excess is dropped with a console warning).
  • Contacts, photos and the camera only by consent. The page never gets a list unless the player allowed it: the phone draws the picker and the page receives the one contact or photo the player taps. The Camera opens only after the player answers the phone's own prompt. The native sheets answer only while your app is the one on screen ('not-visible' otherwise), one at a time ('busy'), and at most 8 in 20 seconds ('rate-limited'); call prompts at most 3 in 30 seconds.
  • Calls, messages and other apps are the player's. RSPulse.call places nothing until the player taps Call; RSPulse.messages.compose opens Messages and the player presses Send; RSPulse.open takes the player to another app only after they tap Open.
  • Sound stops with the app. An app with web or media is unloaded shortly after it leaves the screen (section 13); every page's own <audio> / <video> is paused by rspulse.js.
  • Every parameter crossing the frame is checked by type and length on the phone side; anything else is refused with bad-params, never passed through. Theme values handed to a page are plain colours, lengths and font names only.
  • Treat every payload as client input. It came from a player's machine. Validate and clamp it, and never take an identity from it - use src and GetPhoneNumber(src).
  • Permissions are enforced on the server (section 3): the player's answer is checked for every data request, and a page never receives a list it was not allowed.
  • Reviews and ratings are players' own: one per phone per app, rate limited, filtered by the server's word list and moderated like posts.
  • Config.Addons.allowCustomPages = false (phone config) restricts add-ons to the declarative pages; Config.AppStore decides which apps are offered at all and which capabilities they get (section 6). A devUrl is used only with set pulse_dev_apps true.

9. Protocol reference (for pages not using rspulse.js)

Page → phone: parent.postMessage({ rspulse: 1, type, ... }, '*')

type fields effect
ready zoom? phone replies context, then delivers anything queued, then a pending deeplink
send event, payload client phone:app:<id> + server phone:app:<id>
request id, event, payload, side? answered by response with the same id
notify title, body, deepLink? notification (if notify ~= false)
badge count icon badge (if badge = true)
open link '<app>' or '<app>/<route>'; your own id → deeplink; another app opens after the player taps Open in the phone's alert (4 in 30 s, only while your app is on screen)
home - leave the app
haptic kind system haptic
typing active a text field has focus: the character stops walking while typing
sdk id, method, params a native sheet or Island activity (methods: pickContact, pickPhoto, alert, confirm, actionSheet, prompt, capturePhoto, activity.start, activity.update, activity.end; SDK v2: permissions.query, permissions.request, contacts.list, photos.list, location.get, storage.get, storage.set, storage.remove, storage.keys, orientation.set, orientation.get, sound.play; SDK v3: call, messages.compose, back.set, fullscreen.set, volume.get); answered by response with the same id

Phone → page: { rspulse: 1, app, type, ... } (to '*', or to the page's own origin when it kept one)

type fields
context version, number (only for an app the player allowed contacts, else null), theme, textScale, reduceMotion, safeArea{top,bottom,left,right}, size{width,height}, locale; SDK v2 adds api, orientation, dir, accent, permissions (declared ones: granted, denied or prompt); SDK v3 (api: 3) adds os{look,style}, device{model,form,hinge,fold}, tokens, volume, inCall, lifecycle, capabilities, restored, preview
message event, payload
response id, ok, data or error (timeout, unknown-app, failed; for sdk: cancelled, busy, rate-limited, not-visible, unknown-method, bad-params: …, and SDK v2: denied, not-asked, not-declared, orientation-locked, too-large, full; SDK v3: in-call)
deeplink route
orientation orientation: the phone turned
permission permission, state: an answer changed (prompt or Settings)
capture requestId, ok, url or error (cancelled, timeout), state: the photo a capturePhoto asked for, sent after ready
lifecycle v3: state (active, inactive, background), reason (open, controlCentre, notificationCentre, switcher, home, other-app, locked, display-off, put-away, folded)
volume v3: volume 0..1, the phone's media volume
call v3: active: a phone call started or ended
back v3: the player swiped back (only while the page enabled it with back.set)

Page address parameters: rsp_app, rsp_theme, rsp_safe_top, rsp_safe_bottom, and SDK v2: rsp_dir, rsp_accent, rsp_orientation.

The wire marker stays rspulse: 1 for every version, so a v1, v2 and v3 page talk to the same phone; a page tells the difference from context.api.

10. Not supported

  • Registering from the client (apps are server-registered so job gating, permissions and the App Hub stay authoritative). Apps written for another phone's API do add themselves from the client; section 11.
  • Selling inside the phone: there are no prices, purchases or in-app payments, by design (section 6).
  • A page reading the phone's own data beyond the permissions above (messages, call history, the whole photo library at once). Anything more, ask your Lua, which can use the phone's server exports.
  • Microphone, camera stream or screen capture from a page (the Camera is the phone's, section 2).
  • Background playback: an app's sound stops when the player leaves it (section 13). Music that should keep playing belongs in the phone's Music app or your own resource's sound system.
  • A page drawn over other apps, or on the Pulse Flip's small cover screen: the cover shows the time and notifications, and your app is in the background while the Flip is shut.

11. Apps written for another phone's API

Many servers already run custom apps (dispatch, banking, job boards, taxis) written for the custom-app API of the phone resource named lb-phone. Those apps run on Pulse Phone without being edited, through the app compatibility resource in the developer kit, pulse-phone-app-compat/. The app opens in the phone's own app frame, follows the player's light/dark setting, and its popups, menus, pickers and notifications are drawn by Pulse in Pulse's style.

Installing

  1. Copy pulse-phone-app-compat/ out of the kit's optional-developer-kit/ folder into your resources/ folder, next to the app resources you already have.
  2. Remove the old phone and its ensure line, if it is still there. The compatibility resource answers in that phone's place (fxmanifest provide 'lb-phone'), so the two can't run together. While a resource named lb-phone is running, the compatibility resource stands aside (and says so in the console when it starts).
  3. In server.cfg, start it after the phone and before the apps:

cfg ensure phone ensure pulse-phone-app-compat ensure my-dispatch-app ensure my-bank-app

Nothing else changes: the apps keep their own folders, scripts and pages. A renamed phone is found by its pulse_phone 'yes' manifest line, or name it with setr pulse_phone_resource "my_phone". When the phone or the compatibility resource restarts, every app is added again by itself.

What players see

  • The app is on the Home Screen and in the App Hub like any add-on, installed by default. Players can remove it in the App Hub and get it back there; its onDelete / onInstall run when they do.
  • Opening it shows its page inside the phone, with the phone's status bar, Home gesture and back swipe. data-theme on the page is dark or light, and settings / onSettingsChange follow the player's appearance.
  • An app without a page runs its onUse when opened, and the phone returns to where it was.
  • A page that does not load within 15 seconds shows "App Didn't Load" with Try Again.

Supported calls

Client exports, called as the apps already do (exports["lb-phone"]:AddCustomApp(...)):

Export On Pulse Phone
AddCustomApp(app) identifier, name, description, developer, ui, icon, onUse, onOpen, onClose, onInstall, onDelete. Returns true or false, reason; a refusal also prints the reason in the client console
RemoveCustomApp(identifier) only the resource that added the app can remove it
SendCustomAppMessage(identifier, data) data arrives as the page's own message event (onNuiEvent / useNuiEvent match data.action)
SetPopUp(data) title, description, picture, one text field, up to 6 buttons (blue, red, green, yellow); the pressed button's cb runs
SetContextMenu(data) the phone's action sheet with Cancel; up to 8 entries
ShowComponent(options, cb) contactselector and gallery, while one of the calling resource's apps is open
SendNotification(data) app (the app's identifier), title, content
OpenApp(app) / CloseApp(options?) the phone's own apps by plain name (Messages, Maps, Clock ...) and compat apps by identifier
IsOpen, ToggleOpen(open?), IsDisabled, ToggleDisabled(disabled), GetEquippedPhoneNumber, FormatNumber, HasPhoneItem, IsInCall, GetAirplaneMode, GetFlashlight, ToggleFlashlight(on), GetBattery, IsCharging, IsPhoneDead forwarded to Pulse Phone's own client exports
RegisterClientCallback, AwaitCallback, TriggerCallback callbacks between the app's client and server scripts (15 s timeout)

Server exports:

Export On Pulse Phone
RegisterCallback(event, handler, options?), BaseCallback(event, handler, options?) options: preventSpam, rateLimit (per player per minute; 60 when not set), defaultReturn. BaseCallback passes the player's phone number after the source, and answers defaultReturn to a player without one
AwaitClientCallback(event, source, ...), TriggerClientCallback(event, source, cb, ...) only the asked player can answer
SendNotification(target, data) to a server ID, or to a phone number while its player is online
GetEquippedPhoneNumber(source or identifier), GetSourceFromNumber, FormatNumber, HasPhoneItem, IsPhoneDead, IsInCall, EndCall forwarded to Pulse Phone's own server exports

Events raised under that phone's names: client lb-phone:phoneToggled and lb-phone:numberChanged, server lb-phone:numberChanged.

The page gets, after componentsLoaded: fetchNui(event, data) (to the app's own resource only), onNuiEvent / useNuiEvent, settings, getSettings, onSettingsChange, sendNotification, setApp, createCall (the player confirms first), formatPhoneNumber, resourceName, appName, appIdentifier, and in components: setPopUp, setContextMenu, setContactSelector, setGallery (photos), setFullscreenImage, saveToGallery, setHomeIndicatorVisible. The older globals setPopUp, setContextMenu and selectGallery work too.

Not supported

Each of these is refused openly: the player sees "Not Available" when they tap something that needs it, and the console names it once.

  • createGameRender and GameMap (the in-app camera view and map), uploadMedia, fetchPhone, useCamera / SetCameraComponent, and the GIF, emoji, colour and music pickers and the share sheet.
  • price (apps are free here), landscape (their pages open upright), game, images and size are accepted and ignored. fixBlur changes nothing: pages are drawn sharp anyway.
  • defaultApp = false: the app is installed like any other; players remove it in the App Hub.
  • fetchNui(event, data, otherResource): a page reaches only its own resource.
  • Calling a company with createCall, video pickers, and more than one text field in a popup (the first is shown).
  • Every export not listed above. A script calling one gets FiveM's own No such export error. Only start the compatibility resource if you use such apps: while it runs, other scripts that look for that phone find it too, and only the calls above answer.

Security

  • A page is served from its own resource (ui must name the resource that adds the app), so its storage is its own, and it cannot navigate the phone, open windows or raise browser dialogs.
  • The popups, menus and pickers a page asks for appear only while its app is on screen, one at a time and at most 8 in 20 seconds. A page gets a contact or photo only when the player picks one, and its call starts only after the player taps Call. A page's notifications are capped at 10 in 10 seconds, its saved photos at 5 a minute and its requests at 60 a second.
  • Treat these apps like any other resource that runs on players' machines: whatever their page or client script sends to the server is client input, and money or items must be checked on the server.

Tested

Three test apps written from the public documentation (a page with a popup and notifications, a board with server callbacks, menus, the contact picker and removal, and an app with no page) run through the compatibility resource and Pulse Phone in automated tests. Apps you run that do not behave: send their name and the client console output to support.

12. Look native on every OS and the Duo

Pulse handsets do not share one look. The Ultra, Titanium, Clear and Flip each run their own OS look, the player can choose a style for it, every look has a light and a Dark Mode, and the Pulse Duo runs its own OS on a cover screen and, open, across two screens with a fold between them. A page on SDK v3 gets all of it, live:

On <html> / in the context Values
data-os / context.os.look ultra, titanium, clear, flip, duo
data-os-style / context.os.style the style the player chose for that look (default, or a style's id)
data-device / context.device.form phone, duo-cover (the Duo shut), duo-spread (open across both screens), tablet
data-model / context.device.model ultra, titanium, clear, flip, book (the Duo)
data-theme light, dark
data-lifecycle active, inactive, background

The phone's own values, as CSS variables, for the current look, style and appearance:

Variable Use
--rsp-bg, --rsp-bg-2 a plain screen's background
--rsp-grouped-bg, --rsp-grouped-bg-2 a grouped list's background and its rows
--rsp-label, --rsp-label-2, --rsp-label-3 text: primary, secondary, tertiary
--rsp-separator, --rsp-fill-3 hairlines, fields and pressed rows
--rsp-tint, --rsp-link the look's tint: buttons, links, the selection
--rsp-blue, --rsp-red, --rsp-green, --rsp-orange, --rsp-yellow, --rsp-destructive system colours, adjusted per look and appearance
--rsp-model-accent the handset's own accent
--rsp-r-card, --rsp-r-button, --rsp-r-sheet, --rsp-screen-radius corner radii
--rsp-font-ui, --rsp-font-display, --rsp-font-rounded, --rsp-font-mono the look's font families (see the note below)
--rsp-hinge-x, --rsp-hinge-width the Duo open: where the fold is, in page pixels (0 elsewhere)
--rsp-volume the media volume, 0..1

RSPulse.tokens holds the same values for script. pulse.css (developer kit) is an optional stylesheet built only on these: an inset grouped list (.group, .row), a large title, buttons, fields, empty states, a navigation bar with the back chevron, and .split for the Duo. Every example uses it, so each one takes the look of the handset it runs on with no code of its own.

Fonts. The variables name the look's font families. A page cannot load the phone's own font files (they belong to the phone's origin): ship the font files you want in your resource and list them under files { }, or let the family list fall back to the system font.

The Pulse Duo.

  • Shut (duo-cover). A single tall screen. Its camera sits in the top corner below the status bar; the context's top safe area keeps your page under it - use --rsp-safe-top.
  • Open (duo-spread). Your page spans both screens (context.size is the whole spread) with the fold at context.device.hinge ({ x, width }). Never put text or a control across it: lay out two panes, one each side. pulse.css does it for you:

```html

the list
the selected item

```

On a phone .split is a plain block (show one pane at a time); on the Duo open it becomes two columns, one each side of the fold. The notes and dispatch examples show list and detail side by side; the web view gives a web page the right screen to itself. - The context changes when the Duo is opened or shut while your app is open: listen to context.

The Pulse Flip. context.device.fold is open or shut. Shut, your app is in the background (section 13): the cover shows the time and notifications.

Text size and motion. --rsp-text-scale follows Settings › Display › Text Size; multiply your font sizes by it. rsp-reduce-motion on <html> means the player asked for less motion.

13. Lifecycle, sound and web content

Lifecycle. The page always knows whether it is on screen:

State When Your page
active on screen, taking input run
inactive on screen under something the phone draws: Control Centre, notifications, the app switcher keep running; do not start sound
background not on screen: Home, another app, locked, the display off, the phone put away, a Flip folded shut save what you need, stop sound
JavaScript
RSPulse.on('lifecycle', ({ state, reason }) => …)
RSPulse.on('pause', () => saveDraft())      // to background
RSPulse.on('resume', () => refresh())       // back from background
RSPulse.lifecycle                           // the state now

The server hears open and close as before (section 7).

Sound follows the phone. RSPulse.volume (0..1) is the phone's media volume, and the volume event fires when the player presses the volume buttons. rspulse.js applies it to your page's own <audio> and <video> elements (turn off with RSPulse.autoVolume = false if you mix sound yourself), pauses them in the background and resumes the ones it paused when the player comes back (RSPulse.autoPause = false to do it yourself). During a phone call (RSPulse.inCall, the call event) duck or pause your sound. A page's sound is heard by the player only - it is not world audio.

A player embedded from another site (an <iframe> in your page) is outside your page: neither rspulse.js nor the phone can reach into it. So:

  • forward the volume to it in the way that site's player offers (most embeddable players take commands by postMessage or have an iframe API with a volume and a pause call); the web view example posts { type: 'pulse:volume', volume } to the page it shows, which your own pages can listen for;
  • the phone unloads every app with web or media about a second after it goes to the background - that is what guarantees an embedded player falls silent. When the player returns, the page loads again and its context says restored: true: put it back from RSPulse.storage (save on pause).

Web content (web) keeps your page's own origin, so a page or player it embeds keeps its own origin too and runs as in a browser. Without web your page and everything it embeds has no origin: most embeddable players and web apps refuse to start then. Many sites refuse to be shown inside another page at all (X-Frame-Options, frame-ancestors); nothing in a phone can change that - choose pages that allow embedding, or host your own. Popups and navigating the phone are never allowed; links that open a new window do nothing.

Media (media) lets your page and what it embeds start sound without a tap, go full screen, play protected streams (where the game's browser supports them) and picture-in-picture. When a player in your page goes full screen, rspulse.js turns the phone sideways for it (apps declared orientation = 'any' or 'landscape'); RSPulse.fullscreen(true) does it on demand.

14. Calls, messages, back and full screen

JavaScript
await RSPulse.call('555-0142', { video: false })     // "Call 555-0142?" - only the player's tap places it
// rejects 'cancelled', 'in-call', 'busy', 'rate-limited' (3 in 30 s), or the call's own reason

await RSPulse.messages.compose({ to: '555-0142' })   // opens that conversation in Messages
await RSPulse.messages.compose({ body: 'On my way' }) // a new message with this text; the player picks the recipient
// the player always presses Send; your app is left (it goes to the background)

await RSPulse.back.enable(true)                      // while your page has somewhere to go back to
RSPulse.on('back', () => closeDetail())              // the edge swipe and Backspace come here
await RSPulse.back.enable(false)                     // at your root: the swipe does nothing, as in the phone's apps

await RSPulse.fullscreen(true)                       // turns the phone sideways (orientation 'any' / 'landscape')

Turn back on only while it means something (a detail screen open), and turn it off at your root: the phone's own apps behave the same way, and players expect the swipe to do nothing at the top level of an app.

15. Templates, TypeScript and hot reload

Vanilla (pulse-phone-template-vanilla/): HTML, CSS and JavaScript, no build step. Edit ui/, ensure the resource again, reopen the app.

React (pulse-phone-template-react/): React, TypeScript and Vite. The source is in web/, the built page in ui/ (already built, so ensure works as shipped).

cd web
npm install
npm run dev       # http://127.0.0.1:5173 in a desktop browser, with hot reload
npm run build     # writes ../ui for the phone

pulse-phone-template-react/src/pulse.ts has typed hooks over rspulse.js: usePulseContext, useLifecycle, useVolume, useForm (phone / Duo cover / Duo spread), usePulseEvent, useServerMessage, useBack(handler | null) and useStorage(key, initial). The template's Vite settings matter: base: './', target: 'chrome103', and one classic script (not a module) - see the comment in vite.config.ts. Vue, Svelte or anything else works the same way: load rspulse.js with a classic <script> first, build with relative paths for Chromium 103.

TypeScript types: rspulse.d.ts (in pulse-phone-sdk/ and in every example) declares window.RSPulse and every event, call and context field. In TypeScript, include it in your project; in plain JavaScript, put // @ts-check and /// <reference path="rspulse.d.ts" /> at the top of your script for editor hints (every example does).

Hot reload inside the phone. On your development server only:

  1. keep npm run dev running (the React template serves on http://127.0.0.1:5173/);
  2. register with devUrl = 'http://127.0.0.1:5173/' (the React template already does);
  3. add set pulse_dev_apps true to that server's server.cfg and restart the phone.

The phone then loads your app from the dev server, and every save shows in game at once. The console says so for each app; without the convar devUrl is ignored, so leaving it in your resource is harmless on a live server. devUrl must be http(s)://127.0.0.1 or localhost.

16. Troubleshooting

What you see Why, and the fix
The app is not on the phone The console says why at registration (add-on "x" rejected: …). No line at all: your resource started before the phone, or did not register on the phone's onResourceStart. Also check the app's job / items and Config.AppStore (allow, deny, jobs, paid apps).
refused: the id belongs to … Another running resource registered that id first. Pick your own id.
"App Didn't Load" The page did not load in 15 s: a wrong page.url, the file missing from files { }, or an external page that is down. Open the address in a browser.
A blank page, scripts not running A <script type="module"> (or a crossorigin stylesheet) without web: use classic scripts (the React template's build does), or declare web.
An embedded site stays blank The site forbids being shown inside other pages (X-Frame-Options / frame-ancestors), or you have no web capability, or the owner turned it off (context.capabilities).
Sound starts only after a tap, or full screen does nothing No media capability, or the owner turned it off. Check context.capabilities.media.
Sound keeps playing after leaving the app Only possible for sound outside the SDK's reach in an app without web / media (a player in an iframe): declare media, which makes the phone unload the app in the background.
The page loses its place when the player comes back Apps with web / media are unloaded in the background: save on pause, restore when context.restored is true.
A call rejects not-visible Your app is not the one on screen (it was closed, or the phone is locked).
Rejects not-declared / denied Declare the permission in RegisterApp; the player refused it - they change it in Settings › Apps.
Rejects unknown-app This player is not offered the app (job, grade, items, owner rules), or the app was unregistered.
Text or buttons under the camera on the Duo, or across the fold Use --rsp-safe-top and, open, the .split panes or --rsp-hinge-x / --rsp-hinge-width.
Colours look wrong on one handset Use the --rsp-* variables instead of fixed colours; check light and dark.
devUrl is ignored set pulse_dev_apps true is missing from server.cfg, or the address is not on this machine.
The page works in a browser but not in game The game's browser is Chromium 103: newer CSS or JavaScript does not run there. Build for chrome103.

phone_api in the server console prints the whole API. The client console (F8) shows a page's script errors.

17. API reference at a glance

Page (window.RSPulse)

Member Returns / does
ready, context, api, version, app the first context (Promise), the latest context, SDK level (1-3), rspulse.js version, your app id
on(name, fn) / off(name, fn) events: context, lifecycle, pause, resume, volume, call, back, deeplink, orientation, permission, capture, message, message:<event>, resize; on returns an unsubscribe function
lifecycle, volume, inCall, orientation, os, device, tokens the phone's state now
autoVolume, autoPause your own media follows the phone (default true)
send(event, payload), request(event, payload, { side }) your Lua (section 7)
notify, badge, open, home, haptic, sound section 2
pickContact, pickPhoto, alert, confirm, actionSheet, prompt, capturePhoto the phone's sheets (section 2)
activity.start / update / end one Island activity (section 2)
permissions.query / request, contacts.list, photos.list, location.get section 3
storage.get / set / remove / keys section 4
setOrientation(mode), fullscreen(on) turn the phone (orientation any / landscape)
back.enable(on), call(number, { video }), messages.compose({ to } \| { body }) section 14
devHandlers, devSdk, devSimulate(type, data) a plain browser only (section 2)

Server (exports.phone:…): RegisterApp, UnregisterApp, SendAppMessage / EmitApp, BroadcastApp, Notify, SetBadge, GetApps, Set, Get, GetPhoneNumber, SourceOfNumber, HasAppPermission, GetAppContacts, GetAppPhotos, GetAppLocation, GetAppRating, and the Island activity exports (EXPORTS.md section 14). Events: phone:app:<id>, phone:app:<id>:request, phone:app:<id>:permission, phone:appReviewed, phone:notification:action.

Client (exports.phone:…): SendAppMessage(appId, event, payload), IsAppOpen(appId); events phone:app:<id> (incl. open / close) and phone:app:<id>:request.