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 は、標準 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();