API de geocercas

Tracelet proporciona un motor de geocercado robusto y fuera de línea. A diferencia de las geocercas estándar del sistema operativo, que está limitada a 20-100 geocercas y requiere que el sistema operativo active su aplicación, Tracelet evalúa las geocercas internamente dentro del motor Rust. Esto permite geocercas ilimitadas sin consumo adicional de batería.

1. Geocercas circulares versus poligonales

Tracelet admite geocercas circulares estándar y geocercas poligonales complejas.

Geocercas circulares

Una geocerca circular está definida por una coordenada central y un radio (en metros).

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
);

Geocercas poligonales

Una geocerca poligonal se define mediante una serie de coordenadas que describen una forma compleja (como un parque o un edificio).

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. Agregar y eliminar geocercas

Tracelet almacena todas las geocercas en la base de datos SQLite local. Esto significa que son persistentes tras los reinicios de la aplicación. No es necesario volver a agregarlos cada vez que se inicia la aplicación.

Agregar geocercas

Puede agregar una única geocerca o una serie de geocercas.

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

Eliminación de geocercas

Elimínelos por su identificador único o borre toda la base de datos.

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

3. Listado de geocercas activas

Puede consultar la base de datos SQLite en cualquier momento para ver qué geocercas se están monitoreando actualmente.

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

4. Escuchar eventos de geovalla

Cuando el usuario cruza un límite de geocerca, Tracelet activa el evento onGeofence. Debido a que la evaluación ocurre en el núcleo de Rust durante las actualizaciones de ubicación, estos eventos se activarán incluso si la aplicación se cierra (lo que activa su devolución de llamada sin cabeza).

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: servicio en primer plano y política de Google Play

El modo de geovalla estándar de Tracelet utiliza la API nativa de Geofence de Android (GeofencingClient), que activa ENTER/EXIT y reinicia su aplicación en su tarea sin cabeza: mientras la aplicación está suspendida o finalizada, sin un servicio de primer plano. Llamar a startGeofences() en modo estándar no comienza un servicio en primer plano (a partir de 3.5.x), por lo que es compatible de forma predeterminada.

Si usa Tracelet solo para geocercas

1. No habilite el servicio de primer plano:

   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. El SDK de Tracelet declara FOREGROUND_SERVICE / FOREGROUND_SERVICE_LOCATION por su caso de uso de seguimiento continuo. Si tu aplicación nunca es continua seguimiento, elimínelos del manifiesto fusionado con el manifiesto de fusión Regla remove en android/app/src/main/AndroidManifest.xml de su aplicación:

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

Si utiliza seguimiento continuo y geocercas

Puede conservar FOREGROUND_SERVICE_LOCATION para el caso de uso de seguimiento (p. ej. navegación/seguimiento de flotas), pero el servicio en primer plano no debe usarse para geocercado. Tracelet ya se encarga de esto: el FGS funciona para un seguimiento continuo (start()) y cambiar al modo de solo geocerca (startGeofences() en estándar modo) derriba el FGS.

6. Deriva del GPS y eventos de SALIDA falsos (modo de alta precisión)

En el modo de alta precisión, las transiciones se evalúan en la aplicación desde cada punto de GPS. A El dispositivo que se encuentra quieto justo dentro de una pequeña geocerca puede ocasionalmente recibir una arreglo único que se desplaza bastante fuera del radio, aunque nunca se movió. A evitar que se dispare una SALIDA falsa, la decisión de salida de Tracelet es consciente de la precisión: una geocerca circular solo sale una vez que se produce el error completo del GPS el círculo despeja la valla:

EXIT fires when:  distance - horizontalAccuracy > radius + buffer

Una solución reportada a 160 m de distancia pero con una precisión de ±150 m es sólo “10 m de distancia” en su máximo optimista, por lo que se trata como si estuviera dentro y sin SALIDA de incendios. Un confiado, La fijación precisa a la misma distancia sale normalmente. ENTER se deja intencionalmente independiente de la precisión, por lo que las llegadas aún se activan rápidamente.

La compensación

Debido a que el umbral de salida crece con la precisión reportada de la solución, un genuino La salida se retrasa debido aproximadamente a la incertidumbre actual del GPS. Para una geocerca de 50 m (umbral de salida de 70 m):

En exteriores con buena señal esto es insignificante. En GPS crónicamente deficiente condiciones (en el interior, cañones urbanos), una salida real puede retrasarse notablemente.

Sintonizándolo: geofenceExitAccuracyMax

Si su caso de uso prefiere una SALIDA más rápida y entusiasta, o si desea limitar la retraso en el peor de los casos: configure GeofenceConfig.geofenceExitAccuracyMax (en metros):

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,
  ),
));

Salida confirmada: una sola solución incorrecta nunca desencadena una SALIDA

La activación de precisión solo ayuda cuando una solución a la deriva es honesta acerca de su incertidumbre (gran precisión reportada). Algunos dispositivos hacen lo contrario: emiten una demasiado confiado arreglo que aterriza a cientos de metros fuera de la valla mientras informando una precisión estrecha. Debido a que la precisión reportada es pequeña, la selección No puedo ver a través de él: 200 m − 1.7 m = 198 m aún supera el umbral.

Tracelet los atrapa con una segunda defensa complementaria: se debe realizar una SALIDA. confirmado en dos correcciones consecutivas fuera de la valla. El razonamiento es físico: abandonar una geocerca es un cambio sostenido, mientras que un exceso de confianza El fallo siempre es una solución única que salta y vuelve a entrar en el siguiente uno:

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

Una salida genuina permanece afuera, por lo que la segunda solución lo confirma y exactamente se activa una EXIT: retrasada solo por una actualización de ubicación (≈1 s en alta precisión modo). La histéresis es la mitad espacial de la decisión de salida y esta es la mitad temporal; los dos trabajan juntos.

Esto está activado de forma predeterminada y no necesita configuración. La decisión vive en el Rust. core, por lo que Android e iOS se comportan de manera idéntica. (Al igual que la selección de precisión, se aplica solo a la ruta de alta precisión en la aplicación: en el modo de monitoreo de región del sistema operativo estándar, El sistema operativo es propietario de la decisión EXIT.)