Client exports

Notifications and signal

Client exports that show a notification in the notebook and read the player's signal bars.

These exports run on the player's own client. To notify a player from the server, use the server [Notify](/phone/docs/pocketbook/exports/server/notifications-and-signal).

#Notify

Shows a notification in the notebook: a card on the open book, or the top of the closed book rising into view. The sending app's notification sound plays (Config.Notifications.SoundByApp) and its home icon gets a badge.

lua---@param data table { title, message, app?, offline?, kind?, icon?, duration?, progress? }
---@return boolean accepted
exports['fx-pocketbook']:Notify(data)
luaexports['fx-pocketbook']:Notify({
    title = 'Valentine Bank',
    message = 'Your savings account was opened.',
    app = 'bank',
    kind = 'money',
    offline = true,
})

Only title and message are required. Older calls with just those fields work unchanged. A field that is not valid is left out, never an error.

Field Type What it does
title string Required. Cut to 64 characters.
message string Required. Cut to 220 characters.
app string The sending app's id ('telegram', 'bank', 'billing', or your custom app's id): the card shows its name and drawn picture, plays its sound and badges its icon. Clicking the card opens the app. Lowercase letters, numbers and _, up to 32 characters. Every built-in app passes it.
offline boolean true shows it even without signal. Use it for things that do not come by telegraph, such as a paper in the pocket.
kind string 'info', 'success', 'warn', 'error', 'money', 'mail' or 'telegram': a quiet coloured ribbon on the card.
icon string An app id whose drawn picture the card shows instead of the sender's.
duration number Milliseconds on screen, 1500 to 15000. Default Config.Notifications.Duration.
progress number or false 0 to 1: a fixed line on the card, for a delivery or a timer. false: no line. Left out: the line runs out with the time.

Repeated notices are folded into one card instead of stacking:

  • The same app and kind again (three telegrams in a row): one card with the newest text and a "+2 new" count.
  • The same app and title without a kind (a volume step, a counter): the card on screen or in the queue is rewritten.
  • Returns false when the interface has not loaded, Config.Notifications.Enabled is false, title or message is not a string, or the waiting list is full.
  • When signal is on (Config.Signal.Enabled), offline is not true and the player has fewer than Config.Signal.ReceiveBars bars, the notification waits. Up to 50 wait per player. They are shown one by one when the signal comes back. The export still returns true.
  • The waiting list is cleared when the player switches character.

#GetSignal

Returns the player's signal bars.

lua---@return integer bars 0 to 5
exports['fx-pocketbook']:GetSignal()
lualocal bars = exports['fx-pocketbook']:GetSignal()
  • With Config.Signal.Enabled = false it is always 5.
  • The value comes from the server every Config.Signal.UpdateInterval milliseconds while the book is open and every Config.Signal.IdleInterval milliseconds while it is closed. If no answer arrives for three intervals it drops to 0 (6 seconds open, 30 seconds closed by default).
  • The [fx-pocketbook:signalChanged](/phone/docs/pocketbook/events/client-events) event fires when the bars or the town change and once after the book opens.

#CanUseOnline

Returns whether the signal is strong enough to send or to receive.

lua---@param operation 'send'|'receive'
---@return boolean ok
exports['fx-pocketbook']:CanUseOnline(operation)
luaif not exports['fx-pocketbook']:CanUseOnline('send') then
    return exports['fx-pocketbook']:Notify({ title = 'Telegraph', message = 'No line here.', offline = true })
end
  • 'receive' compares the bars with Config.Signal.ReceiveBars. Any other value compares them with Config.Signal.SendBars.
  • This is the player's own view. Decisions that matter (money, items) must use the server [CanUseOnline](/phone/docs/pocketbook/exports/server/notifications-and-signal).