API de persistencia de datos

Tracelet garantiza la entrega de datos mediante el uso de una arquitectura fuera de línea. Cada evento de coordenadas de ubicación, cambios de actividad y geovallas se escribe instantáneamente en una base de datos SQLite local cifrada.

Si bien el motor de sincronización de Tracelet lee y elimina automáticamente datos de esta base de datos, usted tiene control manual total sobre el almacén persistente.

1. Consultar ubicaciones

Puede extraer las ubicaciones sin procesar y no sincronizadas que se encuentran actualmente en la base de datos SQLite.

// Get ALL locations currently stored in the database
final locations = await tl.Tracelet.getLocations();
 
for (final loc in locations) {
  print('Location: \${loc.coords.latitude}, \${loc.coords.longitude}');
}

Consultas SQL avanzadas

No tienes que buscarlo todo. Tracelet expone un objeto SQLQuery que le permite filtrar la base de datos exactamente como SQL estándar.

// Get only the locations recorded on a specific date
final query = tl.SQLQuery(
  where: "timestamp >= ? AND timestamp <= ?",
  whereArgs: ["2024-01-01T00:00:00Z", "2024-01-01T23:59:59Z"],
  limit: 100,
  order: "timestamp DESC"
);
 
final specificLocations = await tl.Tracelet.getLocations(query);

2. Contando registros

Si solo necesita saber cuántas ubicaciones están atrasadas (por ejemplo, para mostrar una insignia de “Cola de sincronización sin conexión” en su interfaz de usuario), use getCount(). Está altamente optimizado y no carga los registros en la memoria.

// Count total un-synced locations
final count = await tl.Tracelet.getCount();
print('Pending locations to sync: \$count');
 
// You can also use SQL queries here
final highAccuracyCount = await tl.Tracelet.getCount(
  tl.SQLQuery(where: "accuracy <= 20")
);

3. Inspeccionar la cola sin conexión

Debido a que Tracelet elimina cada registro en el momento en que se confirma su sincronización, cada ubicación que aún se encuentra en la base de datos está, por definición, pendiente de carga. Los asistentes de cola pendiente lo hacen explícito, lo cual es ideal para mostrar una insignia de “esperando sincronización”, crear una vista de auditoría o diagnosticar la conectividad.

// The locations still waiting to be delivered to your backend.
final pending = await tl.Tracelet.getPendingLocations();
 
// Just the queue depth (optimized — no records are loaded into memory).
final pendingCount = await tl.Tracelet.getPendingLocationCount();
print('Offline queue: \$pendingCount location(s) waiting to sync');

Ambos aceptan un SQLQuery opcional para el filtrado de rango de tiempo, exactamente como getLocations()/getCount().

4. Destruyendo datos

Si el usuario cierra sesión o elimina explícitamente su cuenta, debe destruir su historial de ubicación para cumplir con GDPR/HIPAA.

Destruir todo

Esto limpia completamente la base de datos de ubicación.

await tl.Tracelet.destroyLocations();

Destruir ubicación específica

Puede destruir una ubicación única y específica si conoce su UUID.

¿De dónde sacas el UUID? A cada ubicación generada por Tracelet se le asigna automáticamente un uuid único. Puede obtener este ID llamando a getLocations() y leyendo la propiedad uuid en el objeto Location.

final locations = await tl.Tracelet.getLocations();
 
if (locations.isNotEmpty) {
  final firstLocationId = locations.first.uuid;
  
  // Destroy just this specific location from the database
  await tl.Tracelet.destroyLocation(firstLocationId);
}

Destruir sincronizado

Normalmente, Tracelet elimina automáticamente las ubicaciones después de recibir un HTTP 200 OK de su servidor. Sin embargo, si realiza una sincronización manual, puede activar esta limpieza manualmente.

await tl.Tracelet.destroySyncedLocations();