Skip to Content
Основные понятияСохранение данных

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. Автоматическое сохранение

Исправлено в версии 3.8.3. Два ключа PersistenceConfig ограничивают объем, который разрешено хранить в локальной очереди, поэтому при длительном автономном режиме база данных не может увеличиваться без ограничений.

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,
  ),
));
КлючПо умолчанию-1 означает
НОТРАНС0ЛАТЕНОТРАНС1ЛАТЕсохранить навсегда
НОТРАНС0ЛАТЕНОТРАНС1ЛАТЕбезлимитный

Записи удаляются сначала самые старые в порядке вставки — в том же порядке, в котором механизм синхронизации их загружает, поэтому в очереди всегда сохраняются самые свежие данные. Два ограничения независимы: применяется то, что достигается первым, и любое из них можно отключить с помощью -1, в то время как другое остается в силе.

Оба ключа были приняты и возвращены корректно в более ранних версиях, но ничего не применялись — очередь росла без ограничений, несмотря на то, что они были установлены. Если ваше приложение полагалось на это, явно установите maxDaysToPersist: -1, чтобы сохранить старое поведение. maxDaysToPersist также теперь по умолчанию имеет значение 3, а не ранее документированный 1, так что включение принудительного применения не приводит к сокращению данных автономных выходных до последнего дня.

Удаление амортизируется после 100 вставок, а не выполняется при каждом исправлении, поэтому DELETE не прикрепляется к каждому местоположению. Таким образом, очередь ограничена maxRecordsToPersist + 100 и сокращается до самого предела при каждом сокращении — это ограничивает рост, а не является потолком для каждой вставки. Первая вставка после запуска сокращается, поэтому невыполненная работа, перенесенная из более ранней версии, очищается при следующем исправлении.

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

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

Если пользователь выходит из системы или явно удаляет свою учетную запись, вы должны уничтожить его историю местоположений в соответствии с 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();
ГеофенсингДиагностика и отчеты об ошибках