Device App Version#

The Device namespace provides access to information about the current device and its environment, including hardware characteristics, system details, screen metrics, battery status, orientation, proximity sensor state, locale and language settings, wake lock control, and network interfaces.

This API is commonly used to adapt UI layouts, behavior, and feature availability based on the device’s runtime context.

#Network state and changes

Device is a global namespace; it needs no import. You can also use import { Device } from "scripting" to access the same object. These methods run in an active main-app script.

import { Device, Dialog, Script } from "scripting"

const onChange = (state: Awaited<ReturnType<typeof Device.getNetworkState>>) => {
  console.log(state.status, state.interfaces, state.isExpensive, state.isConstrained)
}

try {
  const state = await Device.getNetworkState()
  console.log("Initial system path:", state)
  Device.addNetworkChangeListener(onChange)
  await Dialog.alert({
    title: "Network monitoring",
    message: "Change your Wi-Fi connection, then return here. Close this dialog to stop monitoring.",
  })
} catch (error) {
  console.error(error)
} finally {
  Device.removeNetworkChangeListener(onChange)
  Script.exit()
}

The snapshot contains:

getNetworkState() waits for an actual system path callback, with a 10-second timeout. A newly started monitor never reports a made-up initial offline value. A listener receives an asynchronous initial snapshot, then updates when these fields change; duplicate registration of the same function is ignored. removeNetworkChangeListener() without an argument removes all this Device object's network listeners. Listeners and pending queries are cleaned up when the script exits. Monitoring does not keep a script running in the background or guarantee delivery while suspended.

A satisfied path does not prove Internet, a particular TCP server, Bonjour or RSD is reachable. Test the operation itself. The API does not return SSID, cellular generation or airplane-mode settings. Device.networkInterfaces() remains the separate address-list API.

Queries reject with an error whose code identifies the failure: ERR_NETWORK_STATE_TIMEOUT (no initial system event), ERR_NETWORK_STATE_LIMIT (over 32 pending queries or 32 distinct listeners), ERR_PLATFORM_NOT_SUPPORTED (unsupported/inactive context), or ERR_PRO_REQUIRED (access denied). Listener registration can throw the same applicable access/limit errors and ERR_INVALID_ARG_TYPE. Removal remains available for cleanup. If access is revoked, the next update or call releases monitoring; no synthetic network-state callback is emitted for that error.

#Orientation

Represents the physical orientation of the device.

type Orientation =
  | "portrait"
  | "portraitUpsideDown"
  | "landscapeLeft"
  | "landscapeRight"
  | "faceUp"
  | "faceDown"
  | "unknown"

#Description

• portrait: Portrait orientation, default upright position
• portraitUpsideDown: Portrait orientation, upside down
• landscapeLeft: Landscape orientation rotated to the left
• landscapeRight: Landscape orientation rotated to the right
• faceUp: Device is lying flat with the screen facing upward
• faceDown: Device is lying flat with the screen facing downward
• unknown: Orientation cannot be determined

#InterfaceOrientation

Represents the supported interface orientations for the app.

type InterfaceOrientation =
  | "portrait"
  | "portraitUpsideDown"
  | "landscape"
  | "landscapeLeft"
  | "landscapeRight"
  | "all"
  | "allButUpsideDown"

#Description

• portrait: Portrait orientation, default upright position
• portraitUpsideDown: Portrait orientation, upside down
• landscape: Landscape orientation, either left or right
• landscapeLeft: Landscape orientation rotated to the left
• landscapeRight: Landscape orientation rotated to the right
• all: All supported orientations
• allButUpsideDown: All supported orientations except upside down

#NetworkInterface

Describes a single network interface address.

type NetworkInterface = {
  address: string
  netmask: string | null
  family: "IPv4" | "IPv6"
  mac: string | null
  isInternal: boolean
  cidr: string | null
}

#Properties

• address: IP address
• netmask: Subnet mask
• family: Address family, either IPv4 or IPv6
• mac: MAC address (may be null depending on system restrictions)
• isInternal: Indicates whether the interface is internal (for example, loopback)
• cidr: CIDR notation, such as 192.168.1.10/24

#BatteryState

Represents the current battery state.

type BatteryState = "full" | "charging" | "unplugged" | "unknown"

#Description

• full: Battery is fully charged
• charging: Device is currently charging
• unplugged: Device is not connected to power
• unknown: Battery state cannot be determined

#Device Information

#model

const model: string

The device model, such as "iPhone" or "iPad".

#localizedModel

const localizedModel: string

The localized name of the device model.

#appVersion / appBuildNumber

Readonly synchronous strings identifying the Scripting App, including when a script runs in an extension. appVersion reads CFBundleShortVersionString; appBuildNumber reads CFBundleVersion. Build numbers stay strings (they can contain dots or leading zeros). If the containing App cannot be read, the running bundle is used; a missing value is an empty string.

Device is an injected global, so no import is required. The existing import alias is also supported:

import { Device } from "scripting"
console.log(`Scripting ${Device.appVersion} (${Device.appBuildNumber})`)
console.log(`OS ${Device.systemVersion}`)

These values identify Scripting, independently of a script's own version and the OS version. They require no permission or network access.

