@abennouna/capacitor-compass-accuracy

A Capacitor plugin for Android to monitor the accuracy of the device compass.

This is a port of the cordova-plugin-compass-accuracy plugin to Capacitor.

Platform Support

• ✅ Android: Full support (reports sensor accuracy changes)
• ⚠️ iOS: Not needed - iOS automatically calibrates the compass using the motion coprocessor since iPhone 5S and iOS 13
• ⚠️ Web: Not supported - compass accuracy monitoring is not available on web

Installation

npm install @abennouna/capacitor-compass-accuracy
npx cap sync

API

Interfaces

AccuracyLevel

Enum indicating the required or current accuracy of the device compass:

• HIGH - High accuracy (less than 5 degrees of error)
• MEDIUM - Medium accuracy (less than 10 degrees of error)
• LOW - Low accuracy (less than 15 degrees of error)
• UNRELIABLE - Unreliable accuracy (more than 15 degrees of error)
• UNKNOWN - Unknown accuracy value

ResultType

Enum indicating the type of result being returned:

• STARTED - Monitor has been started and the current accuracy is being returned
• ACCURACY_CHANGED - Accuracy has changed and the new accuracy is being returned

AccuracyChangeResult

interface AccuracyChangeResult {
  type: ResultType;
  currentAccuracy: AccuracyLevel;
  requiredAccuracy: AccuracyLevel;
  previousAccuracy?: AccuracyLevel;
  isInaccurate?: boolean;
}

Methods

startMonitoring(options, callback)

Starts monitoring the accuracy of the device compass for the required accuracy level.

• This plugin does not show any native UI. Your app is responsible for reacting to insufficient accuracy.
• The callback will be invoked when monitoring starts and whenever accuracy changes

import { CompassAccuracy, AccuracyLevel } from '@abennouna/capacitor-compass-accuracy';

const callbackId = await CompassAccuracy.startMonitoring(
  { requiredAccuracy: AccuracyLevel.HIGH },
  (result, error) => {
    if (error) {
      console.error('Error:', error);
      return;
    }
    
    if (result) {
      console.log('Type:', result.type);
      console.log('Current Accuracy:', result.currentAccuracy);
      console.log('Required Accuracy:', result.requiredAccuracy);
    }
  }
);

Parameters:

• options: StartMonitoringOptions - Configuration options
  • requiredAccuracy: AccuracyLevel (optional) - Required accuracy level (defaults to HIGH)
• callback: (result, error) => void - Callback function that receives accuracy updates

Returns: Promise<string> - Callback ID for the monitoring session

stopMonitoring()

Stops monitoring the accuracy of the device compass.

await CompassAccuracy.stopMonitoring();

Returns: Promise<void>

getCurrentAccuracy()

Gets the current accuracy of the device compass.

const result = await CompassAccuracy.getCurrentAccuracy();
console.log('Current Accuracy:', result.currentAccuracy);

Returns: Promise<{ currentAccuracy: AccuracyLevel }>

simulateAccuracyChange(options)

Simulates a change in compass accuracy. This method is intended for testing only.

await CompassAccuracy.simulateAccuracyChange({ 
  accuracy: AccuracyLevel.LOW 
});

Parameters:

• options: { accuracy: AccuracyLevel } - The simulated accuracy level

Returns: Promise<void>

Usage Example

import { CompassAccuracy, AccuracyLevel, ResultType } from '@abennouna/capacitor-compass-accuracy';

// Start monitoring with high accuracy requirement
const startMonitoring = async () => {
  try {
    const callbackId = await CompassAccuracy.startMonitoring(
      { requiredAccuracy: AccuracyLevel.HIGH },
      (result, error) => {
        if (error) {
          console.error('Monitoring error:', error);
          return;
        }

        if (result) {
          const action = result.type === ResultType.STARTED ? 'started as' : 'changed to';
          console.log(`Compass accuracy ${action}: ${result.currentAccuracy}`);
          console.log(`Required accuracy: ${result.requiredAccuracy}`);
          
          // Handle insufficient accuracy in your app (UI/UX is out of scope of this plugin)
        }
      }
    );
    
    console.log('Monitoring started with callback ID:', callbackId);
  } catch (error) {
    console.error('Failed to start monitoring:', error);
  }
};

// Stop monitoring
const stopMonitoring = async () => {
  try {
    await CompassAccuracy.stopMonitoring();
    console.log('Monitoring stopped');
  } catch (error) {
    console.error('Failed to stop monitoring:', error);
  }
};

// Get current accuracy without starting monitoring
const checkAccuracy = async () => {
  try {
    const result = await CompassAccuracy.getCurrentAccuracy();
    console.log('Current compass accuracy:', result.currentAccuracy);
  } catch (error) {
    console.error('Failed to get accuracy:', error);
  }
};

How It Works

The plugin monitors the Android magnetometer sensor's accuracy events and reports changes back to JavaScript.

The plugin does not show any native UI. Your app is responsible for deciding how to react when accuracy is insufficient.

Differences from Cordova Plugin

This Capacitor plugin maintains API compatibility with the original Cordova plugin, with these differences:

• Uses Capacitor's plugin architecture instead of Cordova's
• Written in TypeScript for better type safety
• Uses modern Promise-based APIs while maintaining callback support for monitoring
• Simplified installation process (no plugin.xml)

License

MIT License

Copyright (c) 2026 Abdelaziz Bennouna (Tellibus)

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.