Skip to Content
其他工具和适配器实用程序API

实用程序API

Tracelet 公开了一系列强大的实用函数，可帮助您调试、管理电池权限和检查底层硬件传感器。这些是直接在 Tracelet 上可用的静态方法。

1. 硬件和操作系统检查

有时您需要确切地知道应用程序正在运行的设备类型，或者硬件是否支持某些功能（例如计步器）。

获取传感器可用性

检查设备是否具有物理计步器（计步器）、加速计或陀螺仪。

final sensors = await tl.Tracelet.getSensors();
 
print('Has Accelerometer: \${sensors.accelerometer}');
print('Has Gyroscope: \${sensors.gyroscope}');
print('Has Step Counter: \${sensors.stepCounter}');

获取设备信息

获取详细的 OEM 字符串。这对于识别具有严格背景限制的中国原始设备制造商（如华为、小米）非常有用。

final device = await tl.Tracelet.getDeviceInfo();
 
print('Manufacturer: \${device.manufacturer}');
print('Model: \${device.model}');
print('OS Version: \${device.version}');

2. 电源和电池管理

后台定位的最大敌人是操作系统本身。 Tracelet 提供了检测操作系统当前是否正在限制您的应用程序的方法，以及要求用户解除这些限制的方法。

省电模式

检测用户是否启用了“低功耗模式”(iOS) 或“省电模式”(Android)。在这种模式下，操作系统会主动杀死Tracelet。

final isPowerSaving = await tl.Tracelet.isPowerSaveMode;
if (isPowerSaving) {
  print('Warning: Battery Saver is ON. Tracking will be degraded.');
}

电池优化豁免 (Android)

在 Android 上，如果您想要可靠的后台跟踪，则必须要求用户使您的应用程序免于打瞌睡模式。 Tracelet 为此提供了统一的 API。

final isExempt = await tl.Tracelet.isIgnoringBatteryOptimizations();
 
if (!isExempt) {
  // Opens the exact Android settings page to whitelist your app
  await tl.Tracelet.openBatterySettings();
}

3.健康仪表板API

如果用户抱怨跟踪不起作用，可能有十几种不同的原因：他们拒绝使用 GPS、关闭 Wi-Fi 扫描、处于省电模式等。

Tracelet 编译可能影响跟踪的每个操作系统设置的大量 JSON 有效负载。您可以将此负载上传到您的服务器进行调试。

final health = await tl.Tracelet.getSettingsHealth();
 
// Upload to your server or print to console
print('Health Check: \$health');

4. 日志记录和诊断

Tracelet 将全面的诊断日志直接写入内部 SQLite 数据库（与位置数据库分开）。这对于调试生产中的问题非常有价值。

获取日志

检索日志的方法有两种，了解它们之间的区别以避免混淆非常重要：

1. getLogs(int limit)（结构化） 从数据库返回结构化的 List<LogEntry>。当您需要在结构化 UI（如 Tracelet Doctor）中显示日志或以编程方式处理日志时，这是最好的选择。

// Get the 50 most recent structured log entries
final entries = await tl.Tracelet.getLogs(50);
for (final entry in entries) {
  print('[\${entry?.level}] \${entry?.message}');
}

2. getLog([SQLQuery query])（原始字符串） 检索连接为单个大字符串的日志。当您只想快速将所有内容打印到控制台或将其写入文本文件时，这是理想的选择。

final logsString = await tl.Tracelet.getLog();
print(logsString);
 
// Or query specific logs as a string
final errorLogsString = await tl.Tracelet.getLog(
  tl.SQLQuery(where: "level = 'ERROR'")
);

清除日志

您可以清除所有存储的系统日志以重置数据库队列：

await tl.Tracelet.clearLogs();

编写自定义日志

您可以将自己的应用程序日志注入 Tracelet 日志数据库，以便所有内容都按时间顺序与位置事件完美交错。

await tl.Tracelet.log('INFO', 'User tapped the checkout button');
await tl.Tracelet.log('ERROR', 'Failed to fetch user profile');

通过电子邮件发送日志

轻松将整个日志数据库转储到电子邮件附件中，以便用户可以将其发送给您的支持团队。

// Opens the native email client with the logs attached
await tl.Tracelet.emailLog('[email protected]');
火力基地网络支持