🚀 移行ガイド: `flutter_background_geolocation` → Tracelet

flutter_background_geolocation から Tracelet に切り替えますか?素晴らしい選択です！ Tracelet は、1:1 互換の API を備えた完全なオープンソース (Apache 2.0) の代替品であり、カルマンフィルタリング、モック検出、プライバシーゾーンなどの追加機能を備えています。ライセンスキー、独自の SDK、完全なソースコードは不要です。

💡 このガイドは常に現在のリリースを反映しています。

⚡ 3段階スピードラン

本当に、これは速いです。

ステップ 1 — 依存関係を交換します:


# Before
dependencies:
  flutter_background_geolocation: ^5.x.x

後✨


dependencies:
  tracelet: ^3.6.14

ステップ 2 — インポートを更新します:


// Before
import 'package:flutter_background_geolocation/flutter_background_geolocation.dart' as bg;
 
// After — short & sweet ✅
import 'package:tracelet/tracelet.dart' as tl;

ステップ 3 — クラス名を検索して置換します:


// Before
bg.BackgroundGeolocation.ready(bg.Config(...));
 
// After
tl.Tracelet.ready(tl.Config.balanced().copyWith(...));

文字通りこれです。 すべてのメソッド、すべてのイベント、すべてのコールバック - 1:1 互換性があります。このガイドの残りの部分は、詳細を説明するための単なるチートシートです。

🏗️ 構成: フラットから構造化へ

以前のプラグインは、すべてのフィールドが 1 つのレベルにある単一のフラットな Config() を使用します。 Tracelet はそれらを論理セクションに整理するため、大規模な構成の読み取りと保守がはるかに簡単になります。


// Before — flat config
bg.Config(
  desiredAccuracy: bg.Config.DESIRED_ACCURACY_HIGH,
  distanceFilter: 10.0,
  stopOnTerminate: false,
  startOnBoot: true,
  stopTimeout: 5,
  url: 'https://api.example.com/locations',
  batchSync: true,
  autoSync: true,
  headers: {'Authorization': 'Bearer $token'},
  heartbeatInterval: 60,
  notification: bg.Notification(title: 'Tracking', text: 'Active'),
  debug: true,
  logLevel: bg.Config.LOG_LEVEL_VERBOSE,
);
 
// After — organized by section 🏠
tl.Config(
  geo: tl.GeoConfig(
    desiredAccuracy: tl.DesiredAccuracy.high,   // typed enums!
    distanceFilter: 10.0,
  ),
  app: tl.AppConfig(
    stopOnTerminate: false,
    startOnBoot: true,
    heartbeatInterval: 60,
  ),
  android: tl.AndroidConfig(
    foregroundService: tl.ForegroundServiceConfig(
      notificationTitle: 'Tracking',
      notificationText: 'Active',
    ),
  ),
  motion: tl.MotionConfig(
    stopTimeout: 5,
  ),
  http: tl.HttpConfig(
    url: 'https://api.example.com/locations',
    batchSync: true,
    autoSync: true,
    headers: {'Authorization': 'Bearer $token'},
  ),
  logger: tl.LoggerConfig(
    debug: true,
    logLevel: tl.LogLevel.verbose,   // readable enum instead of int constants
  ),
);

構成セクションの概要:

