ユーティリティAPI

Tracelet は、デバッグ、バッテリー権限の管理、および基盤となるハードウェアセンサーの検査に役立つ強力なユーティリティ関数のコレクションを公開します。これらは Tracelet で直接使用できる静的メソッドです。

1. ハードウェアと OS の検査

場合によっては、アプリが実行されているデバイスの種類や、ハードウェアが特定の機能 (歩数カウンターなど) をサポートしているかどうかを正確に知る必要があります。

センサーの可用性を取得する

デバイスに物理歩数計 (歩数計)、加速度計、またはジャイロスコープが搭載されているかどうかを確認します。


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

デバイス情報の取得

詳細な OEM 文字列を取得します。これは、バックグラウンド制限が厳しい中国の OEM (Huawei、Xiaomi など) を特定するのに非常に役立ちます。


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

2. 電源とバッテリーの管理

バックグラウンドロケーションの最大の敵はOSそのものです。 Tracelet は、OS が現在アプリを調整しているかどうかを検出するメソッドと、ユーザーにそれらの制限を解除するように要求するメソッドを提供します。

省電力モード

ユーザーが「低電力モード」(iOS) または「バッテリーセーバー」(Android) を有効にしているかどうかを検出します。このモードでは、OS は Tracelet をアクティブに強制終了します。


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

バッテリー最適化の免除 (Android)

Android では、信頼性の高いバックグラウンド追跡が必要な場合は、アプリを Doze モードから除外するようにユーザーに依頼する必要があります。 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 は、追跡に影響を与える可能性があるすべての単一 OS 設定の大規模な JSON ペイロードをコンパイルします。このペイロードをサーバーにアップロードしてデバッグできます。


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

4. ロギングと診断

Tracelet は、包括的な診断ログを内部 SQLite データベース (場所データベースとは別) に直接書き込みます。これは、運用環境で問題をデバッグする場合に非常に役立ちます。

ログを取得する

ログを取得するには 2 つの方法があり、混乱を避けるためにそれらの違いを理解することが重要です。

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]');