データ永続化 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. 自動保持
3.8.3 で修正されました。 2 つの 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 は | を意味します。
| --- | --- | --- |
|非トランスレート |翻訳1遅れ |永久に保持します |
|非トランスレート |翻訳1遅れ |無制限 |
レコードは古いものから順に、同期エンジンがレコードをアップロードする順序と同じ挿入順序で削除されるため、キューには常に最新のデータが保持されます。 2 つの上限は独立しています。最初に到達した方が適用され、どちらかを -1 でオフに切り替えることができ、もう一方は有効なままになります。
以前のバージョンでは両方のキーが受け入れられ、正しく報告されましたが、何も強制されませんでした。どのように設定してもキューは際限なく増大しました。アプリがこれに依存している場合は、maxDaysToPersist: -1 を明示的に設定して古い動作を維持します。また、maxDaysToPersist のデフォルトは、以前に文書化された 1 ではなく 3 になるため、強制をオンにしても、オフラインの週末のデータが最終日まで削減されることはありません。
プルーニングは修正ごとに実行されるのではなく、100 回の挿入で償却されるため、DELETE がすべての場所に適用されるわけではありません。したがって、キューは maxRecordsToPersist + 100 によって制限され、プルーンごとにキャップ自体に切り戻されます。これは増加を制限するものであり、挿入ごとの上限ではありません。起動後の最初の挿入はプルーニングされるため、以前のバージョンから引き継がれたバックログは次の修正でクリアされます。
保持では、場所の監査証跡エントリも削除されるため、枝刈りによって孤立したチェーン行が残ることはありません。経過時間は各レコードのタイムスタンプから取得されます。タイムスタンプを読み取ることができないレコードは、古いものとみなされずに保持され、代わりにレコードの上限によって制限されます。
5. データの破棄
ユーザーがログアウトするか、アカウントを明示的に削除した場合は、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();