geo → GeoConfig — 精度、距離フィルター、弾性、周期モード、カルマンフィルター、モック検出
app → AppConfig — ライフサイクル、ハートビート、スケジュール
android → AndroidConfig — 🆕 Android のみ: フォアグラウンドサービス通知、位置情報の更新間隔、AlarmManager、定期的な戦略
ios → IosConfig — 🆕 iOS のみ: アクティビティタイプ、バックグラウンドセッション、一時停止の防止
motion → MotionConfig — タイムアウト、アクティビティ認識、加速度センサーのみのモードを停止します。
http → HttpConfig — 同期 URL、ヘッダー、バッチ処理、再試行バックオフ、Wi-Fi 専用モード
logger → LoggerConfig — ログレベル、最大日数、デバッグサウンド
geofence → GeofenceConfig — 近接半径、初期トリガー、ノックアウトモード
persistence → PersistenceConfig — 永続モード、最大日数/レコード、テンプレート
audit → AuditConfig — 🆕 SHA-256 ハッシュチェーン — 改ざん防止が重要であるため
privacyZone → PrivacyZoneConfig — 🆕 プライバシーゾーンエンジン — GDPR の親友
security → SecurityConfig — 🆕 保存時のデータベース暗号化 (encryptDatabase)
attestation → AttestationConfig — 🆕 デバイス認証 / 整合性チェック

🗺️ 大きな設定のチートシート

心配しないでください。すべてのフィールドには 1:1 のマッピングがあります。これがロゼッタストーンです。

位置と追跡 → `GeoConfig`


Before                              → Tracelet
─────────────────────────────────────────────────────────────
desiredAccuracy (int: -2…100)       → geo.desiredAccuracy (DesiredAccuracy enum)
                                      .high / .medium / .low / .veryLow / .passive
distanceFilter                      → geo.distanceFilter (default 10m)
stationaryRadius                    → geo.stationaryRadius (default 25m)
locationTimeout                     → geo.locationTimeout (default 60s)
disableElasticity                   → geo.disableElasticity
elasticityMultiplier                → geo.elasticityMultiplier (default 1.0)
stopAfterElapsedMinutes             → geo.stopAfterElapsedMinutes (-1 = disabled)
enableTimestampMeta                 → geo.enableTimestampMeta
maxMonitoredGeofences               → geo.maxMonitoredGeofences (-1 = platform default)

Android 固有のフィールド → AndroidConfig:


Before                              → Tracelet
─────────────────────────────────────────────────────────────
locationUpdateInterval              → android.locationUpdateInterval (1000ms)
fastestLocationUpdateInterval       → android.fastestLocationUpdateInterval (500ms)
deferTime                           → android.deferTime
allowIdenticalLocations             → android.allowIdenticalLocations
geofenceModeHighAccuracy            → geofence.geofenceModeHighAccuracy (cross-platform; android.* is deprecated)
scheduleUseAlarmManager             → android.scheduleUseAlarmManager

iOS 固有のフィールド → IosConfig:


Before                              → Tracelet
─────────────────────────────────────────────────────────────
activityType                        → ios.activityType (LocationActivityType enum)
useSignificantChangesOnly           → ios.useSignificantChangesOnly
showsBackgroundLocationIndicator    → ios.showsBackgroundLocationIndicator
pausesLocationUpdatesAutomatically  → ios.pausesLocationUpdatesAutomatically
locationAuthorizationRequest        → ios.locationAuthorizationRequest
disableLocationAuthorizationAlert   → ios.disableLocationAuthorizationAlert
preventSuspend                      → ios.preventSuspend

🆕 Tracelet 専用の GeoConfig フィールド:

geo.enableAdaptiveMode — アクティビティ + バッテリー + 速度に応じて距離フィルターを調整します
geo.periodicLocationInterval — デフォルト 900 秒 (15 分)
geo.filter (LocationFilter) — カルマン、モック検出、精度しきい値

🧹 場所フィルター → `LocationFilter` (Tracelet 限定!)

🆕 filter.policy — LocationFilterPolicy.adjust / .ignore / .discard
🆕 filter.useKalmanFilter — 4 状態の拡張カルマンフィルター — プロのように GPS ノイズを滑らかにします
🆕 filter.mockDetectionLevel — .disabled / .basic / .heuristic — 偽装された位置情報を捕捉します
🆕 filter.rejectMockLocations — 疑似ロケーションを自動拒否する
🆕 filter.maxImpliedSpeed — スパイクフィルター — 「いいえ、ユーザーはテレポートしませんでした」
🆕 filter.trackingAccuracyThreshold — 許容される最小精度
🆕 filter.odometerAccuracyThreshold — オドメーター更新の最小精度

