Firebase 实时数据库适配器

tracelet_firebase 包提供了一个无缝的嵌入式适配器，可将您的后台位置直接同步到 Firebase 实时数据库 (RTDB) — 100% 无服务器，无需部署云功能。

安装

将适配器添加到您的 pubspec.yaml：


flutter pub add tracelet_firebase

该适配器使用 firebase_core 和 firebase_auth。在使用之前，您必须为 Firebase 配置 Flutter 应用（使用 flutterfire configure）并在 Firebase 控制台中创建实时数据库。

它是如何运作的

与 Firestore SDK 集成不同，此适配器不打开单独的写入路径。它插入 Tracelet 的电池高效 本机 HTTP 同步引擎：buildHttpConfig 生成指向 RTDB 的 REST 端点 (<database>/<path>.json) 的 HttpConfig，并使用 Firebase 身份验证 ID 令牌作为 ?auth= 查询参数进行身份验证。

由于同步在本机引擎中运行，因此即使应用程序强制退出**，也会以指数退避和离线排队方式上传批次。当令牌过期且 RTDB 返回 401 时，configureTokenRefresh 会透明地刷新 Firebase ID 令牌（在前台和无头后台隔离中）并重试。

设置和配置

初始化 Firebase

在调用 Tracelet 之前在 main.dart 中初始化 Firebase：


import 'package:firebase_core/firebase_core.dart';
import 'firebase_options.dart';
 
void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await Firebase.initializeApp(
    options: DefaultFirebaseOptions.currentPlatform,
  );
  runApp(const MyApp());
}

配置令牌刷新并构建 HTTP 配置

调用 configureTokenRefresh() 一次，然后为 RTDB 路径构建 HttpConfig 并将其传递给 Tracelet.ready：


import 'package:firebase_core/firebase_core.dart';
import 'package:firebase_auth/firebase_auth.dart';
import 'package:tracelet_firebase/tracelet_firebase.dart';
import 'package:tracelet/tracelet.dart';
 
// 1. Your Realtime Database URL (from FirebaseOptions).
final databaseUrl = Firebase.app().options.databaseURL;
 
// 2. Keep the Firebase ID token fresh in the background (resolves 401s).
await TraceletFirebase.configureTokenRefresh();
 
// 3. Get the signed-in user's id for a per-user write path.
final uid = FirebaseAuth.instance.currentUser?.uid ?? 'anonymous_device';
 
// 4. Build the native HTTP config for RTDB.
final httpConfig = await TraceletFirebase.buildHttpConfig(
  databaseUrl: databaseUrl!,        // e.g. https://my-project-default-rtdb.firebaseio.com
  path: 'locations/$uid',           // secure this path in your RTDB rules
  // autoSync: true, batchSync: true, maxBatchSize: 250 are the defaults
);
 
// 5. Start Tracelet with the adapter's HTTP config.
await Tracelet.ready(Config(
  geo: const GeoConfig(distanceFilter: 50),
  http: httpConfig,
));
await Tracelet.start();

必须对用户进行身份验证，写入才能根据安全规则成功。如果您还没有真正的登录流程，FirebaseAuth.instance.signInAnonymously() 足以在测试时获得 uid。

附加自定义元数据

要使用业务数据标记每个位置（例如 order_id 或 trip_id），请使用 setRouteContext() — 它通过 SQLite 队列与每个位置一起传输，并包含在 RTDB 有效负载中：


await Tracelet.setRouteContext(RouteContext(
  taskId: 'order_123',
  custom: {'trip_id': 'trip_456'},
));

安全规则

保护您的实时数据库，以便经过身份验证的用户只能写入自己的位置路径：


{
  "rules": {
    "locations": {
      "$uid": {
        ".read": "auth != null && auth.uid === $uid",
        ".write": "auth != null && auth.uid === $uid"
      }
    }
  }
}