Agency-Phone Apps Personalizados

🧩 Criar uma app própria para o Agency-Phone

Há duas maneiras de pôr uma app no telefone. Escolhe a que te serve:

Se distribuis uma app para outros servidores, usa o método A. Não precisa de código-fonte nosso e continua a funcionar depois das atualizações.

A SDK: registar uma app a partir do teu próprio resource

O agency-phone disponibiliza exports com que qualquer resource coloca, em tempo de execução, uma app com o seu próprio ícone no ecrã inicial do telefone. A interface da tua app fica no teu resource; o telefone mostra o ícone e passa-te o controlo quando o jogador lhe toca. Sem alterações ao agency-phone, sem build desbloqueado.

Exemplo mínimo

-- client side of YOUR resource
CreateThread(function()
    Wait(1500) -- let agency-phone boot
    exports['agency-phone']:RegisterApp({
        id        = 'myshop',
        label     = 'My Shop',
        icon      = 'fa-solid fa-cart-shopping', -- FontAwesome 6 class
        -- image  = 'https://cfx-nui-myresource/icon.png', -- or your own image instead
        color     = '#ff9500',
        colorDark = '#e08600',
    })
end)

-- fired when the player taps your icon on the phone
AddEventHandler('agency-phone:client:openApp', function(appId)
    if appId ~= 'myshop' then return end
    exports['agency-phone']:ClosePhone()
    -- open your own NUI here
end)

Configuração do RegisterApp

Exports do SDK (cliente)

O evento ao tocar

Quando o jogador toca no teu ícone, o agency-phone dispara estes dois eventos no cliente. Usa o que preferires:

Adiciona dependency 'agency-phone' ao teu fxmanifest.lua para a ordem de arranque estar certa.

B Drop-in, um ecrã nativo dentro do telefone

Para um ecrã desenhado pelo próprio telefone (não pelo teu resource). Isto altera ficheiros do agency-phone.

Os passos 3 e 4 estão em ficheiros cifrados pelo escrow, por isso um ecrã nativo precisa de um build com código-fonte ou desbloqueado. Se só tens a versão escrow, usa o método A (o teu ecrã fica no teu próprio resource). Ficheiros de referência dentro do resource: apps/testapp_client.lua e apps/dispatch_client.lua.

📋 Outros exports do telefone

Cliente

Servidor

⇄ Ponte NUI ↔ Lua (método B)

💳 Pagamento AgencyPay

Cobra na wallet do jogador a partir de qualquer resource.

exports['agency-phone']:StartAgencyPayCheckout({
    merchant = 'My Shop', title = 'Agency Pay', subtitle = 'Checkout',
    label = 'Premium Coffee', amount = 24.50,
    icon = 'fa-solid fa-mug-hot', accent = '#ff9f0a',
    clientEvent = 'myshop:client:agencyPayResult',
    serverEvent = 'myshop:server:agencyPayResult',
    metadata = { orderId = 'order_2048' },
})

RegisterNetEvent('myshop:client:agencyPayResult', function(result)
    if result.status == 'paid' then
        -- deliver the goods
    end
end)

O resultado inclui status (paid / cancelled / failed), amount, cardId, balance e os teus metadata.

Um paid que chega do cliente ao teu resource não prova nada por si só. Passa o teu próprio id a StartAgencyPayCheckout e chama exports['agency-phone']:VerifyAgencyPayCharge(source, id, amount) no servidor antes de entregares seja o que for. Só devolve true e o valor se este jogador pagou esse pagamento nos últimos 60 segundos, e consome o pagamento para que não possa ser reclamado duas vezes.

🐛 Resolução de problemas

Dúvidas ou precisas de ajuda? Junta-te ao Discord da Agency Scripts.