beacon_firebase

Firebase Analytics integration package for the Beacon analytics library.

Installation

Add this to your package's pubspec.yaml file:

dependencies:
  beacon_firebase:
    path: path/to/beacon/integrations/beacon_firebase

Setup

Before using this package, you need to set up Firebase in your Flutter app. Follow the official Firebase setup guide.

Usage

1. Initialize Firebase

Ensure Firebase is initialized in your app:

import 'package:firebase_core/firebase_core.dart';

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

2. Create and Attach the Receiver

Create a FirebaseReceiver and attach it to Beacon:

import 'package:beacon_core/beacon.dart';
import 'package:beacon_firebase/beacon_firebase.dart';
import 'package:firebase_analytics/firebase_analytics.dart';

final analytics = FirebaseAnalytics.instance;
final receiver = FirebaseReceiver(analytics: analytics);
Beacon().attach(receiver);

3. Track Events

Now all events sent through Beacon will be forwarded to Firebase Analytics:

Beacon().emit('button_clicked', params: {
  'button_name': 'subscribe',
  'screen': 'home',
});

Event Name Sanitization

Firebase Analytics has specific requirements for event names. This receiver automatically sanitizes event names to comply with Firebase requirements:

  • Replaces spaces and special characters with underscores
  • Ensures names start with a letter
  • Limits names to 40 characters

For example:

  • "Button Clicked!" → "Button_Clicked_"
  • "123-event" → "event_123_event"

Default Parameters

You can specify default parameters that will be included with every event:

final receiver = FirebaseReceiver(
  analytics: analytics,
  defaultParams: {
    'app_version': '1.0.0',
    'platform': 'mobile',
  },
);

These default parameters will be merged with event-specific parameters. Event parameters take precedence if there are conflicts.

Configuration Options

Constructor Parameters

  • analytics (required): The FirebaseAnalytics instance
  • defaultParams (optional): Default parameters to include with every event

Error Handling

The receiver handles errors gracefully and logs them without interrupting the analytics flow. If Firebase tracking fails, the error is caught and logged, but other receivers will continue to work normally.

License

MIT License - see the LICENSE file for details.

Libraries

beacon_firebase