Collecting data with Trackers and Webhooks

  1. Home
  2. Docs
  3. Collecting data with Trackers and Webhooks
  4. Trackers – collecting data from your own applications
  5. Flutter Tracker
  6. Initialization and configuration

Initialization and configuration

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.

SnowplowTracker tracker = await Snowplow.createTracker( namespace: 'ns1', endpoint: 'http://...', method: Method.post, trackerConfig: const TrackerConfiguration(...), gdprConfig: const GdprConfiguration(...), subjectConfig: const SubjectConfiguration(...)); );
Code language: Dart (dart)

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 and provide configuration by instantiating classes for TrackerConfigurationSubjectConfiguration, or GdprConfiguration. The following arguments are accepted by the Snowplow.createTracker method:

AttributeTypeDescription
namespaceStringTracker namespace to identify the tracker.
endpointStringURI for the Snowplow collector endpoint.
methodMethod?HTTP method to use. Method.get and Method.post options are available.
trackerConfigTrackerConfiguration?Configuration of the tracker and the core tracker properties.
gdprConfigGdprConfiguration?Determines the GDPR context that will be attached to all events sent by the tracker.
subjectConfigSubjectConfiguration?Subject information about tracked user and device that is added to events.

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.

AttributeTypeDescriptionAndroidiOSWebDefault
appIdString?Identifier of the app.null on Web, bundle identifier on iOS/Android
devicePlatformDevicePlatform?The device platform the tracker runs on. Available options are provided by the DevicePlatform enum.“web” on Web, “mob” on iOS/Android
base64Encodingbool?Indicates whether payload JSON data should be base64 encoded.true
platformContextbool?Indicates whether platform context should be attached to tracked events.true
geoLocationContextbool?Indicates whether geo-location context should be attached to tracked events.false
sessionContextbool?Indicates whether session context should be attached to tracked events.true
webPageContextbool?Indicates whether context about current web page should be attached to tracked events.true
webActivityTrackingWebActivityTracking?`Enables activity tracking using page views and pings on the Web.true

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 he / she digests 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 tab in his / her browser), no page ping fires.

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.

AttributeTypeDescriptionAndroidiOSWebDefault
userIdString?Business ID of the user.
networkUserIdString?Network user ID (UUIDv4).Non-configurable, auto-assigned.
domainUserIdString?Domain user ID (UUIDv4).Non-configurable, auto-assigned.
userAgentString?Custom user-agent. It overrides the user-agent used by default.Non-configurable, auto-assigned.
timezoneString?The timezone label.Non-configurable, auto-assigned.
languageString?The language set on the device.Non-configurable, auto-assigned.
screenResolutionSize?The screen resolution on the device.Non-configurable, auto-assigned.
screenViewportSize?The screen viewport.Non-configurable, auto-assigned.
colorDepthdouble?The color depth.Non-configurable, auto-assigned.

The configured attributes are mapped to Snowplow event properties described in the Snowplow Tracker Protocol. They are mapped as follows:

AttributeEvent Property
userIduid
networkUserIdnetwork_userid
domainUserIddomain_userid
userAgentuseragent
ipAddressuser_ipaddress
timezoneos_timezone
languagelang
screenResolution.widthdvce_screenwidth
screenResolution.heightdvce_screenheight
screenViewport.widthbr_viewwidth
screenViewport.heightbr_viewheight
colorDepthbr_colordepth

GDPR context entity configuration: GdprConfiguration

Determines the GDPR context that will be attached to all events sent by the tracker.

AttributeTypeDescriptionAndroidiOSWebDefault
basisForProcessingStringBasis for processing.
documentIdStringID of a GDPR basis document.
documentVersionStringVersion of the document.
documentDescriptionStringDescription of the document.

If you’d like to learn more about Snowplow BDP you can book a demo with our team, or if you’d prefer, you can try Snowplow technology for yourself quickly and easily.