Skip to Content
API参考

详尽的 API 参考

此页面包含 Tracelet 配置 API 的绝对真实来源。此处列出了可以传递给 Tracelet.ready(Config) 的每个参数。

对于解释为什么您将使用这些参数的真实架构场景，请单击它们旁边的 “查看故事 📖” 链接。

在运行时更新配置 - ready() 与 setConfig()

配置到达插件的方式有两种，它们的含义不同。

Tracelet.ready(config) 建立完整基线。每个字段都是 发送，解析为其有效值。在启动时调用一次 - 或者在启动时再次调用 您想更换整个配置。 Tracelet.reset(config) 的行为 同样的方式。

Tracelet.setConfig(config) 是部分更新。只有你的领域 实际设置被传输；其他一切保留平台拥有的一切 坚持下来了。当一件事需要改变时，这就是您在会议中想要的：

// 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： NOTRAN0LATE 精度/距离，以及 NOTRAN0LATE 重新发布实时通知。

🌍 GeoConfig（未翻译）

控制物理位置、准确性和采样逻辑。 参见地理故事📖

  • desiredAccuracy：DesiredAccuracy （默认：DesiredAccuracy.high） 目标硬件精度。对于 GPS，使用 high，对于蜂窝/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） 自动将坐标反向地理编码为街道地址字符串。

🧹 位置过滤器（NOTRAN0LATE）

在损坏的 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（未翻译）

