Skip to Content
APIリファレンス

徹底的な API リファレンス

このページには、Tracelet の構成 API に関する絶対的な信頼できる情報源が含まれています。 Tracelet.ready(Config) に渡すことができるすべてのパラメータがここにリストされています。

これらのパラメーターを使用する 理由 を説明する実際のアーキテクチャ シナリオについては、パラメーターの横にある 「ストーリーを見る 📖」 リンクをクリックしてください。

実行時の構成の更新 — ready() と setConfig()

設定がプラグインに到達する方法は 2 つあり、それぞれ意味が異なります。

Tracelet.ready(config) は 完全なベースラインを確立します。どの分野も 送信され、有効な値に解決されます。起動時に 1 回呼び出すか、起動時にもう一度呼び出します。 構成全体を置き換えたい場合。 Tracelet.reset(config) の動作 同じように。

Tracelet.setConfig(config) は 部分的な更新です。あなたが選んだフィールドのみ 実際に設定されたものが送信されます。それ以外はすべてプラットフォームが持っているものを保持します 続けた。セッション中に 1 つ変更する必要がある場合は、次のようにします。

// Changes one flag. The notification title from ready(), the HTTP URL,
// distanceFilter, stopOnTerminate — all keep their configured values.
await Tracelet.setConfig(const Config(
  android: AndroidConfig(
    foregroundService: ForegroundServiceConfig(
      showNotificationOnPauseOnly: true,
    ),
  ),
));
 
// Changes nothing at all.
await Tracelet.setConfig(const Config());

