📡 Beacon #

A lightweight and extensible Flutter library for managing and logging analytics events across multiple platforms with ease.

🚀 Features #

• 📦 Plug-and-Play Analytics: Easily integrate multiple analytics platforms like Mixpanel, Firebase, or custom solutions.
• 🌐 Extensible: Add your own custom receivers for any analytics provider.
• ⚡ Asynchronous: Non-blocking event logging ensures smooth app performance.
• 🛠 Customizable: Filter events, add default parameters, and transform data effortlessly.
• ✅ Lifecycle Management: Initialize and shutdown receivers cleanly.

Packages #

Core Library #

• beacon: Core library for event management.

Integrations #

• beacon_mixpanel: Mixpanel integration.
• beacon_firebase: Firebase integration.
• beacon_amplitude: Amplitude integration.

Example App #

• example: Demo app showcasing the usage of Beacon.

📖 Getting Started #

Installation #

Add beacon_core to your pubspec.yaml file:

dependencies:
  beacon_core: ^1.0.0

Then, fetch the package:

flutter pub get

🛠 Usage #

Step 1: Import Beacon #

import 'package:beacon_core/beacon.dart';

Step 2: Register Analytics Receivers #

Add your desired analytics platforms during app initialization:

import 'package:mixpanel_flutter/mixpanel_flutter.dart';

void main() async {
  // Initialize Mixpanel
  final mixpanel = await Mixpanel.init('YOUR_MIXPANEL_PROJECT_TOKEN');

  // Register receivers
  Beacon.attach(MixpanelReceiver(
    mixpanel: mixpanel,
    defaultParams: {
      'app_version': '1.0.0',
      'platform': 'Flutter',
    },
  ));

  // Optionally, add a debug receiver for testing
  Beacon.attach(DebugReceiver());

  runApp(MyApp());
}

Step 3: Emit Events #

Log analytics events anywhere in your app:

Beacon.emit('button_click', params: {'button_name': 'example_button'});

Beacon.emit('purchase', params: {
  'item_id': '12345',
  'price': 19.99,
  'currency': 'USD',
});

Step 4: Clean Up (Optional) #

Shut down all receivers when the app exits:

@override
void dispose() {
  Beacon.shutdown();
  super.dispose();
}

📦 Receivers #

Beacon uses receivers to handle events for different analytics platforms.

Built-in Receivers #

MixpanelReceiver

Logs events to Mixpanel:

Beacon.attach(MixpanelReceiver(
  mixpanel: mixpanel,
  defaultParams: {
    'app_version': '1.0.0',
    'platform': 'Flutter',
  },
));

DebugReceiver

Logs events to the console for debugging:

Beacon.attach(DebugReceiver());

Creating Custom Receivers #

Implement the BeaconReceiver interface to create your own receiver:

class MyCustomReceiver implements BeaconReceiver {
  @override
  void initialize() {
    print("Custom receiver initialized");
  }

  @override
  void shutdown() {
    print("Custom receiver shutting down");
  }

  @override
  bool shouldProcess(String eventName) {
    return !eventName.startsWith('debug_');
  }

  @override
  void onEvent(String eventName, Map<String, dynamic> params) {
    print("Custom Event: $eventName, Params: $params");
  }
}

Register it like any other receiver:

Beacon.attach(MyCustomReceiver());

🧪 Testing #

Run the following command to test the library:

flutter test

Example unit test for Beacon:

void main() {
  test('Beacon logs events to all registered receivers', () {
    final debugReceiver = DebugReceiver();
    Beacon.attach(debugReceiver);

    expect(() => Beacon.emit('test_event'), prints(contains('test_event')));
  });
}

📖 API Reference #

Beacon Methods #

BeaconReceiver Interface #

📜 Changelog #

See CHANGELOG.md for details on updates and new features.

🛡 License #

This project is licensed under the MIT License. See the LICENSE file for details.

🙌 Contributing #

We welcome contributions! Here's how you can help:

1. Fork the repository.
2. Create a feature branch: git checkout -b feature-name.
3. Commit your changes: git commit -m 'Add new feature'.
4. Push to the branch: git push origin feature-name.
5. Open a pull request.

📫 Contact #

For questions or suggestions, feel free to reach out:

• GitHub: Beacon on GitHub
• Twitter: @cesarmcferreira

🔗 Resources #

• Mixpanel Documentation
• Firebase Analytics
• Flutter Packages