🚀 迁移指南：flutter_background_geolocation → Tracelet
从 flutter_background_geolocation 切换到 Tracelet？很棒的选择！ Tracelet 是一个完全开源 (Apache 2.0) 的替代方案，具有 1:1 兼容的 API — 以及卡尔曼过滤、模拟检测、隐私区域等附加功能。没有许可证密钥，没有专有的 SDK，完整的源代码。
💡 本指南始终反映当前版本。
⚡ 三步速度跑
说真的，这么快。
第 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 兼容。本指南的其余部分只是详细信息的备忘单。
🏗️ 配置：从扁平化到结构化
上一个插件使用单个平面 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.scheduleUseAlarmManageriOS 特定字段 → 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.periodicDesiredAccuracy— 默认.mediumgeo.filter(LocationFilter) — 卡尔曼、模拟检测、准确性阈值
🧹 位置过滤器 → LocationFilter（Tracelet 独有！）
- 🆕
filter.policy— NOTTRANS1LATE / NOTTRANS2LATE / NOTTRANS3LATE - 🆕
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|不传输 2 晚 → 不传输 3 晚
🔔 前台服务通知 → AndroidConfig.foregroundService
重要（2.x.x 更改）： 前台服务通知现在配置在
android.foregroundService（AndroidConfig）下，而不是在app下。这是仅适用于 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.enabledHTTP 同步 → 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— 默认 1000 毫秒http.retryBackoffCap— 默认 300000 毫秒（5 分钟）
地理围栏 → GeofenceConfig
Before → Tracelet
─────────────────────────────────────────────────────────────
geofenceProximityRadius → geofence.geofenceProximityRadius (default 1000m)
geofenceInitialTriggerEntry → geofence.geofenceInitialTriggerEntry (default true)- 🆕
geofence.geofenceModeKnockOut— 第一次退出后自动删除地理围栏 — 一劳永逸！
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 哈希链 — 篡改 = 被破坏- NOTRAN0LATE — 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)调度、后台任务和 Headless
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)— 特定位置记录的加密证明
🛡️ 隐私区域（仅限 Tracelet — GDPR 表示感谢）
addPrivacyZone(zone)— 添加具有以下操作的区域：排除/降级/仅事件addPrivacyZones(list)— 批量添加removePrivacyZone(id)— 按标识符删除removePrivacyZones()— 删除所有getPrivacyZones()— 列出所有区域
🎁 Tracelet-独家功能
通过 Tracelet 获得的功能在 flutter_background_geolocation 中不可用：
- 定期模式 —
Tracelet.startPeriodic()— GPS 通过 WorkManager 每 N 分钟修复一次。没有前台服务，没有通知，没有电池消耗。 - 卡尔曼滤波器 —
geo.filter.useKalmanFilter: true— 4 状态 EKF 平滑 GPS 噪声。你的曲目看起来很专业，而不是喝醉了。 - 自适应采样 —
geo.enableAdaptiveMode: true— 根据活动 + 电池 + 速度自动调整距离过滤器。 - 模拟检测（3 级） —
geo.filter.mockDetectionLevel— 通过卫星计数、实时漂移和时间戳分析捕获 GPS 欺骗。 - 隐私区域 —
addPrivacyZone()— 排除、降级或限制敏感区域的跟踪。内置 GDPR 合规性。 - 审计跟踪 —
verifyAuditTrail()— SHA-256 哈希链。证明您的位置数据未被篡改。 - 健康检查 —
getHealth()— 一通电话即可告诉您一切：权限、GPS、电池、OEM 问题、12 个自动警告。 - OEM 兼容性 —
getSettingsHealth()— 检测华为、小米、三星、OPPO 上的攻击性电池杀手，并告诉用户如何修复它们。 - 行程检测 —
onTrip(cb)— 自动检测行程的距离、持续时间、航路点和平均速度。 - 多边形地理围栏 —
Geofence(vertices: [...])— 不仅仅是圆圈。使用光线投射多边形支持绘制任何形状。 - 地理围栏淘汰 —
geofence.geofenceModeKnockOut— 地理围栏在第一次退出后自动删除。非常适合一次性警报。 - 地理围栏查找 —
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》。 - License key activation — 🎉 Not needed!它是开源的。
🛠️ 逐步迁移
dependencies:
tracelet: ^3.6.14
删除 flutter_background_geolocation 和任何许可证密钥包。你不再需要它们了！
第 2 步：安卓设置
请参阅 INSTALL-ANDROID.md 。主要区别：
- 可选依赖项 — 如果您想要高精度 GMS 跟踪，🆕 Tracelet 2.0.0+ 要求您显式将
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— 删除以前插件的 pod 源
第 4 步：更新配置
将您的公寓 Config() 改造为复合 Config()。请参阅上面的 配置：从扁平化到结构化 部分。
第 5 步：更新事件监听器
查找并替换 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();
});第 7 步：更新 Headless 任务
// 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 负载：snake_case→camelCase
请注意，后端开发人员！ 在服务器上需要更新的一件事。
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) 内部是foregroundService: ForegroundServiceConfig(...)，而不是appscheduleUseAlarmManager不在 AppConfig 中 — 现在是android.scheduleUseAlarmManagerpreventSuspend不在 AppConfig 中 — 现在是ios.preventSuspend- 后端无法解析
is_moving— 现在是isMoving(camelCase) - 仍然有许可证密钥代码吗？ — 删除它 — Tracelet 不需要它
State属性看起来不同 — 检查 API 参考HeadlessEvent.event类型错误 — 转换为：event.event as tl.Location
📚 更多资源
- API 参考 — 每个方法，每个参数
- 配置指南 — 深入了解所有配置选项
- 后台跟踪 — 它如何在应用程序被杀死后幸存下来
- Android 安装 — Android 特定设置
- iOS 安装 — iOS 特定设置
- GitHub 问题 — 卡住了？我们找到你了
欢迎来到开源方面。 We have cookies. 🍪