データ永続化 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 は、標準 SQL とまったく同じようにデータベースをフィルタリングできる SQLQuery オブジェクトを公開します。


// 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. レコードのカウント

バックログにあるロケーションの数を知る必要があるだけの場合 (たとえば、UI に「オフライン同期キュー」バッジを表示するため)、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');

どちらも、getLocations() / getCount() とまったく同様に、時間範囲フィルター用のオプションの SQLQuery を受け入れます。

4. データの破棄

ユーザーがログアウトするか、アカウントを明示的に削除した場合は、GDPR/HIPAA に準拠するためにユーザーのロケーション履歴を破棄する必要があります。

すべてを破壊する

これにより、位置データベースが完全に消去されます。


await tl.Tracelet.destroyLocations();

特定の場所を破壊する

UUID がわかっている場合は、単一の特定の場所を破棄できます。

UUID はどこで入手できますか? Tracelet によって生成されたすべての位置には、一意の uuid が自動的に割り当てられます。この ID を取得するには、getLocations() を呼び出し、Location オブジェクトの uuid プロパティを読み取ります。


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