驾驶与安全

Tracelet可以将原始位置+加速度计流变成有意义的 关于设备如何移动的事件 - 完全在设备上，没有云 来电。 3.3.0中添加，有三个独立的功能：

这是给谁的？ （现实世界的例子）

• 基于使用情况的保险/车队安全 → 驾驶事件为您提供每次行程 没有任何服务器端的危险驾驶图片（急刹车、超速） 加工。
• 送货/现场服务应用程序 → 运输模式可让您将每次行程标记为 驾驶 vs 步行（例如“离开货车，走到门口”）。
• 单独工作者/拼车/个人安全应用程序 → 碰撞和跌倒检测 为您提供一个值得信赖的触发器（带有用户“我很好”取消窗口） 启动 SOS 流程。

您可以启用任何组合 - 它们是独立的。

1. 驾驶赛事（远程信息处理）

30秒版本

// 1. Turn it on (e.g. with a 50 km/h limit for speeding)
await Tracelet.ready(Config(
  telematics: TelematicsConfig(
    enableDrivingEvents: true,
    speedLimitKmh: 50,
  ),
));
 
// 2. Listen
Tracelet.onDrivingEvent((event) {
  print('${event.kind} — severity ${event.severity}');
});
 
// 3. Start tracking as usual
await Tracelet.start();

就是这样。当设备移动时，您将收到如下事件：

harsh_braking — severity 0.82
speeding — severity 0.40

每个字段的含义

每个 DrivingEvent 都有：

调整阈值

所有阈值均以 g 为单位（1 g ≈ 9.81 m/s²，重力）。默认值 遵循常见的保险/车队惯例 - 您很少需要更改它们：

2、运输方式

告诉您用户是否为 still、walking、running、cycling，还是处于 vehicle，通过将加速度计运动与 GPS 速度相结合。

await Tracelet.ready(Config(
  classifier: ClassifierConfig(enableFusedClassifier: true),
));
 
Tracelet.onModeChange((event) {
  print('Now: ${event.mode} (confidence ${event.confidence})');
});

自动调整位置过滤器

距离精确跟踪需要针对不同的情况使用不同的滤波器阈值 活动。步行是一个困难的情况：在 ~1.4 m/s 时，GPS 本底噪声很大 您实际移动距离的一小部分，因此松散的滤波器将抖动记录为 距离。在汽车中则相反——严格的门槛会抛弃真实的东西 移动。

您不能预先选择一个设置。您的用户不会声明“我现在正在慢跑”， 一次训练通常包括步行到步道起点、跑步和跑步 往回走。所以让分类器决定：

await Tracelet.ready(Config(
  classifier: ClassifierConfig(
    enableFusedClassifier: true,        // required
    autoTuneFromTransportMode: true,
  ),
));

当模式提交时，Tracelet 会将四个阈值交换为适合它的值：

慢跑没有刻意划船——它属于 running 范围（6-20 公里/小时）， 这正是为什么面向用户的“慢跑预设”是虚构的。

如何保持可预测性：

• 仅在 承诺 模式更改时才会进行重新调整 - 已经受到信任限制 并由 modeSwitchDwellMs 去抖 - 不会根据传感器读数进行去抖，因此阈值 不能喋喋不休。
• 阈值就地交换。您的里程表在一段时间内保持连续 模式改变而不是丢失一个段。
• 应用的值到达 onModeChange 事件并出现在调试日志中，因此 自动调谐永远不会静音。
• unknown 恢复您配置的任何内容。 Tracelet 不会猜测何时 不知道。
• 关闭 的 autoTuneFromTransportMode（或 enableFusedClassifier） 运行时会立即恢复您配置的阈值 - 该功能永远不会 一旦你关闭它，它的效果就会消失。

查看应用了什么

ModeChangeEvent.appliedTuning 带有放入的四个阈值 力量。自动调谐关闭时为 null，模式为 unknown 时 （恢复你自己的价值观）：

Tracelet.onModeChange((event) {
  final tuning = event.appliedTuning;
  if (tuning == null) {
    print('${event.mode} — your configured thresholds are in force');
  } else {
    print('${event.mode} → distanceFilter ${tuning.distanceFilter} m, '
        'odometerAccuracyThreshold ${tuning.odometerAccuracyThreshold} m');
  }
});

日志中出现相同的值 debug: true 和 logLevel: verbose：

