Skip to Content
快速入门（2 分钟）

⚡ 10 分钟快速入门

使用我们高度优化的预构建配置文件立即在您的应用程序中运行后台跟踪。

✨

希望 AI 为您完成设置？ 复制我们的设置提示并将其粘贴到 Claude、ChatGPT、Cursor 或在您的项目中工作的任何 AI 编码代理中。它将从此网站获取最新文档，询问您一些有关您的应用程序的问题（用例、电池目标、后端同步、合规性需求……），然后自动为您安装和配置 Tracelet。

1.安装Tracelet

flutter pub add tracelet

2.添加平台权限

iOS 设置 (ios/Runner/Info.plist) 您必须明确定义使用说明和后台模式，以防止 Apple 拒绝您的应用程序或杀死后台任务：

<key>NSLocationWhenInUseUsageDescription</key>
<string>We need your location to track your route.</string>
<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>We need background location to record your route even when the app is closed.</string>
<key>NSMotionUsageDescription</key>
<string>Motion detection allows battery-efficient tracking by pausing GPS when stationary.</string>
<key>UIBackgroundModes</key>
<array>
  <string>location</string>
  <string>fetch</string>
</array>

Android 设置 (android/app/src/main/AndroidManifest.xml) Tracelet 会自动将所有必要的权限注入到您编译的应用程序中（例如 ACCESS_FINE_LOCATION、ACCESS_BACKGROUND_LOCATION、FOREGROUND_SERVICE、ACTIVITY_RECOGNITION 等）。 您无需手动将它们添加到清单中。

如果您想删除任何可选权限（例如，如果您不需要运动检测），您可以使用 Android 清单合并来强制删除它们。有关哪些权限是强制的、哪些是可选的以及如何删除它们的完整指南，请参阅 Android 平台设置。

3. 初始化和跟踪

使用预先配置的平衡配置文件启动 Tracelet。这是完美的默认设置，可以在用户移动时主动跟踪，并在静止时完全关闭 GPS 以节省电池。此代码还注册了 Headless Task，因此即使用户将应用程序滑开，跟踪也可以完美地继续！

import 'dart:io';
import 'package:flutter/material.dart';
import 'package:tracelet/tracelet.dart';
 
// 1. Define a top-level Headless Task to handle events when the app is killed
@pragma('vm:entry-point')
void headlessTask(HeadlessEvent event) {
  print('[Headless] Event received while app is killed: ${event.name}');
}
 
void main() async {
  WidgetsFlutterBinding.ensureInitialized();
 
  // 2. Register the headless task BEFORE runApp!
  Tracelet.registerHeadlessTask(headlessTask);
 
  // 3. Request permissions required for background tracking natively via Tracelet
  if (Platform.isAndroid) {
    await Tracelet.requestNotificationAuthorization(); // Required for Android 13+ Foreground Service
    await Tracelet.requestMotionAuthorization(); // Required for Motion Detection heuristics
  }
  
  final authStatus = await Tracelet.requestLocationAuthorization();
  if (authStatus == AuthorizationStatus.deniedForever) {
    print("Permissions denied!");
    return;
  }
 
  // 4. (Optional) Mitigate Aggressive OEM Battery Managers (Xiaomi, Huawei, etc.)
  if (Platform.isAndroid) {
    final health = await Tracelet.getSettingsHealth();
    if (health['isAggressiveOem'] == true) {
      await Tracelet.showPowerManager(); // Prompts user to whitelist the app
    }
  }
 
  // 5. Listen to real-time location events
  Tracelet.onLocation((location) {
    print('[Tracelet] Location: ${location.coords.latitude}, ${location.coords.longitude}');
  });
 
  // 6. Configure Tracelet with the Balanced Profile and Notification settings
  await Tracelet.ready(Config.balanced(
    url: 'https://api.your-server.com/locations',
    headers: {'Authorization': 'Bearer YOUR_TOKEN'},
    startOnBoot: true,
    stopOnTerminate: false, // Ensures tracking continues when app is swiped away
    android: AndroidConfig(
      foregroundService: ForegroundServiceConfig(
        contentTitle: "Background Tracking",
        contentText: "We are tracking your location securely.",
        notificationIcon: "mipmap/ic_launcher",
      ),
    ),
  ));
 
  // 7. Start tracking!
  await Tracelet.start();
 
  runApp(MyApp());
}

就是这样！ Tracelet 现在将完全自行自动处理后台执行、运动检测启发式、离线 SQLite 缓存和网络同步。

家颤动SDK