動き検出 → `MotionConfig`


Before                                → Tracelet
─────────────────────────────────────────────────────────────
stopTimeout                            → motion.stopTimeout (default 5 min)
motionTriggerDelay                     → motion.motionTriggerDelay
disableMotionActivityUpdates           → motion.disableMotionActivityUpdates
                                         (set true for accelerometer-only, no permission!)
isMoving                               → motion.isMoving (initial state)
activityRecognitionInterval            → motion.activityRecognitionInterval (10000ms)
minimumActivityRecognitionConfidence   → motion.minimumActivityRecognitionConfidence (75)
disableStopDetection                   → motion.disableStopDetection
stopDetectionDelay                     → motion.stopDetectionDelay
stopOnStationary                       → motion.stopOnStationary
triggerActivities                      → motion.activityTypes (Set<ActivityType>)

🆕 Tracelet 専用の MotionConfig フィールド:

motion.motionDetectionMode — .accelerometer / .speed / .smart — 動きの検出方法 (スマート = 加速度計 および GPS 速度、推奨)
motion.shakeThreshold — 加速度センサーのみのチューニング (デフォルトは 2.5)
motion.stillThreshold — 加速度計のみのチューニング (デフォルト 0.4)
motion.stillSampleCount — 加速度計のみの調整 (デフォルトは 25)
motion.speedMovingThreshold / motion.speedStationaryDelay / motion.speedWakeConfirmCount — 速度モード調整 (.speed / .smart で使用)
motion.stationaryTrackingMode / motion.stationaryPeriodicInterval / motion.stationaryPeriodicAccuracy — 静止後に何をするか (定期的な修正とジオフェンス)

アプリケーション → `AppConfig`


Before                   → Tracelet
─────────────────────────────────────────────────────────────
stopOnTerminate          → app.stopOnTerminate (default true)
startOnBoot              → app.startOnBoot (default false)
heartbeatInterval        → app.heartbeatInterval (default 60s)
schedule                 → app.schedule (cron-like expressions)

注意: scheduleUseAlarmManager → android.scheduleUseAlarmManager | preventSuspend → ios.preventSuspend

🔔 フォアグラウンドサービス通知 → `AndroidConfig.foregroundService`

重要 (2.x.x の変更): フォアグラウンドサービス通知は、app ではなく android.foregroundService (AndroidConfig) で構成されるようになりました。これは Android のみの概念です。


Before (Notification)     → Tracelet (AndroidConfig.foregroundService)
─────────────────────────────────────────────────────────────
title                     → android.foregroundService.notificationTitle
text                      → android.foregroundService.notificationText
color                     → android.foregroundService.notificationColor
smallIcon                 → android.foregroundService.notificationSmallIcon
largeIcon                 → android.foregroundService.notificationLargeIcon
priority                  → android.foregroundService.notificationPriority
channelName               → android.foregroundService.channelName
channelId                 → android.foregroundService.channelId
sticky                    → android.foregroundService.notificationOngoing
actions                   → android.foregroundService.actions
enabled                   → android.foregroundService.enabled

HTTP 同期 → `HttpConfig`


Before                    → Tracelet
─────────────────────────────────────────────────────────────
url                       → http.url (null = sync disabled)
method                    → http.method (HttpMethod.post / .put)
headers                   → http.headers
httpRootProperty          → http.httpRootProperty (default 'location')
batchSync                 → http.batchSync
maxBatchSize              → http.maxBatchSize
autoSync                  → http.autoSync
autoSyncThreshold         → http.autoSyncThreshold
httpTimeout               → http.httpTimeout (default 60000ms)
params                    → http.params
extras                    → http.extras
locationsOrderDirection   → http.locationsOrderDirection (LocationOrder enum)

🆕 Tracelet 専用の HttpConfig フィールド:

