Votre propre application dessus

Un exemple fonctionnel se trouve dans example/mic_phone_demo. Copiez le dossier, modifiez les noms, et vous avez une application.

my_app/
  fxmanifest.lua
  client.lua          registers the app
  server.lua          anything that touches money or the database
  ui/index.html       your page
  ui/icon.svg         your icon

-- fxmanifest.lua
fx_version 'cerulean'
game 'gta5'

client_script 'client.lua'
server_script 'server.lua'

files {                  -- WITHOUT THIS your page and icon are not served and the frame comes up blank
    'ui/index.html',
    'ui/icon.svg',
}

Le bloc files est l’élément que tout le monde oublie. FiveM ne sert que ce qu’une ressource déclare dans cette liste, donc une page qui n’y figure pas répond par une 404 et votre application s’ouvre sur un cadre blanc.

local function register()
    exports.mic_phone:AddApp({
        id   = 'phonedemo',
        name = 'Field Notes',
        icon = ('https://cfx-nui-%s/ui/icon.svg'):format(GetCurrentResourceName()),
        ui   = ('%s/ui/index.html'):format(GetCurrentResourceName()),
    })
end

AddEventHandler('mic_phone:ready', register)   -- fires on start, and after every restart of the phone

C’est l’intégralité du contrat, et il n’y a rien de plus : rien n’est configuré sur le téléphone, et rien n’est redémarré. Démarrez votre ressource et l’application apparaît sur l’écran d’accueil — default = true la place directement là, default = false la place dans l’App Store. Dans les deux cas, la décision vous appartient, dans votre propre fichier.

Config.AppList.Custom existe pour qu’un propriétaire de serveur puisse prévaloir sur vos choix — tarifer votre application, l’offrir préinstallée ou la désactiver. Il n’est jamais requis pour que votre application fonctionne.

Quatre contraintes que vous n’avez pas à subir, contrairement à d’autres téléphones :

• Vous n’avez pas à supprimer l’application avant de la rajouter. Enregistrer le même ID depuis la même ressource la met à jour. Seule une ressource différente revendiquant un ID déjà attribué est refusée, avec indication du motif.
• Vous n’avez pas à attendre le téléphone. mic_phone:ready se déclenche lorsqu’il est prêt à recevoir des applications et à nouveau après chaque redémarrage, votre application revient donc d’elle-même après un restart mic_phone.
• Vous n’avez pas à nettoyer lors de l’arrêt de votre ressource. Vos applications partent avec elle. Un script arrêté ne laisse jamais derrière lui une icône inactive.
• Vous n’avez pas à redémarrer le téléphone. Une application enregistrée pendant qu’un joueur tient son téléphone en main apparaît dessus instantanément.

Ce qu’une application peut déclarer sur elle-même

id	lettres, chiffres, _ et -. Unique sur l’ensemble du serveur
name	nom affiché sous l’icône
subtitle, description, features, version	la page sur l’App Store
developer, category	affichés dans l’App Store
color	couleur de fond de l’icône lorsqu’aucune image icon n’est fournie
icon	une URL. https://cfx-nui-<resource>/path.png la sert depuis votre propre dossier
ui	resource/path/index.html, la page de votre application. À omettre pour une app 100 % Lua. Un chemin interne à une ressource de ce serveur, jamais une URL externe — voir ci-dessous
landscape	indique que la page nécessite le téléphone déplié en tablette
size, images	éléments affichés sur la page App Store. Les images doivent être en https://
default	true la dépose directement sur l’écran d’accueil au lieu de l’App Store
onOpen, onClose	fonctions appelées à l’ouverture et à la fermeture

Vous ne pouvez pas fixer votre propre prix. Il n’y a pas de champ price, et c’est volontaire : cette valeur résiderait côté client, et un prix déclaré par le client est un prix manipulable par le client — l’App Store afficherait un montant et le serveur ne prélèverait rien. La tarification est du ressort de Config.AppList.Custom, écrit par le propriétaire du serveur et lu par le serveur. Si vous souhaitez que votre application soit payante, demandez-lui d’ajouter une ligne ; cela ne prend qu’une ligne.

La ville a le dernier mot. Tout ce que vous demandez ici constitue une suggestion. Config.AppList.Custom dans la configuration du téléphone peut tarifer votre application, la distribuer préinstallée ou la désactiver totalement, sans que personne n’ait à modifier votre ressource. C’est délibéré — un gestionnaire de serveur ne devrait pas avoir à forker un script pour le faire payer.

Communiquer avec votre page

Votre page est une iframe. Elle ne peut pas pénétrer dans le téléphone, lire les messages ni dessiner hors de son rectangle ; le téléphone ne peut pas non plus pénétrer dans votre iframe. Tout s’échange par messages.

