tracelet_firebase 3.2.18

Firebase adapter for Tracelet. Automatically configures native HTTP sync to push locations directly to the Firebase RTDB and manages background auth token refresh.

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.