http.disableAutoSyncOnCellular — Wi-Fi のみの同期 — データプランを節約しましょう!
http.maxRetries — デフォルトは 10、指数バックオフ + ジッターあり
http.retryBackoffBase — デフォルト 1000ms
http.retryBackoffCap — デフォルト 300000ms (5 分)

ジオフェンシング → `GeofenceConfig`


Before                        → Tracelet
─────────────────────────────────────────────────────────────
geofenceProximityRadius       → geofence.geofenceProximityRadius (default 1000m)
geofenceInitialTriggerEntry   → geofence.geofenceInitialTriggerEntry (default true)

🆕 geofence.geofenceModeKnockOut — 最初の終了後にジオフェンスを自動削除 — 1 つで完了です。

永続化 → `PersistenceConfig`


Before                        → Tracelet
─────────────────────────────────────────────────────────────
persistMode                   → persistence.persistMode (.all / .location / .geofence / .none)
maxDaysToPersist              → persistence.maxDaysToPersist (-1 = forever)
maxRecordsToPersist           → persistence.maxRecordsToPersist (-1 = unlimited)
locationTemplate              → persistence.locationTemplate (Mustache-style)
geofenceTemplate              → persistence.geofenceTemplate (Mustache-style)
disableProviderChangeRecord   → persistence.disableProviderChangeRecord
extras                        → persistence.extras

ロギング → `LoggerConfig`


Before                 → Tracelet
─────────────────────────────────────────────────────────────
logLevel (int const)   → logger.logLevel (.verbose / .debug / .info / .warning / .error)
logMaxDays             → logger.logMaxDays (default 3)
debug                  → logger.debug (alert sounds — fun at demos, terrifying at 3 AM)

🔐 監査証跡 → `AuditConfig` (Tracelet 専用)

audit.enabled — デフォルトでは false。すべての場所の SHA-256 ハッシュチェーン - 改ざん = 破棄
audit.hashAlgorithm — NOTTRANS1LATE
audit.includeExtrasInHash — デフォルトでは false

🛡️ プライバシーゾーン → `PrivacyZoneConfig` (Tracelet 専用)

privacyZone.enabled — デフォルトでは false。プライバシーゾーンエンジンを有効にします。

🎯 精度定数 — 型付き列挙型!


Before (int constants)                    → Tracelet (typed enum)
─────────────────────────────────────────────────────────────
Config.DESIRED_ACCURACY_NAVIGATION        → DesiredAccuracy.high
Config.DESIRED_ACCURACY_HIGH              → DesiredAccuracy.high
Config.DESIRED_ACCURACY_MEDIUM            → DesiredAccuracy.medium
Config.DESIRED_ACCURACY_LOW               → DesiredAccuracy.low
Config.DESIRED_ACCURACY_VERY_LOW          → DesiredAccuracy.veryLow
Config.DESIRED_ACCURACY_LOWEST            → DesiredAccuracy.passive

📡 イベント — 同じ名前で、入力は少なくなります

14 個のイベントストリームはすべて 1:1 にマッピングされます。接頭辞を交換するだけです。


Before                     → Tracelet                     Callback Type
─────────────────────────────────────────────────────────────────────────
onLocation(cb)             → onLocation(cb)               Location
onMotionChange(cb)         → onMotionChange(cb)           Location
onActivityChange(cb)       → onActivityChange(cb)         ActivityChangeEvent
onProviderChange(cb)       → onProviderChange(cb)         ProviderChangeEvent
onGeofence(cb)             → onGeofence(cb)               GeofenceEvent
onGeofencesChange(cb)      → onGeofencesChange(cb)        GeofencesChangeEvent
onHeartbeat(cb)            → onHeartbeat(cb)              HeartbeatEvent
onHttp(cb)                 → onHttp(cb)                   HttpEvent
onSchedule(cb)             → onSchedule(cb)               State
onPowerSaveChange(cb)      → onPowerSaveChange(cb)        bool
onConnectivityChange(cb)   → onConnectivityChange(cb)     ConnectivityChangeEvent
onEnabledChange(cb)        → onEnabledChange(cb)          bool
onNotificationAction(cb)   → onNotificationAction(cb)     String
onAuthorization(cb)        → onAuthorization(cb)          AuthorizationEvent
N/A                        → 🆕 onTrip(cb)                TripEvent (auto-detected trips!)
N/A                        → 🆕 onRemoteConfig(cb)        Config (remote config applied)
removeListeners()          → removeListeners()            Cancels all subscriptions


