API сохранения данных

Tracelet гарантирует доставку данных, используя автономную архитектуру. Каждая координата местоположения, изменение активности и событие геозоны мгновенно записываются в зашифрованную локальную базу данных SQLite.

Хотя механизм синхронизации Tracelet автоматически считывает и удаляет данные из этой базы данных, вы имеете полный ручной контроль над постоянным хранилищем.

1. Запрос локаций

Вы можете извлечь необработанные, несинхронизированные местоположения, которые в настоящее время находятся в базе данных 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}');
}

Расширенные SQL-запросы

Вам не обязательно брать все. Tracelet предоставляет объект SQLQuery, который позволяет фильтровать базу данных точно так же, как стандартный SQL.

// 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. Подсчет записей

Если вам просто нужно узнать, сколько местоположений находится в очереди (например, чтобы отобразить значок «Очередь автономной синхронизации» в вашем пользовательском интерфейсе), используйте getCount(). Он высоко оптимизирован и не загружает записи в память.

// 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. Проверка автономной очереди

Поскольку Tracelet удаляет каждую запись в момент подтверждения ее синхронизации, каждое местоположение, остающееся в базе данных, по определению — ожидает загрузки. Помощники очереди ожидания делают это явным, что идеально подходит для отображения значка «Ожидание синхронизации», построения представления аудита или диагностики подключения.

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

Оба принимают дополнительный SQLQuery для фильтрации временного диапазона, точно так же, как getLocations()/getCount().

4. Уничтожение данных

Если пользователь выходит из системы или явно удаляет свою учетную запись, вы должны уничтожить его историю местоположений в соответствии с GDPR/HIPAA.

Уничтожить все

Это полностью очистит базу данных местоположений.

await tl.Tracelet.destroyLocations();

Уничтожить определенное место

Вы можете уничтожить одно конкретное место, если знаете его UUID.

Где взять UUID? Каждому местоположению, сгенерированному Tracelet, автоматически присваивается уникальный номер uuid. Вы можете получить этот идентификатор, вызвав getLocations() и прочитав свойство uuid объекта 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);
}

Уничтожить синхронизированные

Обычно Tracelet автоматически удаляет местоположения после получения HTTP 200 OK от вашего сервера. Однако если вы выполняете синхронизацию вручную, вы можете запустить очистку вручную.

await tl.Tracelet.destroySyncedLocations();