analytics_hub_firebase 0.2.0

Firebase Analytics provider for analytics_hub. Sends LogEvent and all GA4 e-commerce events (add_to_cart, purchase, view_item, etc.) to Firebase via the official SDK.

Analytics Hub Firebase Provider

This documentation is also available in Ukrainian.

analytics_hub_firebase is a provider that connects analytics_hub to Firebase Analytics: you keep a strongly‑typed event model in core, and this package maps those events to Firebase Analytics (including e‑commerce).

Features

• FirebaseAnalyticsHubProvider – AnalytycsProvider implementation backed by FirebaseAnalytics;
• FirebaseAnalyticsHubProviderKey – provider key used by events;
• FirebaseAnalyticsEventResolver / FirebaseAnalyticsECommerceEventResolver – resolvers that map LogEvent and ECommerceEvent into Firebase SDK calls.

Essence of the solution

In one sentence: you use the same event classes as for other analytics providers, and this package sends them to Firebase (log events + e‑commerce like SelectPromotion) without your app calling the Firebase SDK directly.

For general Analytics Hub setup (creating the hub, session delegate, registering providers), see the analytics_hub package README.

Installation

Add this provider and its dependencies to your app pubspec.yaml:

dependencies:
  firebase_core: ^2.0.0
  firebase_analytics: ^10.0.0

  analytics_hub: ^0.0.1
  analytics_hub_firebase: ^0.0.1

Call Firebase.initializeApp() in main() before using the hub (see Firebase docs).

Integrating this provider

1. Initialize Firebase (e.g. in main()), then create your AnalyticsHub as described in the analytics_hub README.
2. Add the Firebase provider to the hub’s providers list:

import 'package:analytics_hub_firebase/analytics_hub_firebase.dart';

// When building your hub:
final hub = AnalyticsHub(
  sessionDelegate: yourSessionDelegate,
  providers: [
    FirebaseAnalyticsHubProvider.fromInstance(), // add this
    // ... other providers
  ],
);

3. In events that should go to Firebase, include FirebaseAnalyticsHubProviderKey in providerKeys (see Supported event types below).

Supported event types

FirebaseAnalyticsEventResolver implements:

• LogEventResolver
• ECommerceEventResolver

and internally delegates to FirebaseAnalytics and FirebaseAnalyticsECommerceEventResolver.

1. Log events (LogEvent)

Any LogEvent that includes FirebaseAnalyticsHubProviderKey in its providerKeys set will be sent to Firebase using logEvent:

class ExampleLogEvent extends LogEvent {
  const ExampleLogEvent({required this.value}) : super('example_log_event');

  final String value;

  @override
  Map<String, Object>? get properties => {'value': value};

  @override
  Set<ProviderKey<LogEventResolver>> get providerKeys => {
        const FirebaseAnalyticsHubProviderKey(),
      };
}

Mapping in Firebase:

_analytics.logEvent(
  name: event.name,
  parameters: event.properties,
);

So:

• event.name → name in logEvent;
• event.properties → parameters.

2. E‑commerce events (ECommerceEvent)

Currently supported:

• SelectPromotionECommerceEvent
  • handled via FirebaseAnalyticsECommerceEventResolver.

Mapping in Firebase:

Future<void> _resolveSelectPromotionEvent(
  SelectPromotionECommerceEvent event,
) =>
    _analytics.logSelectPromotion(
      creativeName: event.data.creativeName,
      creativeSlot: event.data.creativeSlot,
      locationId: event.data.locationId,
      promotionId: event.data.promotionId,
      promotionName: event.data.promotionName,
      parameters: event.data.parameters,
    );

Whatever you put into SelectPromotionECommerceEventData is passed directly to logSelectPromotion.

Example:

class PromoClickEvent extends SelectPromotionECommerceEvent {
  const PromoClickEvent({required this.promoId, required this.creativeName});

  final String promoId;
  final String creativeName;

  @override
  SelectPromotionECommerceEventData get data =>
      SelectPromotionECommerceEventData(
        creativeName: creativeName,
        promotionId: promoId,
      );

  @override
  Set<ProviderKey<ECommerceEventResolver>> get providerKeys => {
        const FirebaseAnalyticsHubProviderKey(),
      };
}

Session handling

FirebaseAnalyticsHubProvider implements setSession as:

@override
Future<void> setSession(Session? session) async {
  await _analytics.setUserId(id: session?.id);
}

• If Session is non‑null, userId is set in Firebase.
• If Session == null, userId is reset (id: null).

This lets you manage the session centrally via HubSessionDelegate instead of calling Firebase APIs directly throughout your app.

Roadmap: planned events

On the Firebase provider level, the next logical steps are:

• Additional e‑commerce events:
  • view_item, view_item_list, select_item,
  • add_to_cart, add_to_wishlist,
  • begin_checkout, add_payment_info, add_shipping_info,
  • purchase, refund, and other standard GA4 events.
• Matching ECommerceEvent subtypes in the core package and mappings in FirebaseAnalyticsECommerceEventResolver.

The idea is that all common GA4 e‑commerce flows can be expressed as strongly typed events in analytics_hub and automatically mapped to Firebase through this provider.

When to use analytics_hub_firebase

• You already use Firebase Analytics and want to:
  • strongly type your events in Dart;
  • share a single event model across multiple analytics SDKs;
  • manage sessions centrally.
• You plan to add other providers (e.g. Mixpanel) and would like to reuse the same event classes instead of duplicating logic.

Suggestions and improvements

Have an idea to improve this provider or the hub? Open an issue in the repository with your suggestion or feedback.