Skip to Content
API参考

详尽的 API 参考

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

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

🌍 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 部分） instead — it now controls both iOS and 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）
  • actions：List<String> （默认：[]）

🔔 要应用通知更改当跟踪已在运行时，请在 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+) 刷新它。

📍地理围栏配置（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 区域限制）。

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

🏢 企业配置

不翻译迟（不翻译迟）

  • enabled：bool （默认：false） 创建一个加密的、防篡改的位置哈希区块链。
  • hashAlgorithm：HashAlgorithm （默认：HashAlgorithm.sha256）
  • includeExtrasInHash：bool （默认：false）

不翻译迟（不翻译迟）

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

不翻译迟（不翻译迟）

不翻译迟（不翻译迟）

  • enabled：bool （默认：false） 使用 Play Integrity (Android) 和 App Attest (iOS) 以加密方式证明设备是真实的，而不是模拟器。
  • refreshInterval：int （默认：86400）
  • verificationUrl：String? （默认：null）
企业特色诊断工具