# Initialize and configure the Flutter tracker > Initialize the Flutter tracker with createTracker method and configure TrackerConfiguration, SubjectConfiguration, GdprConfiguration, and EmitterConfiguration. Set up app identifiers, context entities, session tracking, and anonymous tracking options. > Source: https://docs.snowplow.io/docs/sources/flutter-tracker/initialization-and-configuration/ > Documentation index: https://docs.snowplow.io/llms.txt The package provides a single method to initialize and configure a new tracker, the `Snowplow.createTracker` method. It accepts configuration parameters for the tracker and returns a `SnowplowTracker` instance. ```dart SnowplowTracker tracker = await Snowplow.createTracker( namespace: 'ns1', endpoint: 'http://...', trackerConfig: const TrackerConfiguration(...), gdprConfig: const GdprConfiguration(...), subjectConfig: const SubjectConfiguration(...)); ); ``` The method returns a `SnowplowTracker` instance. This can be later used for tracking events, or accessing tracker properties. However, all methods provided by the `SnowplowTracker` instance are also available as static functions in the `Snowplow` class but they require passing the tracker namespace as string. The only required attributes of the `Snowplow.createTracker` method are `namespace` used to identify the tracker, and the Snowplow collector `endpoint`. Additionally, one can configure the HTTP method to be used when sending events to the collector, as well as a custom POST path, and provide configuration by instantiating classes for `TrackerConfiguration`, `SubjectConfiguration`, or `GdprConfiguration`. By default, events are sent by POST. The following arguments are accepted by the `Snowplow.createTracker` method: | Attribute | Type | Description | | ---------------------- | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------- | | `namespace` | `String` | Tracker namespace to identify the tracker. | | `endpoint` | `String` | URI for the Snowplow collector endpoint. | | `method` | `Method?` | HTTP method to use: `Method.get` or `Method.post` (`Method.post` is default). | | `customPostPath` | `String?` | Custom POST path. | | `requestHeaders` | `Map?` | Map of custom HTTP headers to add to requests to the collector. | | `trackerConfig` | `TrackerConfiguration?` | Configuration of the tracker and the core tracker properties. | | `gdprConfig` | `GdprConfiguration?` | Determines the GDPR context that will be attached to all events sent by the tracker. | | `subjectConfig` | `SubjectConfiguration?` | Subject information about tracked user and device that is added to events. | | `emitterConfig` | `EmitterConfiguration?` | Configuration for how the events are sent. | | `globalContextsConfig` | `GlobalContextsConfiguration?` | Configuration of global context entities attached to all events. | | `sessionConfig` | `SessionConfiguration?` | Configuration of session timeouts. See [session tracking](/docs/sources/flutter-tracker/sessions-and-data-model/#configure-session-timeouts). | | `plugins` | `List?` | Plugins that inspect tracked events. See [plugins](/docs/sources/flutter-tracker/plugins/). | > **Note:** The ability to set `customPostPath` was added in v0.2.0. Setting a custom POST path can be useful in avoiding adblockers; it replaces the default "com.snowplowanalytics/snowplow/tp2". Your event collector must also be configured to accept the custom path. > **Note:** The `EmitterConfiguration` class was added in v0.3.0. > **Note: Version support** > > The `GlobalContextsConfiguration` class was added in 0.9.0. > **Note: Version support** > > The `SessionConfiguration` class was added in 0.11.1. > **Note: Version support** > > The `plugins` argument was added in 0.11.2. ## Configuration of tracker properties: `TrackerConfiguration` `TrackerConfiguration` provides options to configure properties and features of the tracker. In addition to setting the app identifier and device platform, the configuration enables turning several automatic context entities on and off. | Attribute | Type | Description | Android | iOS | Web | Default | | ------------------------------ | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------- | --- | --- | --------------------------------------------- | | `appId` | `String?` | Identifier of the app. | ✔ | ✔ | ✔ | null on Web, bundle identifier on iOS/Android | | `devicePlatform` | `DevicePlatform?` | The device platform the tracker runs on. Available options are provided by the `DevicePlatform` enum. | ✔ | ✔ | ✔ | "web" on Web, "mob" on iOS/Android | | `base64Encoding` | `bool?` | Indicates whether payload JSON data should be base64 encoded. | ✔ | ✔ | ✔ | true | | `platformContext` | `bool?` | Indicates whether [platform](http://iglucentral.com/schemas/com.snowplowanalytics.snowplow/mobile_context/jsonschema/1-0-2) (mobile) entity should be attached to tracked events. | ✔ | ✔ | | true | | `geoLocationContext` | `bool?` | Indicates whether [geo-location](http://iglucentral.com/schemas/com.snowplowanalytics.snowplow/geolocation_context/jsonschema/1-1-0) entity should be attached to tracked events. | ✔ | ✔ | ✔ | false | | `sessionContext` | `bool?` | Indicates whether [session](http://iglucentral.com/schemas/com.snowplowanalytics.snowplow/client_session/jsonschema/1-0-2) entity should be attached to tracked events. | ✔ | ✔ | ✔ | true | | `webPageContext` | `bool?` | Indicates whether a context entity about current [web page](http://iglucentral.com/schemas/com.snowplowanalytics.snowplow/web_page/jsonschema/1-0-0) should be attached to tracked events. | | | ✔ | true | | `screenContext` | `bool?` | Indicates whether [screen](http://iglucentral.com/schemas/com.snowplowanalytics.mobile/screen/jsonschema/1-0-0) entity should be attached to tracked events. | ✔ | ✔ | | true | | `applicationContext` | `bool?` | Indicates whether [application](http://iglucentral.com/schemas/com.snowplowanalytics.mobile/application/jsonschema/1-0-0) entity should be attached to tracked events. | ✔ | ✔ | | true | | `webActivityTracking` | `WebActivityTracking?` | Enables activity tracking using page views and pings on the Web. | | | ✔ | true | | `userAnonymisation` | `bool?` | Anonymizes certain user identifiers. | ✔ | ✔ | ✔ | false | | `lifecycleAutotracking` | `bool?` | Indicates whether the [lifecycle](iglu:com.snowplowanalytics.mobile/application_lifecycle/jsonschema/1-0-0) entity and foreground and background events should be autotracked. | ✔ | ✔ | | true | | `screenEngagementAutotracking` | `bool?` | Indicates whether to enable tracking of the screen end event and the screen summary context entity. | ✔ | ✔ | | true | | `installAutotracking` | `bool?` | Indicates whether to track an [application install](/docs/events/ootb-data/mobile-lifecycle-events/#install-events) event. | ✔ | ✔ | | false | | `platformContextProperties` | `PlatformContextProperties?` | Overrides for the values for properties of the platform context entity. | ✔ | ✔ | | null | > **Note:** The ability to enable `userAnonymisation`, or the screen and application context entities, was added in v0.3.0. > **Note:** The ability to enable `lifecycleAutotracking` was added in v0.5.0. > **Note: Version support** > > The ability to enable `installAutotracking` was added in version 0.11.1. The optional `WebActivityTracking` property configures page tracking on Web. Initializing the configuration will inform `SnowplowObserver` observers (see section on auto-tracking in "Tracking events") to auto track `PageViewEvent` events instead of `ScreenView` events on navigation changes. Further, setting the `minimumVisitLength` and `heartbeatDelay` properties of the `WebActivityTracking` instance will enable activity tracking using 'page ping' events on Web. Activity tracking monitors whether a user continues to engage with a page over time, and record how they digest content on the page over time. That is accomplished using 'page ping' events. If activity tracking is enabled, the web page is monitored to see if a user is engaging with it. (E.g. is the tab in focus, does the mouse move over the page, does the user scroll etc.) If any of these things occur in a set period of time (`minimumVisitLength` seconds from page load and every `heartbeatDelay` seconds after that), a page ping event fires, and records the maximum scroll left / right and up / down in the last ping period. If there is no activity in the page (e.g. because the user is on a different browser tab), no page ping fires. Lifecycle autotracking is only available on mobile apps (iOS and Android). When configured (it is enabled by default), a Lifecycle context entity is attached to all events. It records whether the app was visible or not when the event was tracked. In addition, a `Background` event will be tracked when the app is moved to background, and a `Foreground` event when the app moves back to foreground (becomes visible on the screen). Screen engagement autotracking is also only available on mobile apps (iOS and Android). When configured (it is enabled by default), a screen summary context entity will be tracked along with screen end, foreground and background events. Make sure that you have lifecycle autotracking enabled for screen summary to have complete information. Install autotracking is also only available on mobile apps (iOS and Android), and is disabled by default in the Flutter tracker. When enabled, the tracker sends an [application install](/docs/events/ootb-data/mobile-lifecycle-events/#install-events) event once per device, the first time a tracker is created with the option enabled. ```dart SnowplowTracker tracker = await Snowplow.createTracker( namespace: 'ns1', endpoint: 'http://...', trackerConfig: const TrackerConfiguration(installAutotracking: true)); ``` > **Warning: Enabling install tracking in a released app** > > The tracker only records that the install event was sent while `installAutotracking` is enabled. If you enable it in an app version that is already released, each existing user sends one install event the first time they open the updated app. Account for this in any install metrics around the rollout. See [this page](/docs/sources/flutter-tracker/anonymous-tracking/) for information about anonymous tracking. ## Configuration of emitter properties: `EmitterConfiguration` The `EmitterConfiguration` class was added in version 0.3.0. It configures how the tracker sends events and how long it keeps events that it couldn't send yet. | Attribute | Type | Description | Android | iOS | Web | Default | | --------------------- | ----------- | ------------------------------------------------------------------------ | ------- | --- | --- | ------- | | `serverAnonymisation` | `bool?` | Prevents tracking of server-side user identifiers. | ✔ | ✔ | ✔ | false | | `maxEventStoreSize` | `int?` | Maximum number of unsent events to keep in the event store. | ✔ | ✔ | | 1000 | | `maxEventStoreAge` | `Duration?` | Maximum time to keep unsent events in the event store, in whole seconds. | ✔ | ✔ | | 30 days | > **Note: Version support** > > The `maxEventStoreSize` and `maxEventStoreAge` options were added in version 0.11.1. On iOS and Android, the tracker stores events in a local database until the collector accepts them. When the device is offline for a long time, for example on poor connectivity, the stored events accumulate. The event store limits control how many of them the tracker keeps, and for how long. Before each attempt to send events, the tracker removes events older than `maxEventStoreAge`. If more than `maxEventStoreSize` events remain, it removes the oldest ones until the number is under the limit. ```dart SnowplowTracker tracker = await Snowplow.createTracker( namespace: 'ns1', endpoint: 'http://...', emitterConfig: const EmitterConfiguration( maxEventStoreSize: 5000, maxEventStoreAge: Duration(days: 7))); ``` `maxEventStoreSize` must be greater than 0, and `maxEventStoreAge` must be at least 1 second. The tracker throws an `ArgumentError` for smaller values, since they would remove all unsent events. On Web, the JavaScript tracker keeps its own event queue and the event store limits have no effect. ## Configuration of subject information: `SubjectConfiguration` Subject information are persistent and global information about the tracked device or user. They apply to all events and are assigned as event properties. Some of the properties are only configurable on iOS and Android and are automatically assigned on the Web. | Attribute | Type | Description | Android | iOS | Web | Default | | ------------------ | --------- | --------------------------------------------------------------- | ------- | --- | -------------------------------- | ------- | | `userId` | `String?` | Business ID of the user. | ✔ | ✔ | ✔ | | | `networkUserId` | `String?` | Network user ID (UUIDv4). | ✔ | ✔ | Non-configurable, auto-assigned. | | | `domainUserId` | `String?` | Domain user ID (UUIDv4). | ✔ | ✔ | Non-configurable, auto-assigned. | | | `userAgent` | `String?` | Custom user-agent. It overrides the user-agent used by default. | ✔ | ✔ | Non-configurable, auto-assigned. | | | `ipAddress` | `String?` | IP address. | ✔ | ✔ | Non-configurable, auto-assigned. | | | `timezone` | `String?` | The timezone label. | ✔ | ✔ | Non-configurable, auto-assigned. | | | `language` | `String?` | The language set on the device. | ✔ | ✔ | Non-configurable, auto-assigned. | | | `screenResolution` | `Size?` | The screen resolution on the device. | ✔ | ✔ | Non-configurable, auto-assigned. | | | `screenViewport` | `Size?` | The screen viewport. | ✔ | ✔ | Non-configurable, auto-assigned. | | | `colorDepth` | `double?` | The color depth. | ✔ | ✔ | Non-configurable, auto-assigned. | | The configured attributes are mapped to Snowplow event properties described in the [Snowplow Tracker Protocol](/docs/events/). They are mapped as follows: | Attribute | Event Property | | ------------------------- | ------------------- | | `userId` | `uid` | | `networkUserId` | `network_userid` | | `domainUserId` | `domain_userid` | | `userAgent` | `useragent` | | `ipAddress` | `user_ipaddress` | | `timezone` | `os_timezone` | | `language` | `lang` | | `screenResolution.width` | `dvce_screenwidth` | | `screenResolution.height` | `dvce_screenheight` | | `screenViewport.width` | `br_viewwidth` | | `screenViewport.height` | `br_viewheight` | | `colorDepth` | `br_colordepth` | ## GDPR context entity configuration: `GdprConfiguration` Determines the GDPR context that will be attached to all events sent by the tracker. | Attribute | Type | Description | Android | iOS | Web | Default | | --------------------- | -------- | ---------------------------- | ------- | --- | --- | ------- | | `basisForProcessing` | `String` | Basis for processing. | ✔ | ✔ | ✔ | | | `documentId` | `String` | ID of a GDPR basis document. | ✔ | ✔ | ✔ | | | `documentVersion` | `String` | Version of the document. | ✔ | ✔ | ✔ | | | `documentDescription` | `String` | Description of the document. | ✔ | ✔ | ✔ | | ## Global context configuration: `GlobalContextsConfiguration` Configures global context entities to attach to all events. Unlike per-event context entities, global context entities are sent with every event without needing to specify them on individual `track()` calls. | Attribute | Type | Description | Android | iOS | Web | Default | | ---------- | ---------------------- | --------------------------------------------------------- | ------- | --- | --- | ------- | | `contexts` | `List` | List of context entities to attach to all tracked events. | ✔ | ✔ | ✔ | empty | See the [Global context page](/docs/sources/flutter-tracker/adding-data/global-context/) for detailed information on configuring global contexts at initialization time and managing them dynamically at runtime.