Memulai

1. Instal paket

   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. Sinkronkan dengan proyek native

   npm

   npx cap sync

   pnpm

   pnpm cap sync

   yarn

   yarn cap sync

   bun

   bunx cap sync

Pengaturan iOS

Di iOS, akses kompas memerlukan izin lokasi. Tambahkan berikut ini ke Info.plist Anda:

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

Pengaturan Android

Tidak diperlukan pengaturan tambahan. Plugin menggunakan sensor magnetometer dan accelerometer perangkat.

Penggunaan

Impor plugin dan gunakan metodenya untuk membaca arah kompas:

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');
  }
};

Referensi API

getCurrentHeading()

Dapatkan arah kompas saat ini dalam derajat.

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

startListening()

Mulai mendengarkan perubahan arah kompas. Harus dipanggil sebelum event arah dipancarkan.

await CapgoCompass.startListening();

stopListening()

Berhenti mendengarkan perubahan arah kompas.

await CapgoCompass.stopListening();

addListener(‘headingChange’, callback)

Tambahkan listener untuk event perubahan arah.

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

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

removeAllListeners()

Hapus semua listener yang terdaftar.

await CapgoCompass.removeAllListeners();

checkPermissions()

Periksa status izin saat ini.

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

requestPermissions()

Minta izin untuk mengakses data kompas.

const status = await CapgoCompass.requestPermissions();

getPluginVersion()

Dapatkan versi plugin native.

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

Contoh Lengkap

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];
  }
}

Catatan Platform

iOS

• Memerlukan iOS 10.0+
• Menggunakan Core Location untuk data arah
• Memerlukan izin lokasi (NSLocationWhenInUseUsageDescription)
• Pembaruan arah berlanjut ketika listening aktif

Android

• Memerlukan Android 6.0 (API 23)+
• Menggunakan sensor accelerometer dan magnetometer
• Tidak diperlukan izin khusus untuk sensor kompas
• Arah dihitung dari fusi sensor

Web

• Tidak didukung di platform web
• Metode akan melempar error saat dipanggil