Facade and Provider
Analytics is the one static entry point for events, page views, identity and defaults, and AnalyticsServiceProvider binds it and wires the router and the auth state.
On this page
Quick Reference#
import 'package:magic_analytics/magic_analytics.dart';
Future<void> afterSignIn(String userUuid, String teamPlan) async {
await Analytics.identify(userUuid);
await Analytics.setUserProperties({'locale': 'en'});
await Analytics.setDefaultParams({'team_plan': teamPlan});
await Analytics.track('monitor_created', {'monitor_type': 'http'});
}
| Call | Does |
|---|---|
Analytics.track(name, [parameters]) |
Sends the event name with string or number parameters |
Analytics.screen(name, {location, referrer}) |
Sends a page view; the observer calls it for you |
Analytics.identify(userId) |
Sets the GA4 user id |
Analytics.setUserProperties(properties) |
Sets user-level properties; a null value clears one |
Analytics.setDefaultParams(parameters) |
Replaces the parameters sent with every event; null clears them |
Analytics.setOptOut(optedOut) |
Stops or resumes collection on this device |
Analytics.isOptedOut |
Whether this device has opted out |
Analytics.reset() |
Forgets the signed-in user |
Analytics.clientId() |
The GA4 client id, or null |
Every call returns a future that never fails: await it in a test, ignore it in app code. A GA4 limit violation is the one exception, in debug only (see Order and Failure).
Events and Parameters#
A parameter value is a string or a number. A string passes through the URL scrubber first, so an email address or a token inside it leaves the device masked. The limits below apply to what is actually sent.
setDefaultParams replaces the whole set: a key left out of the new map is removed. This is where team facts go (a plan, a team size). Each event carries the defaults, and they count toward the 25 parameters an event may carry.
Identity#
identify takes the user's opaque id, a UUID. It refuses an empty id, one longer than 256 characters and anything the scrubber would mask, so an email address is never an id.
setUserProperties is for facts about the USER, not the team: a name is at most 24 characters and a value at most 36. Team facts belong in setDefaultParams, so a team switch replaces them instead of leaving the old team on the user.
reset() nulls the user id, every user property set since the last reset and every default parameter, then lets the driver clear what is left. It never rotates the client id: the device stays the same across a sign-out. It runs on an opted-out device too.
GA4 Limits#
| Limit | Value |
|---|---|
| Event name, parameter name, default parameter name | 40 characters, letters, digits and underscores, starting with a letter |
| Reserved prefixes | ga_, google_, firebase_ |
| Parameters per event, defaults included | 25 |
| String parameter value | 100 characters, measured after scrubbing |
| User property name | 24 characters |
| User property value | 36 characters |
| User id | 256 characters |
A call that breaks a limit fails an assert in debug, so a test or a debug run stops at the call site. In release the call is dropped and the reason is logged through Magic's Log (or debugPrint when none is bound). Nothing invalid reaches a driver.
Order and Failure#
Driver calls run one at a time, in call order, on a queue inside AnalyticsManager. An auth listener cannot await reset(), and without the queue the next user's setDefaultParams could reach the driver before the previous user's were cleared.
A driver error is caught at the manager, logged and never rethrown, so an analytics call never throws into UI flow. A limit violation is the one deliberate exception, in debug only.
What the Provider Wires#
| Step | Does |
|---|---|
register() |
Binds the analytics singleton, an AnalyticsManager over the driver createAnalyticsDriver picks for the platform, or NullDriver unless analytics.enabled is true |
boot() |
Adds AnalyticsNavigatorObserver to MagicRouter, once |
boot(), with auth bound |
Calls Analytics.reset() when the signed-in user signs out or changes |
The reset follows Auth.stateNotifier and compares the user id, so a team switch (same user) keeps the identity: the app sets the new team's default parameters itself. The provider never calls identify.
Page Views#
AnalyticsNavigatorObserver reports a page view each time a named page comes to the top. Magic names a page by its route name, or by its path pattern when the route has no name, and that name is the title; the location is always the pattern (/monitors/:id, never /monitors/42): no id, token or email in either, and every monitor's page counts as one page. A page without a name (a dialog, a bottom sheet) is not a page view, and closing one does not report the page beneath again. The previous page's pattern is the next page's referrer.
Gotchas#
| Mistake | Fix |
|---|---|
Putting a team plan in setUserProperties |
Use setDefaultParams; user properties are user-level |
Calling setDefaultParams with only the new key |
It replaces the set; pass every default you want kept |
Passing an email to identify |
Pass the user's UUID; the call is refused otherwise |
A parameter that is a bool or a list |
Send a string or a number; anything else breaks the limit |
Adding the observer in main() |
Register the provider; MagicRouter refuses an observer after its config is built |
Expecting reset() to change the client id |
It does not; the device is the same |
Related Documentation#
- Drivers: what each driver does with these calls.
- Consent and Opt-Out: what
setOptOutstops. - URL Scrubbing: what is masked before anything is sent.
- Testing: asserting events without a live property.