Tracelet Firebase Adapter

The official Firebase Realtime Database (RTDB) adapter for Tracelet.

This adapter seamlessly connects Tracelet's battery-efficient native HTTP sync engine directly to the Firebase Realtime Database (RTDB) REST API. By pushing locations natively to the RTDB, you achieve 100% serverless, zero-cost background location tracking without the need to deploy Cloud Functions.

🚀 Features

• Zero Cloud Functions — Syncs natively from the device to RTDB via Firebase's REST API.
• Auto Token Refresh — Automatically detects 401 errors in the background and refreshes the Firebase Auth ID token natively, even when the Flutter app is terminated.
• Batch Syncing — fully compatible with Tracelet's robust HTTP batch engine, including exponential backoff and offline queues.
• Enterprise Tested — 100% test coverage using Mocktail and Dependency Injection.

📦 Getting Started

1. Set up Firebase in your Flutter app using firebase_core and firebase_auth.
2. Initialize Tracelet using TraceletFirebase.

import 'package:tracelet_firebase/tracelet_firebase.dart';
import 'package:firebase_auth/firebase_auth.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await Firebase.initializeApp();

  // 1. Configure the auto-token refresher
  await TraceletFirebase.configureTokenRefresh();

  // 2. Build the HTTP Config pointing to your RTDB
  final user = FirebaseAuth.instance.currentUser;
  if (user != null) {
    final httpConfig = await TraceletFirebase.buildHttpConfig(
      databaseUrl: 'https://your-project-default-rtdb.firebaseio.com',
      path: 'locations/${user.uid}', // Secure this path in your RTDB rules
    );

    // 3. Start Tracelet
    await Tracelet.ready(Config(
      http: httpConfig,
    ));
  }
}

🛠 Customizing the Payload

If you want to inject custom data (like an order_id or trip_id) into every location point dynamically, use the Tracelet.setRouteContext() API in Dart:

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

The route context data travels with the location row through the SQLite queue and is included natively in the Firebase RTDB payload.

🔒 Security Rules

Secure your RTDB to only allow authenticated users to write to their own location path:

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

🤝 Contributing

See the root CONTRIBUTING.md for guidelines.

📄 License

Apache 2.0 — see LICENSE for details.