// Before — so many characters...
bg.BackgroundGeolocation.onLocation((bg.Location location) {
  print('[location] $location');
});
 
// After — ahh, much better
tl.Tracelet.onLocation((tl.Location location) {
  print('[location] $location');
});

🔧 メソッド — 完全なマッピング

ライフサイクル


Before                                → Tracelet
─────────────────────────────────────────────────────────────
bg.BackgroundGeolocation.ready(cfg)   → tl.Tracelet.ready(cfg)
bg.BackgroundGeolocation.start()      → tl.Tracelet.start()
bg.BackgroundGeolocation.stop()       → tl.Tracelet.stop()
bg.BackgroundGeolocation.startGeofences()  → tl.Tracelet.startGeofences()
N/A                                   → 🆕 tl.Tracelet.startPeriodic()
bg.BackgroundGeolocation.getState()   → tl.Tracelet.getState()
bg.BackgroundGeolocation.setConfig()  → tl.Tracelet.setConfig()
bg.BackgroundGeolocation.reset()      → tl.Tracelet.reset()
N/A                                   → 🆕 tl.Tracelet.getHealth()

位置


Before                     → Tracelet
─────────────────────────────────────────────────────────────
getCurrentPosition(...)    → getCurrentPosition(...)
                             same params: desiredAccuracy, timeout,
                             maximumAge, persist, samples, extras
N/A                        → 🆕 getLastKnownLocation() — zero battery cost!
watchPosition(cb, ...)     → watchPosition(cb, ...) — returns watchId
stopWatchPosition(id)      → stopWatchPosition(id)
changePace(isMoving)       → changePace(isMoving)
N/A                        → 🆕 updateLocationProviderOptions() — live
                             accuracy/filter override, no pipeline restart
getOdometer()              → getOdometer()
setOdometer(value)         → setOdometer(value)
resetOdometer()            → setOdometer(0) — one less method to remember

ジオフェンシング


Before              → Tracelet
─────────────────────────────────────────────────────────────
addGeofence(g)      → addGeofence(g)
addGeofences(list)  → addGeofences(list)
removeGeofence(id)  → removeGeofence(id)
removeGeofences()   → removeGeofences()
getGeofences()      → getGeofences()
N/A                 → 🆕 getGeofence(id) — get one without fetching all
N/A                 → 🆕 geofenceExists(id) — quick existence check

永続性と同期


Before                   → Tracelet
─────────────────────────────────────────────────────────────
getLocations()           → getLocations([SQLQuery?]) — optional filtering!
getCount()               → getCount()
destroyLocations()       → destroyLocations()
destroyLocation(uuid)    → destroyLocation(uuid)
insertLocation(params)   → insertLocation(params) — returns UUID
sync()                   → sync()

権限 — 何日もの間ヘルパーがいます


Before               → Tracelet
─────────────────────────────────────────────────────────────
requestPermission()  → requestLocationAuthorization()
N/A                  → 🆕 getLocationAuthorization()
N/A                  → 🆕 hasBackgroundPermission (getter)
N/A                  → 🆕 getNotificationAuthorization()
N/A                  → 🆕 requestNotificationAuthorization()
N/A                  → 🆕 getMotionAuthorization()
N/A                  → 🆕 requestMotionAuthorization()
N/A                  → 🆕 requestTemporaryFullAccuracyAuthorization(purpose) — iOS 14+
N/A                  → 🆕 canScheduleExactAlarms() — Android 12+
N/A                  → 🆕 openExactAlarmSettings()
N/A                  → 🆕 openAppSettings()
N/A                  → 🆕 openLocationSettings()
N/A                  → 🆕 openBatterySettings()
N/A                  → 🆕 isIgnoringBatteryOptimizations()