auto-tune: 'walking' → distanceFilter=8.0m trackingAccuracy=15m odometerAccuracy=10m maxImpliedSpeed=4m/s

阅读目前有效的内容

onModeChange 告诉您模式提交的时刻。要问什么 过滤器在任何时候都在使用 - 包括当没有发生模式更改时 小时 — 使用 Tracelet.getCurrentLocationTuning()：

final tuning = await Tracelet.getCurrentLocationTuning();
print('in force: distanceFilter ${tuning?.distanceFilter} m, '
    'trackingAccuracyThreshold ${tuning?.trackingAccuracyThreshold} m');

这从本机位置处理器读回，不是从您的配置中读回 放。这种区别很重要：Tracelet.activeConfig 是 Dart 端的镜像 您传入的最后一个 Config ，因此它报告您要求的内容，而不是 过滤器实际上正在使用 - 它根本无法向您显示自动调谐，因为 自动调整无需任何配置调用即可更改阈值。

在跟踪会话构建处理器之前返回 null，并且始终 Web 上的 null，没有等效的过滤器状态。

3. 碰撞和跌倒检测

检测可能发生的碰撞（移动时的强烈撞击），或者可选地检测 个人跌倒。由于误报代价高昂，因此检测得到证实 （仅靠大的震动是远远不够的）并为用户提供取消倒计时。

await Tracelet.ready(Config(
  impact: ImpactConfig(
    enableCrashDetection: true,
    confirmWindowMs: 15000,   // 15s for the user to say "I'm fine"
  ),
));
 
Tracelet.onImpact((event) async {
  if (event.isPotential) {
    // Show a big "Are you OK?" countdown screen.
    // If the user taps "I'm fine":
    await Tracelet.cancelImpact(event.id);
    // If they tap "Get help now":
    // await Tracelet.confirmImpact(event.id);
  } else {
    // event.kind == 'crash' (or 'fall') — confirmed.
    // The user didn't cancel in time → start your SOS flow.
  }
});

流程如何运作

1. 快速移动时发生强烈撞击 → 您会收到 potential_crash 事件 不翻译迟到。
2. 显示倒计时用户界面。用户可以取消（cancelImpact）或立即确认 （未翻译）。
3. 如果他们在截止日期之前没有采取任何行动 → 会触发已确认的 crash 事件。

应用程序被杀死后确认仍然存在

暴力撞击通常会导致操作系统杀死应用程序——手机被扔掉， 车辆停下来，设备进入瞌睡状态。如果取消倒计时 只存在于记忆中，确认的 crash/fall 不会默默地触发。 Tracelet 使倒计时 进程死亡安全： potential_crash/potential_fall 被引发，它被 持久化到磁盘 并且 唤醒是在截止时间之后准备的。如果该应用程序仍然存在 确认正常并解除唤醒；如果它被杀了，就会醒来 从新进程重新发出已确认的事件，以便您的 SOS 流程仍然运行。

用户取消删除持久化候选者并解除唤醒，因此 取消的候选人在重新启动后永远不会被重新确认。

确认真实碰撞或跌倒的额外线索

仅仅剧烈震动是不够的——这会导致太多的误报。 因此，Tracelet 会寻找额外的真实世界线索，这些线索通常发生在真实的场景中。 碰撞或跌倒。它看到的线索越多，就越确定。这些线索只能 让 Tracelet 更加自信 - 他们永远不会取消真正的活动。

• 手机掉落 - 就在有人掉落手机或拿走手机之前 跌落时，手机会短暂失重。发现让跌倒次数更多的地方 可信的。
• 之后一切都静止了——真正摔倒之后，人和电话 通常停止移动。突然的寂静是一个强烈的信号。
• 汽车突然停下——在真正的碰撞事故中，车辆从快速变为 几乎在一两秒内就停了下来。速度急剧下降会导致事故发生。
• 压力“爆裂” — 严重碰撞（或安全气囊爆炸）会导致快速 车内气压的变化。具有压力传感器的手机可以 注意这一点；没有此功能的手机只需跳过此检查，没有任何缺点。

可选：经过许可的 AI 崩溃模型

默认情况下，碰撞检测使用规则引擎（g 阈值 + 速度 上面的证实）——无需额外设置，开箱即用。为了更高的精度 您可以启用 AI 崩溃模型：一个训练有素的模型，用于控制崩溃 学习概率而不是固定阈值。

