Commencer

1. Installer the package

   npm

   npm i @capgo/capacitor-compass

   pnpm

   pnpm add @capgo/capacitor-compass

   yarn

   yarn add @capgo/capacitor-compass

   bun

   bun add @capgo/capacitor-compass

2. Synchroniser with Natif projects

   npm

   npx cap sync

   pnpm

   pnpm cap sync

   yarn

   yarn cap sync

   bun

   bunx cap sync

iOS Configuration

On iOS, compass access requires location permission. Add the following to your Info.plist:

<key>NSLocationWhenInUseUsageDescription</key>
<string>We need location permission to access the compass</string>

Android Configuration

No additional Configuration required. The plugin uses the Appareil’s magnetometer and accelerometer sensors.

Utilisation

Importer the plugin and use its methods to read compass heading:

import { CapgoCompass } from '@capgo/capacitor-compass';

// Get current heading once
const getCurrentHeading = async () => {
  const { value } = await CapgoCompass.getCurrentHeading();
  console.log('Current heading:', value, 'degrees');
};

// Start continuous heading updates
const startCompass = async () => {
  // Start listening for updates
  await CapgoCompass.startListening();

  // Add listener for heading changes
  const handle = await CapgoCompass.addListener('headingChange', (event) => {
    console.log('Heading:', event.value, 'degrees');
  });

  // Later, to stop listening:
  // await CapgoCompass.stopListening();
  // await handle.remove();
};

// Check permissions
const checkPermission = async () => {
  const status = await CapgoCompass.checkPermissions();
  console.log('Permission status:', status.compass);
};

// Request permissions
const requestPermission = async () => {
  const status = await CapgoCompass.requestPermissions();
  if (status.compass === 'granted') {
    console.log('Compass access granted');
  }
};

API Référence

getCurrentHeading()

Get the current compass heading in degrees.

const result = await CapgoCompass.getCurrentHeading();
// Returns: { value: number } - heading in degrees (0-360)

startListening()

Démarrer listening for compass heading changes. Must be called before heading events are emitted.

await CapgoCompass.startListening();

stopListening()

Arrêter listening for compass heading changes.

await CapgoCompass.stopListening();

addListener(‘headingChange’, callback)

Ajouter a listener for heading change events.

const handle = await CapgoCompass.addListener('headingChange', (event) => {
  console.log('Heading:', event.value);
});

// Remove listener when done
await handle.remove();

removeAllListeners()

Retirer all registered listeners.

await CapgoCompass.removeAllListeners();

checkPermissions()

Vérifier current permission status.

const status = await CapgoCompass.checkPermissions();
// Returns: { compass: 'prompt' | 'granted' | 'denied' }

requestPermissions()

Request permission to access compass data.

const status = await CapgoCompass.requestPermissions();

getPluginVersion()

Get the Natif plugin Version.

const { version } = await CapgoCompass.getPluginVersion();

Terminé Exemple

import { CapgoCompass } from '@capgo/capacitor-compass';

export class CompassService {
  private listenerHandle: any = null;

  async init() {
    // Check and request permissions
    const status = await CapgoCompass.checkPermissions();
    if (status.compass !== 'granted') {
      const result = await CapgoCompass.requestPermissions();
      if (result.compass !== 'granted') {
        throw new Error('Compass permission denied');
      }
    }
  }

  async startTracking(onHeadingChange: (heading: number) => void) {
    // Start listening for updates
    await CapgoCompass.startListening();

    // Add event listener
    this.listenerHandle = await CapgoCompass.addListener(
      'headingChange',
      (event) => {
        onHeadingChange(event.value);
      }
    );
  }

  async stopTracking() {
    if (this.listenerHandle) {
      await this.listenerHandle.remove();
      this.listenerHandle = null;
    }
    await CapgoCompass.stopListening();
  }

  async getHeading(): Promise<number> {
    const { value } = await CapgoCompass.getCurrentHeading();
    return value;
  }

  getCardinalDirection(heading: number): string {
    const directions = ['N', 'NE', 'E', 'SE', 'S', 'SW', 'W', 'NW'];
    const index = Math.round(heading / 45) % 8;
    return directions[index];
  }
}

Platform Notes

iOS

• Requires iOS 10.0+
• Uses Core Location for heading data
• Requires location permission (NSLocationWhenInUseUsageDescription)
• Heading Mises à jour are continuous when listening is Actif

Android

• Requires Android 6.0 (API 23)+
• Uses accelerometer and magnetometer sensors
• No special permissions required for compass sensors
• Heading is calculated from sensor fusion

Web

• Not supported on web platform
• Methods will throw errors when called