メインコンテンツへスキップ
@capgo/background-geolocation 位置情報 オープンソース

バックグラウンド位置情報取得 Capacitor プラグイン

iOS/Androidネイティブのジオフェンシングと遷移webhookによる高精度なバックグラウンド位置追跡

インストール

bun add @capgo/background-geolocation bunx cap sync
npm、pnpm、または yarn
  • npm install @capgo/background-geolocation
  • pnpm add @capgo/background-geolocation
  • yarn add @capgo/background-geolocation

ガイド

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 - 監視中の領域識別子をリスト表示。
  • geofenceTransition listener - アプリがアクティブな間にenterおよびexitイベントを受信。
  • geofenceError listener - ネイティブの監視エラーを遷移イベントとは別に処理。

使用例

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" />

リファレンス全文

「@capgo/background-geolocation の使い方」から続ける

使用している場合 @capgo/background-geolocation の使い方 ネイティブプラグインの作業を計画するには、次と連携してください: @capgo/background-geolocation 実装の詳細については @capgo/background-geolocation を参照、 スタートガイド スタートガイドの実装詳細については、 Capgo プラグインディレクトリ Capgo プラグインディレクトリのプロダクトワークフローについては、 Capgo による Capacitor プラグイン Capgo による Capacitor Plugins の実装詳細、および プラグインの追加または更新 プラグインの追加または更新に関する実装詳細についてはこちら。

よくある質問

Background Geolocation プラグイン FAQ

Capacitor アプリに Background Geolocation プラグインをインストールするには?

&quot;bun add @capgo/background-geolocation&quot; (または &quot;npm install @capgo/background-geolocation&quot;) を実行し、次に &quot;bunx cap sync&quot; を実行して、iOS と Android プロジェクトがネイティブ code を認識するようにします。アプリの code から &quot;@capgo/background-geolocation&quot; をインポートします。

@capgo/background-geolocation は React、Vue、Angular で動作しますか?

はい。Background Geolocation は Capacitor パッケージであるため、Ionic、React、Vue、Angular、Svelte、プレーン JavaScript を含む、Capacitor 内で動作するすべての Web フレームワークで動作します。

@capgo/background-geolocation はどの Capacitor バージョンをサポートしていますか?

Capgo プラグインは Capacitor のメジャーバージョンに合わせています。使用している Capacitor のメジャーバージョンに一致するプラグインのメジャーバージョンを使ってください (例: Capacitor 8 ならプラグイン v8)。GitHub の README にある互換性テーブルに、メンテナンス中のバージョンが記載されています。

@capgo/background-geolocation は無料かつオープンソースですか?

はい。ソース code は https://github.com/Cap-go/capacitor-background-geolocation/ の GitHub で公開されており、npm から無料でインストールできます。バグレポートやプルリクエストをお待ちしています。

App Store のレビューなしで、Background Geolocation を使用している code を更新できますか?

プラグインのインストールやアップグレードはネイティブの code を変更するため、新しいストアビルドが必要です。その後は、プラグインを呼び出す JavaScript、HTML、CSS の変更を Capgo Live Updates で即座に配信できます。

アプリの審査を待たずに Background Geolocation の変更をリリース

プラグインをストア用ビルドに組み込めば、Capgo live updates で JavaScript、HTML、CSS の変更を数分でユーザーに配信できます

Capgo から始める