ui doit être un chemin vers une ressource située sur ce serveur. Une frame a besoin que la Content-Security-Policy de la page autorise son origine, et les CSP ne permettent pas d’écrire “n’importe quelle ressource cfx-nui-” — les jokers ne sont autorisés que sur le sous-domaine le plus à gauche, donc https://cfx-nui-* ne peut pas être formulé et la directive doit être ouverte à https: pour que votre frame puisse charger. C’est vaste, alors le téléphone restreint cela de l’autre côté : il construit lui-même l’origine d’après le chemin de votre ressource et rejette tout ce qui se présente déjà comme une URL. Si vous souhaitez héberger votre page, faites-le depuis votre propre ressource.

Dans votre page, deux lignes :

parent.postMessage({ type: 'phone:ready' }, '*');                       // say you have loaded
const send = m => parent.postMessage({ type: 'phone:message', message: m }, '*');

et écoutez :

window.addEventListener('message', e => {
  if (e.data?.type === 'phone:theme')   document.documentElement.dataset.theme = e.data.theme;
  if (e.data?.type === 'phone:message') { /* from your Lua */ }
});

Dans votre script Lua :

exports.mic_phone:SendAppMessage('phonedemo', { kind = 'hello' })

AddEventHandler(GetCurrentResourceName() .. ':phone:message', function(message)
    -- from your page. Routed here by the resource that owns the app, so nothing else can send these
end)

Envoyez ce que vous voulez depuis onOpen. Un message destiné à une page qui n’a pas encore fini de charger attend sagement et arrive dans l’ordre dès que celle-ci émet phone:ready. D’autres téléphones déconseillent cette pratique car leurs messages entrent en concurrence avec le chargement de la frame ; ici ce n’est pas le cas, car envoyer des données à l’ouverture de l’application est la démarche la plus naturelle qui soit, et ce qui est naturel doit fonctionner.

phone:theme est transmis avec le mode light/dark du téléphone et sa langue lorsque votre page signale sa disponibilité. Suivez ces valeurs et votre application cessera de ressembler à un site web plaqué artificiellement.

Demander un service au téléphone

Votre page peut demander au téléphone d’exécuter des actions qu’il maîtrise déjà — afficher une notification, ouvrir l’appareil photo, faire choisir une photo ou un contact. Quinze lignes initialisent le système, puis chaque requête se résume à un simple await :

let next = 1; const waiting = new Map();
const ask = (what, args) => new Promise(resolve => {
  const id = next++; waiting.set(id, resolve);
  parent.postMessage({ type: 'phone:ask', id, what, with: args || {} }, '*');
});
window.addEventListener('message', e => {
  if (e.data?.type === 'phone:answer') { const done = waiting.get(e.data.id); if (done) { waiting.delete(e.data.id); done(e.data.value); } }
});

const me      = await ask('me');              // { number, name }
const photo   = await ask('photos.pick');     // { id, url, width, height } or null
const shot    = await ask('camera.take');     // the same, from the real Camera
const person  = await ask('contacts.pick');   // { name, number } or null
await ask('notify', { title: 'Field Notes', body: 'Something happened.' });
await ask('toast',  { text: 'Saved.' });
const look    = await ask('theme');           // { theme, language, tablet }
await ask('close');                           // put yourself away

Demande	Ce qui est renvoyé
me	{ number, name }	ce que les autres téléphones voient déjà, et rien d’autre sur la personne
notify	true	classé sous votre application, ainsi la mettre en sourdine dans les Paramètres vous met en sourdine
toast	true	un bandeau discret en bas de l’écran
photos.pick	une photo, ou null	ouvre la galerie du téléphone ; null signifie fermeture sans choix
camera.take	une photo, ou null	ouvre l’Appareil photo en plein jeu, attend et vous ramène sur l’app
contacts.pick	un contact, ou null	ouvre un volet de sélection de contacts
theme	{ theme, language, tablet }	les mêmes valeurs que celles poussées par phone:theme
close	true	revient à l’écran d’accueil

Et le volet qui permet d’interagir activement avec le téléphone :

await ask('message.compose', { number: '555-0110', text: 'Your order is ready.' });
await ask('call.start',      { number: '555-0110' });
await ask('share.text',      { text: 'Look at this.' });   // → { to, number } or null
await ask('share.photo',     { url: photo.url });
await ask('photos.save',     { url: someImageUrl });       // → { id, width, height } or null
await ask('waypoint.set',    { x: 219, y: -855 });
const money = await ask('money.balance');                  // { balance }

Demande	Ce qui est renvoyé
message.compose	true	ouvre Messages avec le texte prérempli. Un joueur appuie sur envoyer
call.start	true	compose et appelle le numéro
share.text / share.photo	{ to, number }, ou null	ouvre un sélecteur, puis prépare l’envoi vers le destinataire choisi
photos.save	{ id, width, height }	enregistre une image générée par votre app dans Photos
waypoint.set	true	place un repère GPS sur la carte
money.balance	{ balance }	lecture seule — l’argent se déplace côté serveur, voir ci-dessous

