Skip to Content
APIリファレンス

徹底的な API リファレンス

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

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

🌍 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 ms の間位置情報をバッチ更新できるようにします。
  • 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)
  • actions: List<String> (デフォルト: [])

🔔 トラッキングが既に実行されているときに通知の変更を適用するには、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+) を使用して実行時に更新します。

📍 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 に代わるものです。どちらかが true の場合、高精度モードが有効になります。

  • geofenceInitialTrigger: bool (デフォルト: true) 登録時にジオフェンスの状態を評価します。
  • geofenceInitialTriggerEntry: bool (デフォルト: true) 登録時にデバイスがすでにジオフェンス内にある場合は、すぐに ENTER を押します。
  • geofenceProximityRadius: int (デフォルト: 1000) 近接ベースの読み込みの半径 (メートル) — この距離内のジオフェンスのみが OS にアクティブに登録されます (iOS 20 のリージョン制限をはるかに超えて管理できます)。

📡 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)

🏢 エンタープライズ構成

AuditConfig (config.audit)

  • enabled: bool (デフォルト: false) 位置ハッシュの暗号化された改ざん防止ブロックチェーンを作成します。
  • hashAlgorithm: HashAlgorithm (デフォルト: HashAlgorithm.sha256)
  • 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)
エンタープライズ機能診断ツール