event_tracker_handler 0.3.0
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.