ジオフェンシング API

Tracelet は、堅牢なオフラインファーストのジオフェンシング エンジンを提供します。 20 ～ 100 のジオフェンスに制限され、OS がアプリを起動する必要がある標準の OS ジオフェンスとは異なり、Tracelet は Rust エンジン内で内部的にジオフェンスを評価します。これにより、追加のバッテリー消耗をゼロにしながら無制限のジオフェンスが可能になります。

1. 円形ジオフェンスと多角形ジオフェンス

Tracelet は、標準的な円形ジオフェンスと複雑なポリゴン ジオフェンスの両方をサポートします。

円形ジオフェンス

円形のジオフェンスは、中心座標と半径 (メートル単位) によって定義されます。

final circular = tl.Geofence(
  identifier: 'headquarters',
  latitude: 37.7749,
  longitude: -122.4194,
  radius: 200, // 200 meters
  notifyOnEntry: true,
  notifyOnExit: true,
  notifyOnDwell: true, // Triggers if they stay inside
  loiteringDelay: 300, // Trigger dwell after 5 minutes
);

ポリゴンジオフェンス

ポリゴン ジオフェンスは、複雑な形状 (公園や建物など) の輪郭を描く座標の配列によって定義されます。

final polygon = tl.Geofence.polygon(
  identifier: 'golden_gate_park',
  vertices: [
    tl.Coordinate(latitude: 37.773972, longitude: -122.431297),
    tl.Coordinate(latitude: 37.769996, longitude: -122.511055),
    tl.Coordinate(latitude: 37.764516, longitude: -122.508566),
  ],
  notifyOnEntry: true,
  notifyOnExit: true,
);

2. ジオフェンスの追加と削除

Tracelet は、すべてのジオフェンスをローカル SQLite データベースに保存します。これは、アプリが再起動されても永続的であることを意味します。アプリを起動するたびにそれらを再追加する必要はありません。

ジオフェンスの追加

単一のジオフェンスまたはジオフェンスの配列を追加できます。

// Add a single geofence
await tl.Tracelet.addGeofence(circular);
 
// Add multiple geofences efficiently
await tl.Tracelet.addGeofences([circular, polygon]);

ジオフェンスの削除

一意の識別子を使用してそれらを削除するか、データベース全体をクリアします。

// Remove a specific geofence
await tl.Tracelet.removeGeofence('headquarters');
 
// Remove all geofences entirely
await tl.Tracelet.removeGeofences();

3. アクティブなジオフェンスの一覧表示

いつでも SQLite データベースにクエリを実行して、現在監視されているジオフェンスを確認できます。

final geofences = await tl.Tracelet.getGeofences();
for (final fence in geofences) {
  print('Monitoring: \${fence.identifier}');
}

4. ジオフェンス イベントのリッスン

ユーザーがジオフェンスの境界を越えると、Tracelet は onGeofence イベントを起動します。評価は位置情報の更新中に Rust コアで行われるため、アプリが強制終了された場合でも、これらのイベントは発生します (ヘッドレス コールバックがトリガーされます)。

tl.Tracelet.onGeofence((evt) {
  if (evt.action == tl.GeofenceEventAction.ENTER) {
    print('User entered: \${evt.identifier}');
  } else if (evt.action == tl.GeofenceEventAction.EXIT) {
    print('User exited: \${evt.identifier}');
  } else if (evt.action == tl.GeofenceEventAction.DWELL) {
    print('User is dwelling inside: \${evt.identifier}');
  }
});

5. Android: フォアグラウンド サービスと Google Play ポリシー

Tracelet の 標準 ジオフェンス モードは、ネイティブ Android Geofence API を使用します (GeofencingClient)、ENTER/EXIT が起動され、アプリが再起動されます。 ヘッドレス タスク — アプリが一時停止または終了している間、なしで フォアグラウンドサービス。標準モードで startGeofences() を呼び出すと 開始されません フォアグラウンド サービス (3.5.x 時点) であるため、デフォルトで準拠しています。

Tracelet をジオフェンシングのみに使用する場合

1. フォアグラウンド サービスを有効にしないでください。

   await tl.Tracelet.ready(const tl.Config(
     android: tl.AndroidConfig(
       foregroundService: tl.ForegroundServiceConfig(enabled: false),
     ),
     geofence: tl.GeofenceConfig(geofenceModeHighAccuracy: false),
   ));
   await tl.Tracelet.startGeofences();

2.Tracelet SDK は FOREGROUND_SERVICE / FOREGROUND_SERVICE_LOCATION を宣言します 継続的な追跡のユースケースについて。アプリが継続的に実行しない場合 追跡、manifest-merger を使用してマージされたマニフェストからそれらを削除します アプリの android/app/src/main/AndroidManifest.xml 内の remove ルール:

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
          xmlns:tools="http://schemas.android.com/tools">
    <uses-permission android:name="android.permission.FOREGROUND_SERVICE_LOCATION"
        tools:node="remove" />
    <uses-permission android:name="android.permission.FOREGROUND_SERVICE"
        tools:node="remove" />
</manifest>

継続的追跡 * および * ジオフェンシングを使用する場合

追跡のユースケースでは FOREGROUND_SERVICE_LOCATION を保持しておくこともできます (例: ナビゲーション/フリート追跡）、ただしフォアグラウンド サービスは次の目的で使用してはなりません。 ジオフェンシング。 Tracelet はすでにこれを処理しています。FGS は継続的な追跡のために実行されます。 (start())、およびジオフェンス専用モード (標準では startGeofences()) への切り替え モード）FGS を破棄します。