Skip to main content

event_tracker_handler 0.3.0 copy "event_tracker_handler: ^0.3.0" to clipboard
event_tracker_handler: ^0.3.0 copied to clipboard

Multi-provider event tracking with Firebase Analytics, Mixpanel, and webhooks.

event_tracker_handler #

Multi-provider event tracking with Firebase Analytics, Mixpanel, and custom webhooks.

Features #

  • Track predefined events with a single handler.
  • Firebase Analytics, Mixpanel, and custom webhook backends.
  • Typed user and event data (items, value, currency, custom fields).
  • Timed event manager with lifecycle-aware flushing.
  • Delivery outcomes per tracker plus identity merge support.
  • Explicitly bootstrapped Meta App Events and consent-gated Meta Pixel on web.

Getting started #

Add event_tracker_handler to your pubspec.yaml and complete the setup for any providers you plan to use (Firebase/Mixpanel).

If you plan to use Mixpanel on Flutter web, load the Mixpanel script from the plugin assets in web/index.html before the Flutter app initializes:

<!-- web/index.html -->
<script src="/assets/packages/mixpanel_flutter/assets/mixpanel.js"></script>

Usage #

Create settings for each tracker and build a handler instance:

import 'package:decimal/decimal.dart';
import 'package:event_tracker_handler/event_tracker_handler.dart';

final handler = EventTrackerHandler.instance([
  EventTrackerSettingsFirebase(
    eventsToTrack: [EventTrackerEvents.openApp, EventTrackerEvents.purchase],
  ),
  EventTrackerSettingsMixpanel(
    token: 'YOUR_MIXPANEL_TOKEN',
    eventsToTrack: [EventTrackerEvents.openApp, EventTrackerEvents.purchase],
  ),
  EventTrackerSettingsCustomWebhook(
    url: 'https://example.com/events',
    eventsToTrack: [EventTrackerEvents.openApp],
  ),
]);

Future<void> trackPurchase() async {
  await handler.init();

  handler.logEvent(
    type: EventTrackerEvents.purchase,
    userData: EventTrackerUserData(
      uuid: 'user-123',
      email: 'user@example.com',
      isAnonymous: false,
    ),
    data: EventTrackerData(
      value: Decimal.parse('29.90'),
      currency: 'USD',
      customData: {'plan': 'pro'},
    ),
  );
}

Log events return delivery outcomes per tracker:

final outcomes = await handler.logEvent(
  type: EventTrackerEvents.openApp,
  userData: EventTrackerUserData(
    uuid: 'user-123',
    email: 'user@example.com',
    isAnonymous: false,
  ),
);
final failed = outcomes.where((outcome) => outcome.isFailure);

You can also build tracker settings from a map:

final settings = EventTrackerSettingsModel.fromMap({
  'type': 'EventTrackerType.mixpanel',
  'token': 'YOUR_MIXPANEL_TOKEN',
  'events': ['EventTrackerEvents.openApp', 'EventTrackerEvents.purchase'],
  // Or set track_all: true to track every EventTrackerEvents value.
});

Timed events #

Use the timed event manager to start, finish, or flush active timers:

final timedManager = EventTrackerTimedEventManager(
  handler: handler,
  userDataProvider: () async => EventTrackerUserData(
    uuid: 'user-123',
    email: 'user@example.com',
    isAnonymous: false,
  ),
);

final handle = timedManager.start(type: EventTrackerEvents.viewContent);
await timedManager.finish(handle);

Attach a lifecycle observer to flush when the app goes inactive:

final observer = EventTrackerLifecycleObserver(
  timedEventManager: timedManager,
);
WidgetsBinding.instance.addObserver(observer);

Identity merge #

Merge identities when a user logs in or links accounts:

await handler.mergeIdentity(
  previousUserId: 'anon-456',
  userData: EventTrackerUserData(
    uuid: 'user-123',
    email: 'user@example.com',
    isAnonymous: false,
  ),
);

Meta App Events #

The Meta adapter registers an inert method channel. Resolve the owning tenant's configuration first, and call bootstrap only after the host's tenant and platform binding checks. On iOS, Meta App Events require ATT authorization; advertiser ID collection additionally requires the explicit collection setting. Automatic metadata collection stays disabled until title, URL and event envelope auditing proves it safe for the tenant's routes. The native process binds to one tenant and App ID. A tenant or App ID change requires a process restart; disabling Meta only blocks further events. The client token is an SDK configuration value, not an App Secret or Ads access token. On Android, requestTrackingAuthorization checks the app's AD_ID permission and whether Google Play services supplies a usable advertising ID; it does not show a permission prompt. Missing, limited, or zeroed IDs keep advertiser ID collection off while ordinary Meta events remain available. The Android adapter uses Meta SDK 19.0.1. The iOS adapter uses CocoaPods FBSDKCoreKit 19.0.0 and requires a deployment target of 15.0 or later. The iOS host must set FacebookAutoInitEnabled, FacebookAutoLogAppEventsEnabled, FacebookAdvertiserIDCollectionEnabled, FacebookSKAdNetworkReportEnabled, FBSDKAutoLogMetaDataEnabled, and FBSDKAutoLogProductImprovementEnabled to false in Info.plist. These native defaults keep collection off before tenant resolution and SDK initialization; the plugin configures the SDK only after bootstrap. Do not put the tenant's Meta App ID or client token in Info.plist.

final meta = MetaAppEvents.instance;
await meta.bootstrap(const MetaAppEventsConfig(
  tenantId: 'tenant-id',
  appId: '1234567890',
  clientToken: 'meta-client-token',
  enabled: true,
  viewContentEnabled: true,
  completeRegistrationEnabled: true,
));

await meta.viewContent(contentId: 'public-profile-id', contentType: 'profile');
await meta.completeRegistration(challengeId: 'opaque-otp-challenge-id');

Only ViewContent for profile or event content and app-only CompleteRegistration are exposed. The OTP challenge ID is used only for in-process deduplication and is never sent to Meta. On web, Pixel is initialized only when a pixel ID and explicit tenant consent are supplied in the bootstrap config; only ViewContent is sent. Revocation blocks later calls. A Pixel or tenant switch requires a page reload because a loaded third-party script cannot be removed from the current page context.

Additional information #

Custom webhook events include an envelope with type, timestamp, context, and payload. The context includes app, device, user, and web metadata when available, while the payload carries event properties and timing details.

0
likes
0
points
277
downloads

Publisher

unverified uploader

Weekly Downloads

Multi-provider event tracking with Firebase Analytics, Mixpanel, and webhooks.

Repository (GitHub)
View/report issues

License

unknown (license)

Dependencies

decimal, device_info_plus, firebase_analytics, flutter, flutter_web_plugins, http, mixpanel_flutter, package_info_plus, web

More

Packages that depend on event_tracker_handler

Packages that implement event_tracker_handler