#systemVersion

const systemVersion: string

The current operating system version, for example "18.2".

#systemName

const systemName: string

The name of the operating system, such as "iOS", "iPadOS", or "macOS".

#isiPad / isiPhone

const isiPad: boolean
const isiPhone: boolean

Indicates whether the current device is an iPad or an iPhone.

#screen

const screen: {
  width: number
  height: number
  scale: number
}

Screen metrics:

• width: Screen width in logical pixels
• height: Screen height in logical pixels
• scale: Screen scale factor (for example, 2 or 3)

#Battery and Sensors

#batteryState

const batteryState: BatteryState

The current battery state.

#batteryLevel

const batteryLevel: number

The current battery level, expressed as a value between 0.0 and 1.0.

#proximityState

const proximityState: boolean

The state of the proximity sensor. true indicates that the device is close to the user, such as during a phone call.

#Orientation and Layout

#isLandscape / isPortrait / isFlat

const isLandscape: boolean
const isPortrait: boolean
const isFlat: boolean

• isLandscape: Indicates whether the device is in a landscape orientation
• isPortrait: Indicates whether the device is in a portrait orientation
• isFlat: Indicates whether the device is lying flat (face up or face down)

#orientation

const orientation: Orientation

The current physical orientation of the device.

#supportedInterfaceOrientations

var supportedInterfaceOrientations: InterfaceOrientation[]

The list of supported interface orientations. You can set this property to limit the orientations that your page supports.

#Example

function Page() {
  useEffect(() => {
    Device.supportedInterfaceOrientations = ["all"]
    return () => {
      Device.supportedInterfaceOrientations = Device.userConfiguredInterfaceOrientations
    }
  }, [])
  return <VStack>...</VStack>
}

#userConfiguredInterfaceOrientations

const userConfiguredInterfaceOrientations: InterfaceOrientation[]

The list of interface orientations configured by the user. You can use this value to set supportedInterfaceOrientations to restore the default interface orientations.

#Appearance and Environment

#colorScheme

const colorScheme: ColorScheme

The current system color scheme, such as light or dark mode.

#isiOSAppOnMac

const isiOSAppOnMac: boolean

Indicates whether the current process is an iPhone or iPad app running on macOS.

#Locale and Language

#systemLocale

const systemLocale: string

The current system locale, for example "en_US".

#preferredLanguages

const preferredLanguages: string[]

The user’s preferred languages, for example:

["en-US", "zh-Hans-CN"]

#systemLocales (Deprecated)

const systemLocales: string[]

Deprecated. Use preferredLanguages instead.

#systemLanguageTag

const systemLanguageTag: string

The current language tag, such as "en-US".

#systemLanguageCode

const systemLanguageCode: string

The current language code, such as "en".

#systemCountryCode

const systemCountryCode: string | undefined

The current country code, such as "US".

#systemScriptCode

const systemScriptCode: string | undefined

The script code of the current locale, such as "Hans" for Simplified Chinese.

#Wake Lock

#isWakeLockEnabled

const isWakeLockEnabled: Promise<boolean>

Retrieves whether the wake lock is currently enabled, preventing the device from automatically sleeping.

#setWakeLockEnabled

function setWakeLockEnabled(enabled: boolean): void

Enables or disables the wake lock.

Notes:

• Available only in the Scripting app
• When enabled, the device will remain awake and not auto-lock

#Battery Listeners

#addBatteryStateListener

function addBatteryStateListener(
  callback: (state: BatteryState) => void
): void

Registers a listener for battery state changes.

#removeBatteryStateListener

function removeBatteryStateListener(
  callback?: (state: BatteryState) => void
): void

Removes a battery state listener. If callback is not provided, all battery state listeners are removed.

#addBatteryLevelListener

function addBatteryLevelListener(
  callback: (level: number) => void
): void

Registers a listener for battery level changes.

#removeBatteryLevelListener

function removeBatteryLevelListener(
  callback?: (level: number) => void
): void

Removes a battery level listener. If callback is not provided, all battery level listeners are removed.

#Orientation Listeners

#addOrientationListener

function addOrientationListener(
  callback: (orientation: Orientation) => void
): void

Starts observing device orientation changes.

Notes:

• This method must be called before orientation updates are delivered
• Orientation updates do not work when system orientation lock is enabled

#removeOrientationListener

function removeOrientationListener(
  callback?: (orientation: Orientation) => void
): void

Removes an orientation change listener. If callback is not provided, all orientation listeners are removed and observation is stopped.

#Proximity Listeners

#addProximityStateListener

function addProximityStateListener(
  callback: (state: boolean) => void
): void

Registers a listener for proximity sensor state changes.

#removeProximityStateListener

function removeProximityStateListener(
  callback?: (state: boolean) => void
): void

Removes a proximity state listener. If callback is not provided, all proximity listeners are removed.

#Network

#networkInterfaces

function networkInterfaces(): Record<string, NetworkInterface[]>

Returns the network interfaces available on the device.

Return value:

• Keys are interface names (such as en0, lo0)
• Values are arrays of NetworkInterface objects associated with each interface

This method is useful for network diagnostics, retrieving local IP addresses, and debugging connectivity issues.