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.

Links #

• Firebase Analytics Flutter Documentation
• Firebase Analytics Package on pub.flutter-io.cn
• Beacon Core Library

License #

MIT License - see the LICENSE file for details.