Rien n’est jamais envoyé au nom d’un joueur à son insu. message.compose remplit le champ de saisie et confie le bouton d’envoi à l’humain ; le partage demande systématiquement le destinataire. Une application capable d’envoyer des SMS à vos contacts en secret serait bien pire qu’une application dépourvue d’envoi de messages.

Argent

L’argent est manipulé côté serveur, depuis votre propre script serveur, car un prix contestable par un client n’est pas un prix. Trois fonctions sont proposées, selon l’entité ayant réalisé le mouvement :

-- somebody else already took the money; this only writes the line in the Wallet
exports.mic_phone:AddTransaction(src, { title = 'Tequi-la-la', detail = 'Two drinks', amount = -40 })

-- take it, and write the line. false, 'funds' and nothing moved when they cannot pay
local ok, tx = exports.mic_phone:Charge(src, 250, { title = 'Field Notes', detail = 'Pro upgrade' })

-- give it, and write the line
exports.mic_phone:Pay(src, 1000, { title = 'Delivery', detail = 'Job finished' })

exports.mic_phone:GetBalance(src)

Toutes trois mettent à jour le Portefeuille à l’écran instantanément. Charge et Pay réussissent intégralement ou échouent intégralement : un prélèvement refusé laisse le solde et l’historique dans leur état d’origine.

Deux principes fondamentaux justifient la concision de cette API :

Votre application ne reçoit jamais de données qu’on ne lui a pas explicitement données. contacts.pick ne renvoie pas le carnet d’adresses — il ouvre un volet, le joueur sélectionne un nom, et seul ce nom est renvoyé. Interroger en boucle ne permet pas de siphonner le répertoire ; chaque réponse requiert une action utilisateur. Il en va de même pour les photos.

Seule l’application à l’écran a le droit de poser une question. Une demande provenant d’une frame qui n’est pas l’application actuellement ouverte n’obtient aucune réponse et n’ouvre rien ; une page laissée en arrière-plan ne peut donc pas agir pendant que le joueur fait autre chose.

Si ce dont vous avez besoin ne figure pas dans cette liste, ce n’est pas un refus du téléphone — c’est simplement que personne ne l’a encore ajouté. En ajouter une consiste en une entrée dans PHONE_APP_ASKS au sein de html/apps/store/app-api.js, rien de plus.

Se renseigner sur le téléphone

exports.mic_phone:RegisteredApps()        --> every app registered on this client, and by whom
exports.mic_phone:IsAppOpen('phonedemo')   --> is it on screen
exports.mic_phone:OpenAppId()             --> which custom app is, or nil
exports.mic_phone:OpenApp('phonedemo')     --> open it, if the phone will open at all

RegisteredApps est l’export à consulter lorsque votre application n’apparaît pas. La commande serveur phoneapps affiche ce que prévoit la configuration, ce qui représente une liste différente — votre application réside sur le client qui l’a enregistrée, et n’apparaît dans phoneapps que si une entrée lui a été consacrée dans Config.AppList.Custom.

Une application qui n’est ni en default = true ni marquée comme installed dans la configuration attend dans l’App Store que quelqu’un la télécharge. Si la vôtre est bien enregistrée mais introuvable sur l’écran d’accueil, c’en est généralement la cause.

En cas de dysfonctionnement

Ce que vous constatez	Presque toujours
L’application n’est nulle part	Consultez d’abord RegisteredApps(). Si elle n’y figure pas, AddApp a été rejeté — la raison est inscrite dans la console client (F8), et non serveur
Elle est enregistrée mais absente de l’accueil	Elle se trouve dans l’App Store : vous avez défini default = false, ou le gestionnaire a mis How = 'store' dans Config.AppList.Custom
L’application s’ouvre sur une page blanche	Votre fichier ui n’est pas répertorié dans le bloc files de votre fxmanifest
Refused to frame dans la console	Votre ui est une URL. Ce doit être un chemin vers une ressource située sur ce serveur
La page charge, mais les messages n’arrivent pas	Votre page n’a jamais envoyé phone:ready. Rien n’est délivré tant qu’elle ne l’a pas fait — les messages patientent et arrivent tous à l’envoi de ce signal
no answer in 12000ms	Vous avez sollicité une action inexistante sur le téléphone. Vérifiez le nom avec la liste ci-dessus

phoneapps sur le serveur affiche la configuration et non votre application — une application enregistrée par une ressource vit sur le client qui l’a déclarée, et n’y apparaît que si une entrée Config.AppList.Custom existe. exports.mic_phone:RegisteredApps() fournit la liste réellement présente sur cette machine.

Le reste de l’API du téléphone — state bags, appels, contacts, notifications — est disponible sur la page Exports et state bags.