ロギング


Before              → Tracelet
─────────────────────────────────────────────────────────────
getLog()            → getLog([SQLQuery?]) — optional filtering
destroyLog()        → destroyLog()
emailLog(email)     → emailLog(email)
log(level, msg)     → log(level, msg)

スケジュール、バックグラウンドタスク、ヘッドレス


Before                     → Tracelet
─────────────────────────────────────────────────────────────
startSchedule()            → startSchedule()
stopSchedule()             → stopSchedule()
startBackgroundTask()      → startBackgroundTask()
stopBackgroundTask(id)     → stopBackgroundTask(id)
registerHeadlessTask(cb)   → registerHeadlessTask(cb)

ユーティリティ


Before               → Tracelet
─────────────────────────────────────────────────────────────
getProviderState()   → getProviderState()
getSensors()         → getSensors()
getDeviceInfo()      → getDeviceInfo()
playSound(name)      → playSound(name)
isPowerSaveMode      → isPowerSaveMode
N/A                  → 🆕 getSettingsHealth() — detects OEM battery killers
N/A                  → 🆕 openOemSettings(label) — opens OEM settings page
N/A                  → 🆕 requestSettings(action)
N/A                  → 🆕 showSettings(action)

🔐 監査証跡 (Tracelet のみ — エンタープライズグレードの整合性)

verifyAuditTrail() — SHA-256 ハッシュチェーンを確認します — 何かが改ざんされていましたか?
getAuditProof(uuid) — 特定の位置レコードの暗号証明

addPrivacyZone(zone) — アクションを含むゾーンを追加します: 除外 / 劣化 / イベントのみ
addPrivacyZones(list) — 一括追加
removePrivacyZone(id) — 識別子による削除
removePrivacyZones() — すべて削除
getPrivacyZones() — すべてのゾーンをリストする

🎁 Tracelet 専用の機能

Tracelet で得られる機能のうち、flutter_background_geolocation では利用できない機能:

定期モード — Tracelet.startPeriodic() — WorkManager 経由で N 分ごとに GPS を修正します。フォアグラウンドサービス、通知、バッテリーの消耗はありません。
カルマンフィルター — geo.filter.useKalmanFilter: true — 4 状態 EKF は GPS ノイズを平滑化します。あなたのトラックは酔っているのではなく、プロフェッショナルに見えます。
適応サンプリング — geo.enableAdaptiveMode: true — アクティビティ + バッテリー + 速度に基づいて距離フィルターを自動調整します。
モック検出 (3 レベル) — geo.filter.mockDetectionLevel — 衛星数、リアルタイムドリフト、およびタイムスタンプ分析を通じて GPS スプーフィングを検出します。
プライバシーゾーン — addPrivacyZone() — 機密領域の追跡を除外、低下、または制限します。 GDPR 準拠が組み込まれています。
監査証跡 — verifyAuditTrail() — SHA-256 ハッシュチェーン。位置データが改ざんされていないことを証明します。
ヘルスチェック — getHealth() — 1 回の電話で、権限、GPS、バッテリー、OEM の問題、12 件の自動警告など、すべてがわかります。
OEM 互換性 — getSettingsHealth() — Huawei、Xiaomi、Samsung、OPPO の攻撃的なバッテリーキラーを検出し、それらを修正する方法をユーザーに通知します。
トリップ検出 — onTrip(cb) — 距離、所要時間、ウェイポイント、平均速度を使用してトリップを自動検出します。
ポリゴンジオフェンス — Geofence(vertices: [...]) — 円だけではありません。レイキャスティングポリゴンサポートを使用して任意の形状を描画します。
ジオフェンスノックアウト — geofence.geofenceModeKnockOut — 最初の終了後にジオフェンスが自動削除されます。 1 回限りのアラートに最適です。
ジオフェンスルックアップ — getGeofence(id) — すべてをロードせずに単一のジオフェンスをクエリします。
権限ヘルパー — openAppSettings()、openBatterySettings() — システム設定への直接ディープリンク。
スマートな再試行 — http.maxRetries + バックオフ — ジッターのある指数関数的バックオフ。あなたのサーバーはあなたに感謝するでしょう。
Wi-Fi のみの同期 — http.disableAutoSyncOnCellular — モバイルデータを節約し、Wi-Fi でのみ同期します。
加速度計のみのモーション — motion.shakeThreshold — アクティビティ認識権限なしでモーションを検出します。許可ゼロのポップアップ。
Web サポート — 同じ Dart API がブラウザ内でフォアグラウンド (タブ内) トラッキング用に実行されます。バックグラウンド追跡といくつかのネイティブ機能は利用できません。Web サポートを参照してください。

