ガイド
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 の reject に依存しないでください。
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 の実装詳細、および プラグインの追加または更新 プラグインの追加または更新に関する実装詳細についてはこちら。