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.