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

6. Дрейф GPS и ложные события ВЫХОД (режим высокой точности)

В режиме высокой точности переходы оцениваются в приложении для каждого местоположения GPS. А устройство, стоящее на месте внутри небольшой геозоны, может иногда получать единственное исправление, которое вылетает далеко за пределы радиуса, хотя оно никогда не двигалось. К предотвратить запуск ложного EXIT, решение о выходе Tracelet с учетом точности: выход из круговой геозоны происходит только после полной ошибки GPS. круг обходит забор:

EXIT fires when:  distance - horizontalAccuracy > radius + buffer

Фиксированная точка сообщается на расстоянии 160 м, но с точностью ± 150 м максимум составляет всего «10 м». оптимистично, поэтому он рассматривается как все еще внутри и не срабатывает ВЫХОД. Уверенный, точная фиксация на одном и том же расстоянии выходит нормально. ENTER намеренно оставлен не зависит от точности, поэтому поступления по-прежнему срабатывают быстро.

Компромисс

Поскольку порог выхода увеличивается с заявленной точностью исправления, подлинное вылет задерживается примерно из-за текущей неопределенности GPS. Для геозоны 50 м (порог выхода 70 м):

На открытом воздухе при хорошем сигнале это незначительно. В хронически плохом GPS условиях (глубокие помещения, городские каньоны) реальный выход может заметно отставать.

Настройка: geofenceExitAccuracyMax

Если ваш вариант использования предпочитает более быстрый и быстрый ВЫХОД или вы хотите ограничить задержка в худшем случае — устанавливаем GeofenceConfig.geofenceExitAccuracyMax (в метрах):

await tl.Tracelet.ready(const tl.Config(
  geofence: tl.GeofenceConfig(
    geofenceModeHighAccuracy: true,
    // Absorb drift up to 20 m, but keep genuine exits reasonably prompt.
    geofenceExitAccuracyMax: 20,
  ),
));

Подтвержденный выход: одно неверное исправление никогда не вызывает ВЫХОД.

Стробирование точности помогает только тогда, когда дрейфующее исправление честно говорит о своей неопределенности. (большая заявленная точность). Некоторые устройства действуют наоборот: они излучают чрезмерно самоуверенное исправление, которое приземляется за сотни метров за забором, в то время как сообщая о высокой точности. Поскольку заявленная точность мала, стробирование не может видеть сквозь него — 200 m − 1.7 m = 198 m все равно очищает порог.

Tracelet ловит их с помощью второй, дополнительной защиты: должен быть ВЫХОД. подтверждено двумя последовательными исправлениями. Причина в том, физический — выход из геозоны — это устойчивое изменение, тогда как чрезмерная самоуверенность глюк — это всегда одно исправление, которое выскакивает и возвращается в следующий же раз. один:

fix 1: 200 m out  → held (pending confirmation), no EXIT
fix 2: back inside → pending cleared, glitch absorbed

Истинное отклонение остаётся снаружи, поэтому второй фикс это точно подтверждает. срабатывает один ВЫХОД — с задержкой только на одно обновление местоположения (≈1 с в высокоточном режиме). режим). Гистерезис – это пространственная половина решения о выходе, и это временная половина; эти двое работают вместе.

Это включено по умолчанию и не требует настройки. Решение живет в Rust core, поэтому Android и iOS ведут себя одинаково. (Как и стробирование точности, это применимо только к высокоточному пути внутри приложения — в стандартном режиме мониторинга региона ОС Решение EXIT принадлежит операционной системе.)