⚠️ 3.8.0 で変更されました。 以前は setConfig() が全体を置き換えていました。 設定なので、言及しなかったフィールドはすべてその設定に自動的に戻ります デフォルト — setConfig(const Config()) を含む すべて をリセットします stopOnTerminate、HTTP 設定、フォアグラウンド サービス通知、および iOS キープアライブ フラグ。状態をリセットするためにこれに依存した場合は、呼び出してください 代わりに Tracelet.reset() または ready() (#320 , #321 )。

値をデフォルトに戻すことは引き続き機能します。 「設定解除」とは、値を設定しなかったことを意味します フィールドを指定します。値がデフォルトと等しくなることはありません。 ForegroundServiceConfig(showNotificationOnPauseOnly: false) はフラグをオンにします オフ。完全に省略したフィールドだけがそのまま残されます。

Tracelet.activeConfig は同じマージをローカルに適用するため、常に反映されます。 最後に残った通話のデフォルトではなく、プラットフォームが実際に保持しているもの 設定を解除します。

永続化またはパイプラインの再起動をすべきではない変更については、 代わりに、ターゲットを絞ったランタイム API: updateLocationProviderOptions() 精度/距離、そして updateNotification() ライブ通知を再投稿します。

🌍 GeoConfig (config.geo)

物理的な位置、精度、サンプリング ロジックを制御します。 地理ストーリーを参照 📖

  • desiredAccuracy: DesiredAccuracy (デフォルト: DesiredAccuracy.high) ターゲットのハードウェア精度。バッテリーを節約するには、GPS には high、Cellular/Wi-Fi には low を使用してください。
  • distanceFilter: double (デフォルト: 10.0) ポイントが記録される前に移動する最小の水平メートル。

ℹ️ setConfig() 経由で desiredAccuracy または distanceFilter を変更すると、値が保持され、追跡パイプラインが再起動されます。追跡中の 一時的な オーバーライド (例: 確認された静止期間中に GPS をオフにするなど) の場合は、updateLocationProviderOptions() を使用します。これは、実行中のプロバイダーを再起動せずにライブで更新し、永続的な設定には一切触れません。

  • stationaryRadius: double (デフォルト: 25.0) 静止しているとみなされるユーザーの周囲の半径 (GPS の流出を停止します)。
  • locationTimeout: int (デフォルト: 60) 諦めるまでに GPS ロックを待機する最大秒数。
  • disableElasticity: bool (デフォルト: false) true の場合、動的な速度ベースの距離スケーリングが無効になります。
  • elasticityMultiplier: double (デフォルト: 1.0) 高速走行時の動的距離フィルターの乗数。
  • stopAfterElapsedMinutes: int (デフォルト: -1) X 分後にエンジンを自動停止します。 -1 は永久に実行することを意味します。
  • maxMonitoredGeofences: int (デフォルト: -1) 同時に監視できるジオフェンスの最大数。
  • enableTimestampMeta: bool (デフォルト: false) 正確なナノ秒のハードウェア タイムスタンプを添付します。
  • enableAdaptiveMode: bool (デフォルト: false) バッテリーレベルに基づいて設定を自動で切り替えます。
  • periodicLocationInterval: int (デフォルト: 900) 静止時の定期的な更新間の秒数。
  • periodicDesiredAccuracy: DesiredAccuracy (デフォルト: DesiredAccuracy.medium) 定期的なバックグラウンドウェイク中に使用される精度。
  • enableSparseUpdates: bool (デフォルト: false) 低電力セルタワー三角測量のみを使用します。
  • sparseDistanceThreshold: double (デフォルト: 50.0) スパースモードで移動するメーター。
  • sparseMaxIdleSeconds: int (デフォルト: 300) まばらな更新がない場合の最大時間。
  • enableDeadReckoning: bool (デフォルト: false) GPS が失われた場合 (トンネルなど)、加速度計/ジャイロスコープを使用して位置を推測します。
  • deadReckoningActivationDelay: int (デフォルト: 0) 推測航法が開始されるまでの数秒間の GPS 喪失。
  • deadReckoningMaxDuration: int (デフォルト: 0) 停止するまでの推測航法を許可する最大秒数。
  • resolveAddress: bool (デフォルト: false) 座標を住所文字列に自動的に逆ジオコーディングします。

🧹 ロケーションフィルター (config.geo.filter)

不正な GPS データが SQLite/Sync に到達する前にクリーンアップします。 フィルターストーリーを参照 📖

  • trackingAccuracyThreshold: int (デフォルト: 100) X メーターより精度の悪いポイントは除外されます。
  • maxImpliedSpeed: int (デフォルト: 80) 速度が X m/s (80 m/s = 288 km/h) を超えることを意味する位置ジャンプを拒否します。
  • odometerAccuracyThreshold: int (デフォルト: 50) X メーターより精度の悪いポイントは、総走行距離に加算されません。
  • policy: LocationFilterPolicy (デフォルト: LocationFilterPolicy.adjust) 悪いポイント (drop または adjust) を処理する方法。
  • rejectMockLocations: bool (デフォルト: false) GPS スプーフィング アプリによって生成された位置情報を即座に削除します。
  • mockDetectionLevel: int (デフォルト: 1) 偽の GPS 検出ヒューリスティックの積極性。
  • useKalmanFilter: bool (デフォルト: false) 複雑なカルマン平滑化を生の GPS 軌道に適用します。

📱 AppConfig (config.app)

アプリのライフサイクル全体の動作を制御します。

  • stopOnTerminate: bool (デフォルト: true) true の場合、ユーザーがアプリをスワイプすると追跡が停止します。 false の場合、バックグラウンドで再起動します。 ストーリーの終了を参照 📖
  • startOnBoot: bool (デフォルト: false) true の場合、電話が再起動されると追跡が自動的に開始されます。
  • heartbeatInterval: int (デフォルト: 60) エンジンが生きていることを証明するために、X 秒ごとに「ハートビート」イベントを発生させます。
  • schedule: List<String> (デフォルト: []) 特定の時間に追跡を自動的に開始/停止する CRON のような文字列。
  • remoteConfigUrl: String? (デフォルト: null) HTTPS URL SDK は ready() から JSON 構成マップを取得し、ローカル構成に適用してバックグラウンドで更新します。デバイス上にキャッシュされ、オフラインで即座に適用されます。 リモート構成 を参照してください。
  • remoteConfigHeaders: Map<String, String>? (デフォルト: null) リモート構成フェッチ用の HTTP ヘッダー。
  • remoteConfigTimeout: int (デフォルト: 60000) リモート設定を取得するためのタイムアウト (ミリ秒)。
  • remoteConfigRefreshInterval: int (デフォルト: 1440) リモート構成を再度取得するまでの数分。

🤖 AndroidConfig (config.android)

Android 固有の OS の制約。 Android ストーリーを参照 📖

  • locationUpdateInterval: int (デフォルト: 1000) GPS ping 間の Ms。
  • batteryBudgetPerHour: double (デフォルト: 0.0) 目標の 1 時間あたりの最大バッテリー消耗率 (%)。 0.0 はスロットルを無効にします。
  • releaseWakelockWhenStationary: bool (デフォルト: false) MotionDetectionMode.smart を使用すると、デバイスが完全に静止したときにトラッキング ウェイロックが解放され、ディープ スリープ バッテリーの節約が最大化されます。
  • fastestLocationUpdateInterval: int (デフォルト: 500) 別のアプリが GPS ping を要求した場合の GPS ping 間の最速ミリ秒。
  • deferTime: int (デフォルト: 0) Android が X ミリ秒にわたって位置情報をバッチ処理できるようにします。
  • allowIdenticalLocations: bool (デフォルト: false) false の場合、重複する正確な座標は削除されます。
  • geofenceModeHighAccuracy: bool (デフォルト: false) — ⚠️ 非推奨 ジオフェンスに GPS チップを強制的に使用します (バッテリーの消耗が激しい)。クロスプラットフォームを使用する GeofenceConfig.geofenceModeHighAccuracy (以下の GeofenceConfig セクションを参照) 代わりに、iOS と Android の両方を制御するようになりました。この Android 専用フラグはまだあります 下位互換性のために考慮されます (どちらかが true の場合、高精度モードは 有効になっています）が、将来のメジャー バージョンでは削除される予定です。
  • periodicUseForegroundService: bool (デフォルト: false) 定期的なウェイク中に永続的な通知を強制します。
  • periodicUseExactAlarms: bool (デフォルト: false) 正確なウェイクアップには AlarmManager を使用します (SCHEDULE_EXACT_ALARM マニフェスト権限が必要です)。 正確なアラームを参照 📖
  • scheduleUseAlarmManager: bool (デフォルト: false) CRON スケジュールに正確なアラームを使用します。

ForegroundServiceConfig (config.android.foregroundService)

  • enabled: bool (デフォルト: true) Android 13 以降では POST_NOTIFICATIONS 権限が必要です。 通知を参照 📖
  • channelId: String (デフォルト: 'tracelet_channel')
  • channelName: String (デフォルト: 'Tracelet')
  • notificationTitle: String (デフォルト: 'Tracelet')
  • notificationText: String (デフォルト: 'Tracking location in background')
  • notificationColor: String? (デフォルト: null) 小さなアイコンの背景の 16 進数の色。
  • notificationSmallIcon: String? (デフォルト: null) res/drawable フォルダー内の白のみの PNG の名前。
  • notificationLargeIcon: String? (デフォルト: null)
  • notificationPriority: NotificationPriority (デフォルト: NotificationPriority.defaultPriority)
  • notificationOngoing: bool (デフォルト: true)
  • showNotificationOnPauseOnly: bool (デフォルト: false) アプリが画面に表示されている間は通知を非表示にします。 app.stopOnTerminate が false の間は無視されます — 非表示にするとフォアグラウンド サービスが降格され、そのウィンドウで最近の内容からスワイプするとプロセスが強制終了されます (#378 )。オーバーライドは start() ごとに 1 回ログに記録されます。 通知を非表示にするを参照 📖
  • actions: List<String> (デフォルト: [])
  • notificationStartedAt: int? (デフォルト: null) 経過タイマーがカウントアップするエポックミリ秒 (壁時計)。 notificationShowTimer が true の場合にのみレンダリングされます。通知が投稿されるたびに、将来の値が現在時刻に固定されるため、デバイスのクロック修正が自己修復されます。 経過タイマーを参照 📖
  • notificationShowTimer: bool (デフォルト: false) notificationStartedAt からのセルフティックカウントアップクロックを表示します。 Android は、アプリから再投稿することなく、それを進化させます。 notificationStartedAt が存在しない場合、タイマーは表示されません。
  • notificationOnlyAlertOnce: bool (デフォルト: false) 通知の最初の投稿時にのみデバイスに警告を発するため、その後のコンテンツ更新はサイレントになります。タイマーだけでなく、追跡の実行中にテキストが変更されるあらゆる通知に役立ちます。 テキストを静かに更新するを参照 📖

🔔 トラッキングが既に実行されているときに通知の変更を適用するには、setConfig() の後に Tracelet.updateNotification() を呼び出します。パイプラインを再起動せずにライブ通知を再投稿します (v3.6.8 以降)。 iOS では、代わりに実行中のライブ アクティビティが更新されます。 Web では何も操作しません。

🍎 IosConfig (config.ios)

iOS 固有の OS の制約。 iOS ストーリーを参照 📖

  • activityType: LocationActivityType (デフォルト: LocationActivityType.other) iOS に何を行っているか (例: fitness、navigation) を通知し、追跡をいつ一時停止するかを iOS に知らせます。
  • useSignificantChangesOnly: bool (デフォルト: false) 携帯電話の塔からのハンドオフに完全に依存します。バッテリーの消耗がほぼゼロ。
  • showsBackgroundLocationIndicator: bool (デフォルト: false) ブルーピルインジケーターを表示します。 location Xcode 機能が必要です。 青い錠剤を参照 📖
  • pausesLocationUpdatesAutomatically: bool (デフォルト: false) ユーザーがしばらく移動していない場合、iOS が GPS チップを強制終了できるようにします。
  • locationAuthorizationRequest: LocationAuthorizationRequest (デフォルト: always) どの権限を要求するか。
  • disableLocationAuthorizationAlert: bool (デフォルト: false) 「使用時」のみが要求された場合に、OS が「常に許可」を要求しないようにします。
  • preventSuspend: bool (デフォルト: false) サイレントオーディオを再生してアプリを 24 時間年中無休で稼働させます。 audio Xcode 機能が必要です。 一時停止の防止を参照 📖
  • useBackgroundActivitySession: bool (デフォルト: false) CLBackgroundActivitySession (iOS 17 以降) を使用して、「使用時」認証のみでバックグラウンドの位置情報セッションを維持します。これにより、従来の青い錠剤がダイナミックアイランドインジケーターに置き換えられます。 注意: Apple App Store のガイドラインでは、これを使用するアプリは、バックグラウンド位置情報が必要な理由をユーザーに明確に説明する必要があります。
  • liveActivityConfig: LiveActivityConfig? (デフォルト: null) 追跡中にロック画面 / ダイナミック アイランド ライブ アクティビティをオプトインします (iOS 16.1 以降、ウィジェット拡張機能が必要です)。 title と body を受け取ります。 ライブアクティビティを参照 📖。 Tracelet.updateNotification() (v3.6.8+) を使用して実行時に更新します。

LiveActivityConfig (config.ios.liveActivityConfig)

  • title: String (必須) 静的な見出し。 ActivityKit 属性はアクティビティの実行中は不変であるため、次回アクティビティを開始するときに変更が適用されます。

  • body: String (必須) updateNotification() によってその場で更新される動的ステータス行。

  • startedAt: int? (デフォルト: null) 経過タイマーがカウントアップするエポックミリ秒 (壁時計)。 showTimer が true の場合にのみレンダリングされます。 経過タイマーを参照 📖

  • showTimer: bool (デフォルト: false) Text(timerInterval:) を使用して、startedAt からセルフティック カウントアップ クロックをレンダリングします。 iOS は、アプリからのアップデートを必要とせずに、それを進化させます。 startedAt が存在しない場合、タイマーは表示されません。

    カスタム ウィジェット拡張機能は、TraceletActivityAttributes.ContentState の 独自のコピーが startedAt および showTimer を宣言している場合にのみタイマーをレンダリングします。これらのフィールドが存在する前に作成された拡張機能は動作し続けますが、余分な値は単に無視されますが、構造体を更新するまでクロックは表示されません。 更新されたスニペットを参照してください 📖

📍 GeofenceConfig (config.geofence)

クロスプラットフォームのジオフェンシング動作 (iOS + Android)。

  • geofenceModeHighAccuracy: bool (デフォルト: false) ジオフェンスの遷移を検出する方法を制御します。

    • false (デフォルト) — OS 領域監視サービスを使用します。 低電力、iOS ブルー インジケータなし。ただし、OS は実用的な最小半径 (約 100 m) を強制しており、小さい遷移や EXIT 遷移は信頼性が低い場合があります。
    • true — 継続的な GPS からのアプリ内遷移を評価します。 狭い半径 (例: 5 ～ 50 m) と EXIT イベントの信頼性を高めます。ただし、バッテリーの使用量が多くなり、iOS ではシステムの「使用中の場所」(青) ステータス バー インジケーターが表示されます (継続的な GPS により強制されます)。 青い錠剤を参照 📖

    これは、非推奨の AndroidConfig.geofenceModeHighAccuracy に代わるものです。 if either is true, high-accuracy mode is enabled.

  • geofenceInitialTrigger: bool (デフォルト: true) 登録時にジオフェンスの状態を評価します。

  • geofenceInitialTriggerEntry: bool (デフォルト: true) 登録時にデバイスがすでにジオフェンス内にある場合は、すぐに ENTER を押します。

  • geofenceProximityRadius: int (デフォルト: 1000) 近接ベースの読み込みの半径 (メートル) — この距離内のジオフェンスのみが OS にアクティブに登録されます (iOS 20 のリージョン制限をはるかに超えて管理できます)。

  • geofenceExitAccuracyMax: int (デフォルト: -1) 高精度モードで精度を意識した EXIT ゲートを調整します (標準モードでは効果がありません)。円形のジオフェンスは、GPS エラー円全体がフェンスを通過した場合にのみ終了します (distance - accuracy > radius + buffer)。これにより、デバイスが小さなフェンス内に静止している間、単一の高ドリフト修正によって誤った EXIT が発生するのを防ぐことができます。その代償として、GPS の不確かさの分だけ本物の終了が遅れることになります。

    • -1 (デフォルト) — 完全なゲート。誤終了に対して最も耐性があります。
    • 0 — ゲートが無効になっています。最も速く終了しますが、ドリフトが発生しやすくなります (プレフィックス動作)。
    • N > 0 — N メーターへのクランプ精度。 N までのドリフトを吸収し、最悪の場合の終了遅延を ~N メートルに制限します。 GPS ドリフトと誤った終了を参照 📖

📡 HttpConfig (config.http)

ネットワーク同期エンジンを制御します。 同期ストーリーを参照 📖

  • url: String? (デフォルト: null) バックエンドのエンドポイント。
  • method: HttpMethod (デフォルト: HttpMethod.post)
  • headers: Map<String, String>? (デフォルト: null) カスタム認証ヘッダー。動的な JWT ローテーションについては、コールバックを参照 📖
  • params: Map<String, Object?>? (デフォルト: null)
  • extras: Map<String, Object?>? (デフォルト: null) 静的 JSON データがすべてのロケーション ペイロードに挿入されます。
  • httpRootProperty: String? (デフォルト: 'location') JSON ルート ノード。
  • autoSync: bool (デフォルト: true) 自動的にアップロードされます。 false の場合、Tracelet.sync() を呼び出す必要があります。
  • batchSync: bool (デフォルト: false) 1 行 1 列ではなく、位置の配列をアップロードします。
  • maxBatchSize: int (デフォルト: 250)
  • autoSyncThreshold: int (デフォルト: 0) 同期をトリガーする前に必要な SQLite レコードの数。
  • autoSyncDelay: int (デフォルト: 10000) 場所が到着したら、同期するまで待つようお願いします。
  • syncInterval: int (デフォルト: 0) オフライン キューの時間ベースのフラッシュを繰り返す間隔の秒数。 > 0 の場合、SDK は、新しい挿入時に発生する autoSyncDelay デバウンスとは関係なく、この周期で保留中の場所を定期的にアップロードします。蓄積されたレコードの数に関係なく、時間ベースのフラッシュに役立ちます。 0 はインターバル タイマーを無効にします。
  • httpTimeout: int (デフォルト: 60000)
  • locationsOrderDirection: LocationOrderDirection (デフォルト: LocationOrderDirection.ascending)
  • disableAutoSyncOnCellular: bool (デフォルト: false) Wi-Fi 接続時のみ同期してユーザー データ プランを保存します。
  • maxRetries: int (デフォルト: 3)
  • retryBackoffBase: int (デフォルト: 1000)
  • retryBackoffCap: int (デフォルト: 60000)
  • enableDeltaCompression: bool (デフォルト: false) デルタ座標のみを送信し、JSON ペイロード サイズを 80% 削減します。
  • deltaCoordinatePrecision: int (デフォルト: 5)
  • sslPinningFingerprints: List<String>? (デフォルト: null)
  • sslPinningCertificates: List<String>? (デフォルト: null)
  • syncTelematics: bool (デフォルト: false) 保存された運転/衝撃イベントを現在地と一緒にアップロードします。デフォルトではオフになっているため、既存のペイロードが変更されることはありません。 テレマティクス同期を参照 📖
  • telematicsUrl: String? (デフォルト: null) テレマティクスを位置ペイロードに添付する代わりに、{"telematics": [...]} として独自のエンドポイントに送信します。 syncTelematics が必要です。空の文字列 (null ではない) を渡して、添付されたパスに戻ります。構成は置き換えられずにマージされます。

🏢 エンタープライズ構成

AuditConfig (config.audit)

  • enabled: bool (デフォルト: false) 位置ハッシュの暗号化された改ざん防止ブロックチェーンを作成します。
  • hashAlgorithm: HashAlgorithm (デフォルト: HashAlgorithm.sha256) 現在、チェーンは常に SHA-256 を使用します。別のアルゴリズムの選択はまだ適用されていません。
  • includeExtrasInHash: bool (デフォルト: false) — ⚠️ 非推奨: 実装されていません。 チェーンは常にコアの場所フィールドのみをハッシュするため、このフラグは何も変更しません。 これを接続すると、以前に計算されたすべてのチェーンが無効になるため、バージョン管理されたチェーンが必要です。 サイレントな動作変更ではなく、連鎖的な移行です。

SecurityConfig (config.security)

  • encryptionKey: String? (デフォルト: null) SQLCipher を使用して SQLite データベースを暗号化します。 暗号化を参照 📖

PrivacyZoneConfig (config.privacy)

AttestationConfig (config.attestation)

  • enabled: bool (デフォルト: false) Play Integrity (Android) と App Attest (iOS) を使用して、デバイスがエミュレータではなく本物であることを暗号的に証明します。
  • refreshInterval: int (デフォルト: 86400)
  • verificationUrl: String? (デフォルト: null) — ⚠️ 非推奨: 実装されていません。 サーバー側の検証のために構成証明トークンをどこにも送信するものはありません。トークンは すでに同期ペイロードに含まれています。代わりに独自のバックエンドで確認してください。
エンタープライズ機能診断ツール