Table of Contents

• Maintainers
• Installation
• Permissions
• API
• Contributors

Maintainers

| Maintainer | GitHub | Active | | ---------- | --------------------------------------- | ------ | | robsonos | robsonos | yes |

Installation

npm install capacitor-community-device-orientation
npx cap sync

Permissions

Please check the sample permissions in Android and iOS folders.

• Android: No permissions are required. The output rate on Android is limited to 200Hz on devices running API level 31 (Android S) or higher, unless the android.permissions. HIGH_SAMPLING_RATE_SENSORS permission was added to your Manifest.xml.

• iOS: iOS requires the following keys to be added to your app's Info.plist file:

  • NSMotionUsageDescription: Required for accessing device motion data.
  • NSLocationWhenInUseUsageDescription: Required for aligning the compass with True North.

Power consideration

Always request the longest update period (lowest frequency) that is sufficient for your use case. While more frequent updates can be required for high precision tasks (for example Augmented Reality), it comes with a power cost. If you do not know which update period to use, we recommend starting with 'default' period as it fits most client needs.

API

• watchOrientation(...)
• clearWatch(...)
• Interfaces
• Type Aliases

watchOrientation(...)

watchOrientation(callback: DeviceOrientationWatchCallback, options?: DeviceOrientationOptions | undefined) => Promise<DeviceOrientationCallbackID>

Set up a listener to continuously receive device orientation updates.

On Android, this API returns a complete DeviceOrientationData object, including fused heading and attitude quaternion data from the FusedOrientationProviderClient for high accuracy.

On iOS, this API returns a DeviceOrientationData object containing orientation and attitude data. The fused property will be undefined.

On the Web, this API returns a partial DeviceOrientationData object containing only the orientation property (azimuth, pitch, roll) from the standard DeviceOrientationEvent API. The fused and attitude properties will be undefined. On iOS 13+, this will first prompt the user for permission.

| Param | Type | Description | | -------------- | ----------------------------------------------------------------------------------------- | --------------------------------------------------------- | | callback | DeviceOrientationWatchCallback | The function to call when a new orientation is available. | | options | DeviceOrientationOptions | Options for configuring the watch. |

Returns: Promise<string>

Since: 7.0.0

clearWatch(...)

clearWatch(options: DeviceOrientationClearWatchOptions) => Promise<void>

Remove a watch listener by its ID.

| Param | Type | Description | | ------------- | ------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- | | options | DeviceOrientationClearWatchOptions | The options object containing the ID of the watch to clear. |

Since: 7.0.0

Interfaces

DeviceOrientationData

A comprehensive object containing all available orientation data from a single device event.

| Prop | Type | Description | Since | | --------------------------- | ------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | ----- | | orientation | Orientation | The device's orientation expressed in Euler angles. This is available on all platforms. | 7.0.0 | | fused | FusedOrientation | The fused heading data, which includes corrections for True North. | 7.0.0 | | magneticFieldAccuracy | number | The accuracy of the magnetic field calibration. -1: Uncalibrated 0: Low 1: Medium 2: High | 7.2.0 | | attitude | Attitude | The raw attitude data as a quaternion. | 7.0.0 |

Orientation

Euler angles (Azimuth, Pitch, Roll) calculated from the raw device attitude.

| Prop | Type | Description | Since | | ------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- | | azimuth | number | The angle of rotation about the -z axis, in degrees. This value represents the angle between the device's y-axis and the north pole. The value is normalized to [0, 360] and is Clockwise (Compass style). - iOS: Relative to True North (requires location permissions). - Android: Relative to True North (if location is available), otherwise Magnetic North. | 7.0.0 | | pitch | number | The angle of rotation about the -x axis, in degrees. This value represents the angle between a plane parallel to the device's screen and a plane parallel to the ground. On Android and iOS, the range is [-90, 90]. Positive values indicate the top of the device is pointing down (towards the ground). Negative values indicate the top of the device is pointing up (towards the sky). | 7.0.0 | | roll | number | The angle of rotation about the y-axis, in degrees. This value represents the angle between a plane perpendicular to the device's screen and a plane perpendicular to the ground. On Android and iOS, the range is [-180, 180]. | 7.0.0 |

FusedOrientation

High-level, filtered heading data from the fused orientation provider.

| Prop | Type | Description | Since | | ------------------ | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ----- | | heading | number | The estimated heading of the device in degrees from [0, 360). Relative to True North if location is available), otherwise Magnetic North. | 7.0.0 | | headingError | number | The estimated error in the reported heading in degrees, from [0, 180]. This represents half the error cone. | 7.0.0 |

Attitude

The raw attitude of the device represented as a quaternion. On both Android and iOS, the quaternion represents the rotation from the East-North-Up (ENU) world reference frame to the device frame.

| Prop | Type | Description | Since | | ---------------- | ------------------------------------------------- | ------------------------------------------------------------------------ | ----- | | quaternion | Quaternion | The device's attitude, represented as a rotation vector in a quaternion. | 7.0.0 |

DeviceOrientationOptions

Options for configuring the orientation watch.

| Prop | Type | Description | Default | Since | | --------------- | -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- | ----- | | frequency | 'default' | 'medium' | 'fast' | The desired frequency of updates. - 'default': 50Hz / 20ms period, Recommended for users looking for a trade-off between lower battery usage and frequent orientation updates. - 'fast': 200Hz / 5ms period. This higher update is for users requiring a higher level of precision, at the cost of battery usage. - 'medium': 100Hz / 10ms period. This higher update frequency is for users requiring a higher level of precision, at the cost of battery usage. | 'default' | 7.0.0 |

DeviceOrientationClearWatchOptions

Options for the clearWatch method.

| Prop | Type | Description | Since | | -------- | ----------------------------------------------------------------------------------- | -------------------------------------------------------- | ----- | | id | DeviceOrientationCallbackID | The callback ID returned by watchOrientation to clear. | 7.0.0 |

Type Aliases

DeviceOrientationWatchCallback

The callback function to be invoked on each orientation update.

Quaternion

A 4-element array representing the [qx, qy, qz, qw] components of a quaternion.

[qx: number, qy: number, qz: number, qw: number]

DeviceOrientationCallbackID

A string identifier for a registered watch callback.

string

Errors

The plugin returns specific errors with specific codes on native Android. Web does not follow this standard for errors. The following table list all the plugin errors:

| Error code | Platform(s) | Message | | ------------ | ----------- | ------------------------------------- | | DEV-ORI-0001 | Android | Could not start orientation listener. | | DEV-ORI-0002 | Android | WatchId not found. | | DEV-ORI-0003 | Android | WatchId needs to be provided. |

There was en error trying to obtain the location.

Contributors