Cross-platform device events and queries.
Mob.Device is the single subscription point for OS-level events that exist
on both iOS and Android. The native side (iOS NotificationCenter,
Android ProcessLifecycleObserver) registers observers once at startup and
emits each event as a tagged tuple to a registered dispatcher pid; this
GenServer fans the events out to subscribers by category.
Subscribe
Mob.Device.subscribe() # default categories
Mob.Device.subscribe(:all) # everything
Mob.Device.subscribe([:app, :power])Subscribers receive {:mob_device, atom} or {:mob_device, atom, payload}
in their mailbox. Default categories are :app, :display, :audio, :memory.
Categories and events
:app—:will_resign_active,:did_become_active,:did_enter_background,:will_enter_foreground,:will_terminate:display—:screen_off,:screen_on:audio—:audio_interrupted,:audio_resumed,:audio_route_changed:appearance—{:color_scheme_changed, :light | :dark}:power—{:battery_state_changed, :unplugged | :charging | :full | :unknown},{:battery_level_changed, integer},{:low_power_mode_changed, boolean}:thermal—{:thermal_state_changed, :nominal | :fair | :serious | :critical}:memory—:memory_warning
Platform-specific events with no cross-platform counterpart go through
Mob.Device.IOS / Mob.Device.Android instead.
Queries
Mob.Device.battery_level() # 0..100 | -1 if unknown
Mob.Device.battery_state() # :unplugged | :charging | :full | :unknown
Mob.Device.thermal_state() # :nominal | :fair | :serious | :critical
Mob.Device.low_power_mode?() # boolean
Mob.Device.foreground?() # boolean
Mob.Device.os_version() # binary
Mob.Device.model() # binarySummary
Functions
Current battery level (0..100), or -1 if unknown.
Current battery state — :unplugged | :charging | :full | :unknown.
Returns the configured list of valid categories.
Returns a specification to start this module under a supervisor.
True if the app is currently in the foreground.
True if Low Power Mode (iOS) / Power Save Mode (Android) is on.
Device model (e.g. "iPhone", "Pixel 8").
Hands a URL to the OS to open in the default browser/handler.
OS version string (e.g. "17.4").
Start the dispatcher. Called from Mob.Application (or the app supervision
tree). After start, the registered NIF dispatcher pid is this GenServer.
Subscribe the calling process to device events.
Current thermal state — :nominal | :fair | :serious | :critical.
Unsubscribe the calling process from all categories.
Types
@type category() ::
:app | :display | :audio | :appearance | :power | :thermal | :memory
@type event() :: atom()
Functions
@spec battery_level() :: integer()
Current battery level (0..100), or -1 if unknown.
@spec battery_state() :: :unplugged | :charging | :full | :unknown
Current battery state — :unplugged | :charging | :full | :unknown.
@spec categories() :: [category()]
Returns the configured list of valid categories.
Returns a specification to start this module under a supervisor.
See Supervisor.
@spec foreground?() :: boolean()
True if the app is currently in the foreground.
@spec low_power_mode?() :: boolean()
True if Low Power Mode (iOS) / Power Save Mode (Android) is on.
@spec model() :: String.t()
Device model (e.g. "iPhone", "Pixel 8").
@spec open_url(String.t()) :: :ok
Hands a URL to the OS to open in the default browser/handler.
Fire-and-forget. Returns :ok immediately; failures (malformed URL, no
registered handler) are logged but not raised.
@spec os_version() :: String.t()
OS version string (e.g. "17.4").
@spec start_link(keyword()) :: GenServer.on_start()
Start the dispatcher. Called from Mob.Application (or the app supervision
tree). After start, the registered NIF dispatcher pid is this GenServer.
Subscribe the calling process to device events.
Accepts a single category atom, a list of categories, or :all.
Default is [:app, :display, :audio, :appearance, :memory].
Mob.Device.subscribe()
Mob.Device.subscribe(:thermal)
Mob.Device.subscribe([:app, :power, :thermal])
Mob.Device.subscribe(:all)@spec thermal_state() :: :nominal | :fair | :serious | :critical
Current thermal state — :nominal | :fair | :serious | :critical.
@spec unsubscribe() :: :ok
Unsubscribe the calling process from all categories.