🤷 Tracelet にまだ含まれていない機能

以前のプラグインのいくつかの機能はまだ利用できません。これらは計画的に行われるか、簡単に回避できます。

サーバー側ジオフェンス同期 — 計画中 現時点では、API から取得して addGeofences() を呼び出します。
locationTemplate 補間 — 宣言されており、配線されていません。 onLocation コールバックで変換するか、http.extras を使用します。
JWT 自動リフレッシュ — 宣言されており、接続されていません。 http.headers を手動で設定します。 onAuthorizationを聴いてください。
デモサーバー — 計画されていません。 独自のバックエンドを使用します。任意の REST エンドポイントが機能します。
ライセンスキーのアクティベーション — 🎉 必要ありません。オープンソースです。

🛠️ 段階的な移行

ステップ 1: `pubspec.yaml` を更新する


dependencies:
  tracelet: ^3.6.14

flutter_background_geolocation およびすべてのライセンスキーパッケージを削除します。もう必要ありません。

ステップ 2: Android のセットアップ

INSTALL-ANDROID.md を参照してください。主な違い:

オプションの依存関係 — 🆕 Tracelet 2.0.0 以降では、高精度の GMS 追跡が必要な場合、play-services-location を build.gradle に明示的に追加する必要があります。それ以外の場合は、標準の AOSP GPS に戻ります。
ライセンスキーなし - AndroidManifest.xml から BackgroundGeolocation.org 構成を削除します
権限 — Gradle 経由で自動マージされ、宣言する必要はありません
minSdkVersion — API 21+ (以前と同じ)
Kotlin — すべてのネイティブコードは Kotlin です

ステップ 3: iOS のセットアップ

INSTALL-IOS.md を参照してください。主な違い:

ライセンスキーなし — 以前のプラグインの plist エントリを削除します
バックグラウンドモード — 同じ: 位置情報更新、バックグラウンド取得、リモート通知
Info.plist — 同じ使用法の説明キー (NSLocationAlwaysAndWhenInUseUsageDescription など)
Podfile — 以前のプラグインのポッドソースを削除します

ステップ 4: 構成を更新する

フラット Config() → 複合 Config() に変換します。上記の 構成: フラットから構造化へ セクションを参照してください。

bg.BackgroundGeolocation.onXxx → tl.Tracelet.onXxx を検索して置換します。


// Before
bg.BackgroundGeolocation.onLocation((bg.Location location) {
  print('[location] $location');
});
 
// After
tl.Tracelet.onLocation((tl.Location location) {
  print('[location] $location');
});

ステップ 6: ライフサイクル呼び出しを更新する


// Before
bg.BackgroundGeolocation.ready(config).then((bg.State state) {
  if (!state.enabled) bg.BackgroundGeolocation.start();
});
 
