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. Retención automática

Corregido en 3.8.3. Dos claves PersistenceConfig limitan la cantidad que se permite contener a la cola local, por lo que un período prolongado sin conexión no puede hacer crecer la base de datos sin límite.


await tl.Tracelet.ready(tl.Config(
  persistence: tl.PersistenceConfig(
    // Purge records older than this many days. -1 retains forever.
    maxDaysToPersist: 3,
    // Never hold more than this many records; the oldest go first.
    // -1 is unlimited.
    maxRecordsToPersist: 5000,
  ),
));

Clave	Predeterminado	`-1` significa
`maxDaysToPersist`	`3`	conservar para siempre
`maxRecordsToPersist`	`-1`	ilimitado

Los registros se expulsan los más antiguos primero, por orden de inserción, el mismo orden en el que los carga el motor de sincronización, por lo que la cola siempre mantiene los datos más recientes. Los dos límites son independientes: se aplica el que se alcance primero, y cualquiera de ellos se puede desactivar con -1 mientras el otro permanece vigente.

Ambas claves fueron aceptadas y reportadas correctamente en versiones anteriores, pero nada las aplicó: la cola creció sin límites, independientemente de cómo se configuraran. Si su aplicación dependía de eso, configure maxDaysToPersist: -1 explícitamente para mantener el comportamiento anterior. maxDaysToPersist ahora también tiene por defecto 3 en lugar del 1 previamente documentado, de modo que activar la aplicación de la ley no corta los datos de un fin de semana fuera de línea hasta el último día.

La poda se amortiza en 100 inserciones en lugar de ejecutarse en cada arreglo, por lo que no se adjunta un DELETE a cada ubicación. Por lo tanto, la cola está limitada por maxRecordsToPersist + 100 y se reduce hasta el límite mismo en cada poda: limita el crecimiento, no es un límite por inserción. La primera inserción después del lanzamiento se elimina, por lo que un trabajo pendiente transferido de una versión anterior se elimina en la siguiente corrección.

La retención elimina la entrada del registro de auditoría de una ubicación junto con ella, por lo que la poda no puede dejar filas de cadena huérfanas. La edad se toma de la marca de tiempo de cada registro; un registro cuya marca de tiempo no se puede leer se conserva en lugar de asumirse como antiguo y, en su lugar, está limitado por el límite del registro.

5. 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();