它是选择加入并按需下载（从不嵌入），因此基本 SDK 大小 是不变的。要打开它，请获取许可证密钥并将您的配置指向它：

await Tracelet.ready(Config(
  impact: ImpactConfig(
    enableCrashDetection: true,
    crashModelUnlockUrl: 'https://unlock.ikolvi.com/unlock',
    crashModelLicenseKey: '<your license key>',
    crashModelThreshold: 0.5074,   // rf_probability_threshold from training
  ),
));

如果由于任何原因（离线、密钥无效）无法激活模型 SDK 自动回退到规则引擎 - 您的应用程序继续运行。

获得许可证

从 获取许可证 页面获取密钥：登录，输入您的 应用程序 ID，并复制准备粘贴的密钥（或完整的 ImpactConfig 片段）。

• 开发许可证 — 用于调试版本和模拟器。只需您的应用 ID，无需额外 设置。
• 产品许可证 — 适用于您发布的应用程序；还需要您的应用程序签名证书 SHA-256（Play 控制台 → 应用程序完整性 → 应用程序签名，或 ./gradlew signingReport）。

该门户还列出了您颁发的密钥，并让您立即撤销一个。

无需驾驶（模拟）和数据库访问即可尝试

Tracelet 包括用于存储远程信息处理事件的专用数据库表和一组诊断 API。这些被 Tracelet Doctor 诊断覆盖大量使用，但您也可以直接在应用程序中使用它们来构建自定义诊断屏幕或测试您的安全流程，而无需实际驾驶或撞车。

从数据库检索远程信息处理

每个驾驶和碰撞事件都会自动保存到本地 SQLite 数据库中。您可以检索这些结构化记录以显示危险驾驶行为的历史记录：

// Fetch the 50 most recent telematics events from the database
final events = await Tracelet.getTelematicsEvents(50);
 
for (final event in events) {
  print('Event Type: \${event.eventType}');   // e.g. harsh_braking, crash
  print('Severity: \${event.severity}');
  print('Location: \${event.latitude}, \${event.longitude}');
}

事件返回最新的优先，并且同步不会将它们从中删除 view — 启用 syncTelematics 会上传事件，但会留下本地历史记录 完好无损的。

将它们发送到您的后端

设置 HttpConfig.syncTelematics: true，未同步事件将按正常情况进行 位置同步 — 同一 POST 上的根级 telematics 数组，或者它们自己的数组 当您设置 HttpConfig.telematicsUrl 时发出请求。上传失败会保留事件 排队而不是丢弃它们。对于线模式，批处理边界和 单独端点的权衡，请参阅 远程信息处理同步📖。

模拟事件

您可以将模拟远程信息处理事件直接注入本机跟踪引擎中。这非常适合测试应用程序的反应（例如在崩溃时显示 SOS 屏幕）或测试 UI 组件。示例应用程序的 驾驶与安全 页面和 Tracelet Doctor 覆盖层使用此 API 让开发人员通过按钮触发事件。

// Simulate a harsh braking event (named arguments)
await Tracelet.simulateTelematicsEvent(
  eventType: 'harsh_braking',
  severity: 0.85, // 0.0 to 1.0
  latitude: 37.422,
  longitude: -122.084,
);

清除数据库

如果您需要重置诊断状态或清除本地数据库中的远程信息处理事件历史记录，您可以清除队列：

await Tracelet.destroyTelematicsEvents();

在自动化测试中，您还可以直接从 Dart 驱动引擎（它们通过 flutter_rust_bridge 公开） - 请参阅 example/integration_test/behavior_simulation_test.dart。

权限

• 驾驶活动只需要您已使用的位置权限 跟踪 — 没什么额外的。
• 运输模式和碰撞/跌落使用加速度计。在安卓上是这样的 已运行运动检测（无新许可）。在 iOS 上，添加 运动与健身使用描述提高了准确性。请参阅 iOS 和 Android 设置页面。

很高兴知道

• 设备上和确定性 — 所有检测都在共享 Rust 核心中运行。不 网络，无云模型，Android 和 iOS 上的结果相同。
• 驾驶活动也可在网络上进行（它们源自 GPS）。
• 侧通道 — 这些事件与您的正常情况一起传递 onLocation 流；他们永远不会改变你的位置或里程表，而且他们 仅当您选择使用 syncTelematics 时才加入您的同步负载。