Applications personnalisées

Une ressource peut ajouter une application avec sa propre interface NUI. Elle reste propriétaire de l'application qu'elle enregistre : une autre ressource ne peut ni la supprimer ni lui envoyer de message.

Structure minimale

Dans le fxmanifest.lua de votre ressource :

fx_version 'cerulean'
game 'gta5'

client_script 'client.lua'

files {
    'ui/index.html',
    'ui/app.js',
    'ui/style.css',
    'ui/klm-favicon.png?v=20261013-logos2'
}

Dans client.lua, enregistrez l'application après le démarrage de zs-phone :

local APP_ID <const> = 'my_app'

local function registerApp()
    local ok, reason = exports['zs-phone']:AddCustomApp({
        identifier = APP_ID,
        name = 'Mon application',
        description = 'Description affichée dans l’App Store',
        ui = 'my-resource/ui/index.html',
        icon = 'ui/klm-favicon.png?v=20261013-logos2',
        developer = 'Mon serveur',
        defaultApp = false,
        images = {},
        size = 128,
        price = 0,
        landscape = false,
        fixBlur = false,
        keepOpen = false,
        game = false,
        onOpen = function() print('app ouverte') end,
        onClose = function() print('app fermée') end,
        onInstall = function() print('app installée') end,
        onDelete = function() print('app supprimée') end
    })

    if not ok then
        print(('Impossible d’ajouter %s : %s'):format(APP_ID, reason))
    end
end

AddEventHandler('onClientResourceStart', function(resource)
    if resource == 'zs-phone' or resource == GetCurrentResourceName() then
        CreateThread(function()
            while GetResourceState('zs-phone') ~= 'started' do Wait(250) end
            registerApp()
        end)
    end
end)

Propriétés

Champ	Obligatoire	Description
`identifier`	✅	Identifiant unique et stable
`name`	✅	Nom visible
`ui`	✅	Page HTML relative à la ressource
`description`		Description App Store
`icon`		URL ou chemin relatif de l'icône
`defaultApp`		Installée sans passage par l'App Store
`developer`		Auteur visible
`images`		Captures de présentation
`size`		Taille affichée
`price`		Prix de téléchargement
`landscape`		Interface en mode paysage
`fixBlur`		Ajustement du flou de fond
`keepOpen`		Conserve le téléphone ouvert
`game`		Classe l'application dans les jeux

Les callbacks client disponibles sont onUse, onOpen, onClose, onInstall et onDelete.

Utilitaires dans l'interface

Ajoutez le script de composants à votre HTML :

<script src="https://cfx-nui-zs-phone/ui/components.js"></script>
<script src="app.js"></script>

Les fonctions actuellement prises en charge sont :

fetchNui(event, data, scriptName?) ;
onNuiEvent(eventName, callback) ;
SetPopUp(data) ;
SetContextMenu(data) ;
GetSettings() et OnSettingsChange(callback) ;
SendNotification(data) ;
CreateCall(data).

Les sélecteurs Galerie, GIF, Emoji, Caméra, Couleur et Contacts sont présents comme interfaces de compatibilité mais ne sont pas encore implémentés. Ne les utilisez pas comme dépendance de production.

Messages Lua vers l'interface

exports['zs-phone']:SendCustomAppMessage('my_app', {
    action = 'refresh',
    entries = { 'A', 'B' }
})

Dans app.js :

onNuiEvent('customApp:message', function (payload) {
    if (payload.action === 'refresh') {
        console.log(payload.entries)
    }
})

Suppression et redémarrage

local ok, reason = exports['zs-phone']:RemoveCustomApp('my_app')

Seule la ressource ayant appelé AddCustomApp peut supprimer l'application ou lui envoyer un message. Lorsque cette ressource s'arrête, zs-phone retire automatiquement toutes ses applications du registre en mémoire.

Bonnes pratiques

Utilisez un identifiant en minuscules, préfixé par votre ressource.
Réenregistrez l'application quand zs-phone redémarre.
Validez toutes les données NUI côté Lua puis côté serveur.
N'envoyez jamais de secret ou de clé d'API dans l'iframe.
Appelez RemoveCustomApp lors d'une désactivation volontaire.