// After
tl.Tracelet.ready(config).then((tl.State state) {
  if (!state.enabled) tl.Tracelet.start();
});


// Before
@pragma('vm:entry-point')
void backgroundGeolocationHeadlessTask(bg.HeadlessEvent event) async {
  switch (event.name) {
    case bg.Event.LOCATION:
      bg.Location location = event.event;
      break;
  }
}
 
void main() {
  bg.BackgroundGeolocation.registerHeadlessTask(backgroundGeolocationHeadlessTask);
  runApp(MyApp());
}
 
// After — shorter function name is a bonus 😎
@pragma('vm:entry-point')
void headlessTask(tl.HeadlessEvent event) async {
  switch (event.name) {
    case 'location':
      tl.Location location = event.event as tl.Location;
      break;
  }
}
 
void main() {
  tl.Tracelet.registerHeadlessTask(headlessTask);
  runApp(MyApp());
}

📦 HTTP ペイロード: スネークケース → キャメルケース

バックエンド開発者の皆様、注意してください! サーバー上で更新すべきことが 1 つあります。

flutter_background_geolocation がこれを送信します:


{
  "location": {
    "coords": { "latitude": 37.42, "longitude": -122.08, "accuracy": 12.3 },
    "timestamp": "2026-03-06T10:30:00.000Z",
    "is_moving": true,
    "uuid": "abc-123",
    "odometer": 1234.5,
    "activity": { "type": "walking", "confidence": 85 },
    "battery": { "level": 0.72, "is_charging": false },
    "extras": { "custom_key": "custom_value" }
  }
}

Tracelet はこれを送信します:


{
  "location": {
    "coords": { "latitude": 37.42, "longitude": -122.08, "accuracy": 12.3 },
    "timestamp": "2026-03-06T10:30:00.000Z",
    "isMoving": true,
    "uuid": "abc-123",
    "odometer": 1234.5,
    "isMock": false,
    "activity": { "type": "walking", "confidence": 85 },
    "battery": { "level": 0.72, "isCharging": false },
    "extras": { "custom_key": "custom_value" }
  }
}

TL;DR: is_moving → isMoving、is_charging → isCharging、および新しい isMock フィールド。 JSON 解析を更新すれば、完璧です。

🚨 よくある落とし穴

これらを難しい方法で学ばないでください。すでに学習しています。

Config は複合になりました — GeoConfig(...)、AppConfig(...)、HttpConfig(...) などでフィールドをラップします。
desiredAccuracy: -1 は機能しません — DesiredAccuracy.high を使用します — マジックナンバーではなく、型付き列挙型を使用します
logLevel: 5 は機能しません — LogLevel.verbose を使用します
resetOdometer() が見つかりません — 現在は setOdometer(0) です
notification: プロパティがなくなった — android: (AndroidConfig) 内の app ではなく foregroundService: ForegroundServiceConfig(...) です
scheduleUseAlarmManager は AppConfig にありません — 現在は android.scheduleUseAlarmManager です
preventSuspend は AppConfig にありません — 現在は ios.preventSuspend です
バックエンドは is_moving を解析できません — 現在は isMoving です (キャメルケース)
ライセンスキーコードをまだお持ちですか? — 削除します — Tracelet には必要ありません
State プロパティの外観が異なります — API リファレンスを確認してください
HeadlessEvent.event 型エラー — キャストします: event.event as tl.Location

📚 その他のリソース

API リファレンス — すべてのメソッド、すべてのパラメータ
構成ガイド — すべての構成オプションについて詳しく説明します
バックグラウンドトラッキング — アプリが終了しても生き残る方法
Android インストール — Android 固有のセットアップ
iOS インストール — iOS 固有のセットアップ
GitHub の問題 — スタックしていますか?私たちにはあなたがいます

オープンソース側へようこそ。クッキーをご用意しております。 🍪

🚀 移行ガイド: flutter_background_geolocation → Tracelet