ガイド
Capacitor で Background Geolocation を使う方法
@capgo/background-geolocation の使い方
iOS および Android の Capacitor アプリ向けに、高精度なバックグラウンド位置情報取得とネイティブのジオフェンシングを提供します。正確な位置情報のストリーミング、特定のエリアの監視、ジオフェンスの出入り検知を JavaScript やバックエンドへ通知できます。
インストール
bun add @capgo/background-geolocation
bunx cap sync
このプラグインで利用可能な機能
start- フォアグラウンドまたはバックグラウンドで正確な位置情報更新をストリーム配信。stop- アクティブな位置情報トラッキングを停止。openSettings- ユーザーが位置情報の権限を修正する必要があるときにネイティブ設定を開く。setPlannedRoute- 予定ルートから外れた際にネイティブサウンドを再生。setupGeofencing- ネイティブのジオフェンスのデフォルト設定と、オプションの遷移Webhook配信を設定。addGeofence- iOSまたはAndroidの円形ジオフェンス領域を監視。removeGeofence/removeAllGeofences- 登録済みの1つまたはすべての領域の監視を停止。getMonitoredGeofences- 監視中の領域識別子をリスト表示。geofenceTransitionlistener - アプリがアクティブな間にenterおよびexitイベントを受信。geofenceErrorlistener - ネイティブの監視エラーを遷移イベントとは別に処理。
使用例
start
デバイスの位置情報の変更を監視するには、このメソッドを呼び出します。呼び出しの完了を示す Promise が返されます。新しい位置情報が取得された際、またはメソッド呼び出し時にエラーが発生した際にコールバックが実行されます。エラーハンドリングに Promise の rejection は使用しないでください。
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
位置情報の更新を停止します。
import { BackgroundGeolocation } from '@capgo/background-geolocation';
await BackgroundGeolocation.stop();
openSettings
デバイスの位置情報設定画面を開きます。ユーザーに位置情報サービスを有効にさせたり、権限を調整させたりする場合に便利です。
import { BackgroundGeolocation } from '@capgo/background-geolocation';
// Direct user to location settings
await BackgroundGeolocation.openSettings();
setPlannedRoute
ユーザーが予定ルートから外れた際にサウンドファイルを再生します。サウンドの再生（ネイティブ環境ではバックグラウンド再生も含む）に使用してください。
import { BackgroundGeolocation } from '@capgo/background-geolocation';
await BackgroundGeolocation.setPlannedRoute({
soundFile: "notification.mp3",
route: [[-74.0060, 40.7128], [-118.2437, 34.0522]]
});
ネイティブのジオフェンシング
iOS および Android のネイティブなジオフェンスを使用して、店舗、現場、配送エリア、キャンパス、チェックインエリアなどを監視します。HTTP または HTTPS を追加して、 url WebView がサスペンドされている間でも、ネイティブの code が POST で遷移ペイロードを送信できるようにします。
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();
Android の場合は、 ACCESS_BACKGROUND_LOCATION バックグラウンドでのジオフェンシングが必要な場合にのみ、アプリのマニフェストに以下を追加してください：
<uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />
リファレンス全文
- GitHub: https://github.com/Cap-go/capacitor-background-geolocation/
- ドキュメント: /docs/plugins/background-geolocation/
「@capgo/background-geolocation の使い方」から続ける
使用している場合 @capgo/background-geolocation の使い方 ネイティブプラグインの作業を計画するには、次と連携してください： @capgo/background-geolocation @capgo/background-geolocation の実装詳細については、 スタートガイド スタートガイドの実装詳細については、 Capgo プラグインディレクトリ Capgo プラグインディレクトリのプロダクトワークフローについては、 Capgo による Capacitor プラグイン Capgo による Capacitor Plugins の実装詳細、および プラグインの追加または更新 プラグインの追加または更新に関する実装詳細についてはこちら。