API геозон

Tracelet предоставляет надежный механизм геозонирования, работающий в автономном режиме. В отличие от стандартного геозоны ОС, которое ограничено 20–100 геозонами и требует, чтобы ОС активировала ваше приложение, 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. для случая непрерывного отслеживания. Если ваше приложение никогда не выполняет непрерывную отслеживание, удалите их из объединенного манифеста с помощью манифеста-слияния Правило remove в android/app/src/main/AndroidManifest.xml вашего приложения:

   <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() в стандартном режиме). режим) срывает ФГС.