Search documentation of mob

# Mob.Device (mob v0.6.18)

Copy Markdown View Source

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()              # binary

## Summary

### Types

category()
event()

### Functions

battery_level()

Current battery level (0..100), or -1 if unknown.

battery_state()

Current battery state — `:unplugged | :charging | :full | :unknown`.

categories()

Returns the configured list of valid categories.

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

foreground?()

True if the app is currently in the foreground.

low_power_mode?()

True if Low Power Mode (iOS) / Power Save Mode (Android) is on.

model()

Device model (e.g. "iPhone", "Pixel 8").

open_url(url)

Hands a URL to the OS to open in the default browser/handler.

os_version()

OS version string (e.g. "17.4").

start_link(opts \\ [])

Start the dispatcher. Called from `Mob.Application` (or the app supervision tree). After start, the registered NIF dispatcher pid is this GenServer.

subscribe(categories \\ [:app, :display, :audio, :appearance, :memory])

Subscribe the calling process to device events.

thermal_state()

Current thermal state — `:nominal | :fair | :serious | :critical`.

unsubscribe()

Unsubscribe the calling process from all categories.

## Types

# category()

    @type category() ::
      :app | :display | :audio | :appearance | :power | :thermal | :memory

# event()

    @type event() :: atom()

## Functions

# battery_level()

    @spec battery_level() :: integer()

Current battery level (0..100), or -1 if unknown.

# battery_state()

    @spec battery_state() :: :unplugged | :charging | :full | :unknown

Current battery state — `:unplugged | :charging | :full | :unknown`.

# categories()

    @spec categories() :: [category()]

Returns the configured list of valid categories.

# child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See `Supervisor`.

# foreground?()

    @spec foreground?() :: boolean()

True if the app is currently in the foreground.

# low_power_mode?()

    @spec low_power_mode?() :: boolean()

True if Low Power Mode (iOS) / Power Save Mode (Android) is on.

# model()

    @spec model() :: String.t()

Device model (e.g. "iPhone", "Pixel 8").

# open_url(url)

    @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.

# os_version()

    @spec os_version() :: String.t()

OS version string (e.g. "17.4").

# start_link(opts \\ [])

    @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(categories \\ [:app, :display, :audio, :appearance, :memory])

    @spec subscribe(category() | [category()] | :all) :: :ok

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)

# thermal_state()

    @spec thermal_state() :: :nominal | :fair | :serious | :critical

Current thermal state — `:nominal | :fair | :serious | :critical`.

# unsubscribe()

    @spec unsubscribe() :: :ok

Unsubscribe the calling process from all categories.