Skip to content

Drivers

View raw .md

Three drivers sit behind the facade: Google Tag Manager on web, Firebase on iOS and Android, and a null driver when nothing is configured.

On this page

Quick Reference#

Platform Driver Runs when
Web GtmWebDriver analytics.enabled is true and gtm.container_id and gtm.gateway_path are both set
iOS, Android FirebaseDriver analytics.enabled is true and firebase_options is a FirebaseOptions Function()
Anything else, or not configured NullDriver Always

A driver only transports. The facade has already validated, scrubbed and gated each call, so a driver re-checks none of it.

Picking the Driver#

AnalyticsServiceProvider reads the analytics config map and calls createAnalyticsDriver, which is a conditional export: the dart.library.js_interop arm is the web build, dart.library.io is iOS and Android, and a stub that answers NullDriver is the default. The web arm keys on js_interop and not on the legacy dart:html, which a WebAssembly build lacks. The result is that the Firebase code is never reachable from a web build, so Firebase is never initialised there.

Without analytics.enabled: true the provider skips all of this and binds NullDriver.

Web Driver#

GtmWebDriver loads a Google Tag Manager container from your first-party gateway path and feeds GA4 through it.

Lazy load. Nothing touches the page until the first call that sends something, so a device that opted out never loads the container and never gets a dataLayer. Then, in order: an inline script defines window.dataLayer and the gtag shim, defaults consent (analytics granted, every ad signal denied), pre-seeds the page fields (below) and pushes gtm.start; only after that is the loader <script async src="/<gateway>/?id=<id>"> appended. The shim is real JavaScript on purpose: GTM ignores a consent command pushed as a plain array or object.

What each call pushes to the data layer your container's variables read:

Call Data layer push
screen {event: 'page_view', page_title, page_location, page_referrer}, the locations built from the origin and the route pattern; the first page's referrer is the origin root, never null
track {event: <name>, ...parameters}, then {<each parameter key>: <the value the driver holds for it, or null>}, so the parameters stay with this event (see below)
identify {user_id: <id>}; null on reset
setUserProperties {user_properties: {<name>: <value>}}, nested
setDefaultParams The keys flat; the data layer keeps them for every later push

The data layer is a merged model, not a queue: a key keeps its value for every later push until something pushes it again. Without the second push after track, a monitor_type sent with one event would reach every later event whose tag reads that variable, and an event parameter named like a default parameter (plan in a plan_changed event) would replace the default for good. The driver puts each key back to the value last pushed for it outside an event (by identify, setUserProperties, screen or setDefaultParams, whichever came last), or to null when there is none.

page_location is the page's origin plus the route PATTERN, so the real URL, which may carry a token, never leaves. The container's GA4 configuration must set send_page_view to false, because this driver pushes the page views itself.

Origin-only pre-seed. Before gtm.start, the bootstrap pushes {page_location: <origin>/, page_referrer: <origin>/}. Until the first page view is pushed, a data layer variable bound to page_location would be undefined and the Google tag would fall back to the real document.location, which can carry a reset token or an invitation path. The seed carries the origin alone, so no path or query is ever read from the address bar.

A set of removals (reset, a null user id, a null property) only pushes when the container is already loaded, so it never loads one. clientId() reads the _ga cookie and is null until the container has set it.

Container Setup#

The Google tag alone sends none of the driver's events: it only configures the property. The container needs these pieces for an event to reach GA4.

Piece Setting
Data Layer Variables, version 2 One each for page_location, page_referrer, page_title, user_id, every key you pass to Analytics.setDefaultParams (for example team_plan) and user_properties.<name> for each key you pass to Analytics.setUserProperties
Event Settings Variable A Google tag Event Settings Variable that maps page_location, page_referrer, page_title and user_id to those variables and lists the default params and user properties; both tags below use it
Google tag The measurement ID, send_page_view set to false, the Event Settings Variable
GA4 Event tag Event name {{Event}}, the Event Settings Variable, and one Event Parameter per event key you want reported
Trigger A Custom Event trigger with event name .* and regex matching on, excluding events whose name starts with gtm.
Consent Both tags, under Advanced Settings, Consent Settings: "Require additional consent for tag to fire" with analytics_storage

{{Event}} is the built-in variable for the event key, so one tag reports every Analytics.track name and the page_view the driver pushes. Sharing the Event Settings Variable between the Google tag and the event tag sets the page fields on every event, not only on the first.

Requiring analytics_storage on both tags matters for opt-out: without it, a Google tag whose consent is denied still sends cookieless pings. With it, an opted-out device sends nothing after the driver's consent update.

Firebase Driver#

FirebaseDriver sends through firebase_analytics. The factory is synchronous, so the first call initialises Firebase (when your app has not), sets consent and enables collection, once.

  • Consent on every start: analytics storage granted, ad_storage, ad_user_data and ad_personalization denied. Nothing flips the ad signals.
  • Collection is switched on at first use unless the device opted out. The native keys ship it off, so nothing is collected before then.
  • A page view is screen_view with the route pattern as the screen name and class; the location and referrer are not Firebase parameters and are dropped.
  • Default parameters go through setDefaultEventParameters, which takes the whole map.
  • reset() nulls the user id, every user property and the default parameters. It never calls resetAnalyticsData, which would rotate the app instance id.

Null Driver#

NullDriver completes every call and sends nothing, and clientId() answers null. It keeps the package inert until the host sets its IDs, and it is what a platform without a transport gets.

Writing a Driver#

A driver implements AnalyticsDriver. A driver may throw: the manager catches and logs. setDefaultParams receives only the keys to change, and a null value removes that key. reset() runs after the manager has already nulled the identity through the other methods, so it clears only what those cannot reach, and it must not rotate the client id.

dart
import 'package:magic_analytics/magic_analytics.dart';

/// Records each event and page view, as a starting point for a custom transport.
class LogDriver implements AnalyticsDriver {
  final List<String> lines = <String>[];

  @override
  Future<void> logEvent(String name, Map<String, Object> parameters) async {
    lines.add('$name $parameters');
  }

  @override
  Future<void> logScreen({
    required String name,
    String? location,
    String? referrer,
  }) async {
    lines.add('screen $name');
  }

  @override
  Future<void> setUserId(String? userId) async {}

  @override
  Future<void> setUserProperty(String name, String? value) async {}

  @override
  Future<void> setDefaultParams(Map<String, Object?> parameters) async {}

  @override
  Future<void> setOptOut(bool optedOut) async {}

  @override
  Future<String?> clientId() async => null;

  @override
  Future<void> reset() async {}
}

Bind a manager over it with app.singleton('analytics', () => AnalyticsManager(LogDriver())) in your own provider, instead of registering AnalyticsServiceProvider.

Gotchas#

Mistake Fix
A container served from googletagmanager.com Set gtm.gateway_path; without it the web driver is the null driver
Leaving send_page_view on in the GA4 configuration Set it to false; the driver pushes each page view and a second source double counts
A container with only the Google tag Add the GA4 Event tag on a Custom Event trigger, or no custom event reaches GA4
Tags without analytics_storage required Require it on both, or an opted-out device still sends cookieless pings
Initialising Firebase on web Never; leave firebase_options null there
Expecting the web driver to send before the first event It loads lazily, so the network tab is empty until then
firebase_options set to a value, not a function It must be () => DefaultFirebaseOptions.currentPlatform
esc

Search index did not load.

No match for "".

Try a class like rounded-lg or a widget like WButton.