控制整个应用程序生命周期行为。

  • 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 特定操作系统限制。 参见 Android 故事 📖

  • locationUpdateInterval：int （默认：1000） GPS ping 之间的女士。
  • batteryBudgetPerHour：double （默认：0.0） 目标每小时最大电池消耗百分比。 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） 小图标背景的十六进制颜色。
  • notificationSmallIcon：String? （默认：null） res/drawable 文件夹中纯白色 PNG 的名称。
  • notificationLargeIcon：String? （默认：null）
  • notificationPriority：NotificationPriority （默认：NotificationPriority.defaultPriority）
  • notificationOngoing：bool （默认：true）
  • showNotificationOnPauseOnly：bool （默认：false） 当应用程序在屏幕上时隐藏通知。 当 app.stopOnTerminate 为 false 时被忽略 — 隐藏它会降级前台服务，并且从该窗口中的最近服务中滑动会终止进程 (#378 )。每个 start() 都会记录一次覆盖。 请参阅隐藏通知📖
  • actions：List<String> （默认：[]）
  • notificationStartedAt：int? （默认：null） 经过计时器计数的纪元毫秒（挂钟）。仅当 notificationShowTimer 为 true 时才呈现。每次发布通知时，未来的值都会被固定为当前时间，因此设备时钟校正可以自我修复。 参见已用计时器📖
  • notificationShowTimer：bool （默认：false） 显示来自 notificationStartedAt 的自滴答计数时钟。 Android 无需从您的应用程序重新发布即可推进它。如果不存在 notificationStartedAt，则不会显示计时器。
  • notificationOnlyAlertOnce：bool （默认：false） 仅在第一次发布通知时提醒设备，因此后续内容更新将保持静默。对于在跟踪运行时文本发生变化的任何通知很有用，而不仅仅是计时器。 请参阅安静地更新文本📖

🔔 要应用通知更改当跟踪已在运行时，请在 setConfig() 之后调用 Tracelet.updateNotification()。它会重新发布实时通知，而无需重新启动管道（v3.6.8+）。在 iOS 上，它会刷新正在运行的 Live Activity；在网络上这是一个空操作。

🍎 IosConfig（config.ios）

iOS 特定操作系统限制。 参见 iOS 故事📖

  • activityType：LocationActivityType （默认：LocationActivityType.other） 告诉 iOS 您正在做什么（例如 fitness、navigation），以便它知道何时暂停跟踪。
  • useSignificantChangesOnly：bool （默认：false） 完全依赖于手机信号塔的切换。电池消耗接近于零。
  • showsBackgroundLocationIndicator：bool （默认：false） 显示蓝色药丸指示器。需要 location Xcode 功能。 参见蓝色药丸📖
  • pausesLocationUpdatesAutomatically：bool （默认：false） 如果用户有一段时间没有移动，允许 iOS 关闭 GPS 芯片。
  • locationAuthorizationRequest：LocationAuthorizationRequest （默认：always） 请求哪个权限。
  • disableLocationAuthorizationAlert：bool （默认：false） 如果仅请求“使用时”，则阻止操作系统提示“始终允许”。
  • preventSuspend：bool （默认：false） 播放无声音频以使应用程序 24/7 保持运行状态。需要 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（NOTRAN0LATE）

  • title：String （必填） 静态标题。 ActivityKit 属性在 Activity 运行时是不可变的，因此更改会在下次启动时应用。

  • body：String （必填） 动态状态行，由 updateNotification() 更新。

  • startedAt：int? （默认：null） 经过计时器计数的纪元毫秒（挂钟）。仅当 showTimer 为 true 时才呈现。 参见已用计时器📖

  • showTimer：bool （默认：false） 使用 Text(timerInterval:) 从 startedAt 渲染自滴答计数时钟。 iOS 无需您的应用程序进行任何更新即可实现此功能。如果不存在 startedAt，则不会显示计时器。

    自定义小部件扩展仅在 其自己的 TraceletActivityAttributes.ContentState 副本声明 startedAt 和 showTimer 时才呈现计时器。在这些字段存在之前编写的扩展继续工作 - 额外的值被简单地忽略 - 但在更新结构之前不会显示时钟。 查看更新的代码片段📖

📍地理围栏配置（config.geofence）

跨平台地理围栏行为（iOS + Android）。

  • geofenceModeHighAccuracy：bool （默认：false） 控制如何检测地理围栏转换：

    • false（默认） — 使用操作系统区域监控服务。 低功耗，无 iOS 蓝色指示器，但操作系统强制执行实际的最小半径（约 100 m），并且小或 EXIT 过渡可能不可靠。
    • true — 评估应用内从 连续 GPS 的转换。使小半径（例如 5–50 m）和 EXIT 事件可靠，但代价是更高的电池使用量和 - 在 iOS 上 - 系统“使用中的位置”（蓝色）状态栏指示器（连续 GPS 强制它）。 参见蓝色药丸📖

    这取代了已弃用的 AndroidConfig.geofenceModeHighAccuracy；如果其中一个为 true，则启用高精度模式。

  • geofenceInitialTrigger：bool （默认：true） 评估注册时的地理围栏状态。

  • geofenceInitialTriggerEntry：bool （默认：true） 如果设备在注册时已位于地理围栏内，则立即触发 ENTER。

  • geofenceProximityRadius：int （默认：1000） 基于邻近度的加载的半径（米）——只有此距离内的地理围栏才会主动注册到操作系统（让您管理的区域远远超出 iOS 20 区域限制）。

  • geofenceExitAccuracyMax：int （默认：-1） 在高精度模式下调整精确感知的退出门控（在标准模式下无效）。圆形地理围栏只有在整个 GPS 误差圈越过围栏后才会退出 (distance - accuracy > radius + buffer)，这可以防止单个高漂移修复在设备静止在小围栏内时触发错误退出 - 代价是由于 GPS 不确定性而延迟真正的退出。

    • -1（默认） — 全选通；最能抵抗错误退出。
    • 0 — 门控已禁用；最快的退出，但容易漂移（预先修复行为）。
    • N > 0 — 钳位精度达到 N 米；吸收高达 N 的漂移，同时将最坏情况的退出延迟限制在 ~N 米。 参见 GPS 漂移和错误退出📖

📡 HttpConfig（未翻译）

控制网络同步引擎。 查看同步故事📖

  • 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）以返回到附加路径 - 配置被合并，而不是被替换。

🏢 企业配置

不翻译迟（不翻译迟）

  • enabled：bool （默认：false） 创建一个加密的、防篡改的位置哈希区块链。
  • hashAlgorithm：HashAlgorithm （默认：HashAlgorithm.sha256） 该链目前始终使用 SHA-256；尚未应用选择其他算法。
  • includeExtrasInHash：bool （默认：false） — ⚠️ 已弃用：未实现。 该链始终仅对核心位置字段进行哈希处理，因此该标志不会改变任何内容。 将其连接起来将使之前计算的每个链都无效，因此它需要一个版本化的 链式迁移而不是无声的行为改变。

不翻译迟（不翻译迟）

  • encryptionKey：String? （默认：null） 使用 SQLCipher 加密 SQLite 数据库。 参见加密📖

不翻译迟（不翻译迟）

不翻译迟（不翻译迟）

  • enabled：bool （默认：false） 使用 Play Integrity (Android) 和 App Attest (iOS) 以加密方式证明设备是真实的，而不是模拟器。
  • refreshInterval：int （默认：86400）
  • verificationUrl：String? （默认：null） — ⚠️ 已弃用：未实现。 没有任何东西将证明令牌发送到任何地方以进行服务器端验证。令牌是 已包含在同步有效负载中 - 请在您自己的后端验证它。
企业特色诊断工具