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.luafx_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 phoneC’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:readyse 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 unrestart 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
Section intitulée « 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
Section intitulée « 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 loadedconst 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 theseend)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
Section intitulée « 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 nullconst shot = await ask('camera.take'); // the same, from the real Cameraconst person = await ask('contacts.pick'); // { name, number } or nullawait 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 nullawait ask('share.photo', { url: photo.url });await ask('photos.save', { url: someImageUrl }); // → { id, width, height } or nullawait 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.
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 Walletexports.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 paylocal ok, tx = exports.mic_phone:Charge(src, 250, { title = 'Field Notes', detail = 'Pro upgrade' })
-- give it, and write the lineexports.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
Section intitulée « Se renseigner sur le téléphone »exports.mic_phone:RegisteredApps() --> every app registered on this client, and by whomexports.mic_phone:IsAppOpen('phonedemo') --> is it on screenexports.mic_phone:OpenAppId() --> which custom app is, or nilexports.mic_phone:OpenApp('phonedemo') --> open it, if the phone will open at allRegisteredApps 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
Section intitulée « 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.