Geolocation Latar Belakang plugin Capacitor

Menggunakan @capgo/background-geolocation

Geolocation background yang akurat dan native geofencing untuk aplikasi Capacitor di iOS dan Android. Gunakan untuk streaming update lokasi presisi, memantau area melingkar, dan mengirim transisi enter/exit geofence ke JavaScript atau backend Anda.

Instal

bun add @capgo/background-geolocation
bunx cap sync

Apa yang Diekspos Plugin Ini

• start - Stream update lokasi foreground atau background yang akurat.
• stop - Hentikan pelacakan lokasi yang sedang aktif.
• openSettings - Buka pengaturan native saat user perlu memperbaiki izin lokasi.
• setPlannedRoute - Putar suara native saat user keluar dari rute yang direncanakan.
• setupGeofencing - Konfigurasi default geofence native dan pengiriman webhook transisi opsional.
• addGeofence - Monitor area geofence melingkar di iOS atau Android.
• removeGeofence / removeAllGeofences - Hentikan monitoring satu atau semua region yang terdaftar.
• getMonitoredGeofences - List identifier region yang sedang dimonitor.
• geofenceTransition listener - Terima event enter dan exit saat aplikasi aktif.
• geofenceError listener - Tangani error monitoring native secara terpisah dari event transisi.

Contoh Penggunaan

start

Panggil method ini untuk mulai memantau perubahan lokasi perangkat. Promise akan dikembalikan untuk menandakan pemanggilan selesai. Callback akan dipanggil setiap kali lokasi baru tersedia, atau jika terjadi error saat memanggil method ini. Jangan mengandalkan promise rejection untuk hal ini.

import { BackgroundGeolocation } from '@capgo/background-geolocation';

await BackgroundGeolocation.start(
  {
    backgroundMessage: "App is using your location in the background",
    backgroundTitle: "Location Service",
    requestPermissions: true,
    stale: false,
    distanceFilter: 10
  },
  (location, error) => {
    if (error) {
      console.error('Location error:', error);
      return;
    }
    if (location) {
      console.log('New location:', location.latitude, location.longitude);
    }
  }
);

stop

Hentikan update lokasi.

import { BackgroundGeolocation } from '@capgo/background-geolocation';

await BackgroundGeolocation.stop();

openSettings

Membuka halaman pengaturan lokasi perangkat. Berguna untuk mengarahkan pengguna agar mengaktifkan layanan lokasi atau menyesuaikan izin.

import { BackgroundGeolocation } from '@capgo/background-geolocation';

// Direct user to location settings
await BackgroundGeolocation.openSettings();

setPlannedRoute

Memutar file suara saat pengguna keluar dari rute yang direncanakan. Gunakan ini untuk memutar suara (termasuk di background, khusus untuk native).

import { BackgroundGeolocation } from '@capgo/background-geolocation';

await BackgroundGeolocation.setPlannedRoute({
  soundFile: "notification.mp3",
  route: [[-74.0060, 40.7128], [-118.2437, 34.0522]]
});

Geofencing Native

Pantau toko, lokasi kerja, zona pengiriman, kampus, atau area check-in dengan geofence native iOS dan Android. Tambahkan HTTP atau HTTPS url agar native code dapat melakukan POST transition payload saat WebView sedang suspend.

import { BackgroundGeolocation } from '@capgo/background-geolocation';

await BackgroundGeolocation.setupGeofencing({
  url: 'https://api.example.com/geofences',
  notifyOnEntry: true,
  notifyOnExit: true,
  payload: { userId: '123' },
});

await BackgroundGeolocation.addGeofence({
  identifier: 'warehouse',
  latitude: 40.7128,
  longitude: -74.006,
  radius: 200,
});

const listener = await BackgroundGeolocation.addListener(
  'geofenceTransition',
  (event) => console.log(event.identifier, event.transition),
);

const errorListener = await BackgroundGeolocation.addListener(
  'geofenceError',
  (event) => console.error(event.identifier, event.message),
);

await BackgroundGeolocation.removeGeofence({ identifier: 'warehouse' });
await listener.remove();
await errorListener.remove();

Pada Android, tambahkan ACCESS_BACKGROUND_LOCATION ke app manifest Anda hanya jika Anda membutuhkan background geofencing:

<uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />

Referensi Lengkap

• GitHub: https://github.com/Cap-go/capacitor-background-geolocation/
• Dokumentasi: /docs/plugins/background-geolocation/

Lanjut dari Menggunakan @capgo/background-geolocation

Jika Anda menggunakan Menggunakan @capgo/background-geolocation untuk merencanakan pekerjaan plugin native, hubungkan dengan @capgo/background-geolocation untuk detail implementasi di @capgo/background-geolocation, Panduan Memulai untuk detail implementasi di Getting Started, Direktori Plugin Capgo untuk alur kerja produk di Direktori Plugin Capgo, Plugin Capacitor oleh Capgo untuk detail implementasi di Plugin Capacitor oleh Capgo, dan Menambahkan atau Memperbarui Plugin untuk detail implementasi di bagian Menambahkan atau Memperbarui Plugin.