snowplow_tracker 0.7.0

A package for tracking Snowplow events in Flutter apps

Flutter Analytics for Snowplow

Snowplow is a scalable open-source platform for rich, high quality, low-latency data collection. It is designed to collect high quality, complete behavioral data for enterprise business.

To find out more, please check out the Snowplow website and our documentation.

Snowplow Flutter Tracker Overview

The Snowplow Flutter Tracker allows you to add analytics to your Flutter apps when using a Snowplow pipeline.

With this tracker you can collect granular event-level data as your users interact with your Flutter applications. It is build on top of Snowplow's native iOS and Android and web trackers, in order to support the full range of out-of-the-box Snowplow events and tracking capabilities.

Technical documentation can be found for each tracker in our Documentation.

Features

Feature	Android	iOS	Web
Manual tracking of events: screen views, self-describing, structured, timing, consent granted and withdrawal	✔	✔	✔
Automatic tracking of views events from Navigator API	✔	✔	✔
Adding custom context entities to events	✔	✔	✔
Support for multiple trackers	✔	✔	✔
Configurable subject properties	✔	✔	partly
Session context entity added to events	✔	✔	✔
Geo-location context entity	✔	✔	✔
Mobile platform context entity	✔	✔
Web page context entity			✔
Configurable GDPR context entity	✔	✔	✔
Lifecycle autotracking	✔	✔
Engagement tracking (activity tracking on Web, mobile screen engagement on mobile)	✔	✔	✔
Media playback tracking	✔	✔	✔

Quick Start

Installation

Add the Snowplow tracker as a dependency to your Flutter application:

flutter pub add snowplow_tracker

This will add a line with the dependency like this to your pubspec.yaml:

dependencies:
    snowplow_tracker: ^0.7.0

Import the package into your Dart code:

import 'package:snowplow_tracker/snowplow_tracker.dart'

Installation on Web

If using the tracker within a Flutter app for Web, you will also need to import the Snowplow JavaScript Tracker in your index.html file. Please load the JS tracker with the Snowplow tag as described in the official documentation. Do not change the global function name snowplow that is used to access the tracker – the Flutter APIs assume that it remains the default as shown in documentation.

Make sure to use JavaScript tracker version 3.5 or newer. You may also refer to the example project in the Flutter tracker repository to see this in action.

Using the Tracker

Instantiate a tracker using the Snowplow.createTracker function. You may create the tracker in the initState() of your main widget. The function takes two required arguments: namespace and endpoint. Tracker namespace identifies the tracker instance; you may create multiple trackers with different namespaces. The endpoint is the URI of the Snowplow collector to send the events to. There are additional optional arguments to configure the tracker, please refer to the documentation for a complete specification.

SnowplowTracker tracker = await Snowplow.createTracker(
    namespace: 'ns1',
    endpoint: 'http://...'
);

To track events, simply instantiate their respective types (e.g., ScreenView, SelfDescribing, Structured) and pass them to the tracker.track or Snowplow.track methods. Please refer to the documentation for specification of event properties.

// Tracking a screen view event
tracker.track(ScreenView(
    id: '2c295365-eae9-4243-a3ee-5c4b7baccc8f',
    name: 'home',
    type: 'full',
    transitionType: 'none'));

// Tracking a page view event – only supported on the Web
tracker.track(PageView(title: 'Page Title'));

// Tracking a self-describing event
tracker.track(SelfDescribing(
    schema: 'iglu:com.snowplowanalytics.snowplow/link_click/jsonschema/1-0-1',
    data: {'targetUrl': 'http://a-target-url.com'}
));

// Tracking a structured event
tracker.track(Structured(
    category: 'shop',
    action: 'add-to-basket',
    label: 'Add To Basket',
    property: 'pcs',
    value: 2.00,
));

// Tracking an event using the Snowplow interface and tracker namespace
Snowplow.track(
    Structured(category: 'shop', action: 'add-to-basket'),
    tracker: 'ns1' // namespace of initialized tracker
);

// Adding context to an event
tracker.track(
    Structured(category: 'shop', action: 'add-to-basket'),
    contexts: [
        const SelfDescribing(
            schema: 'iglu:org.schema/WebPage/jsonschema/1-0-0',
            data: {'keywords': ['tester']}
        )
    ]);

Find Out More

Technical Docs	Setup Guide
Technical Docs	Setup Guide

Maintainers

Contributing
Contributing

Maintainer Quick Start

Assuming Flutter SDK is set up and Snowplow Micro is running on your computer.

Clone Repository

git clone https://github.com/snowplow/snowplow-flutter-tracker.git

Example App

The tracker comes with a demo app that shows it in use. It is a simple app with list of buttons for triggering different types of events. The project is located in the example subfolder.

Running the example app on Android/iOS:

1. Change into the project folder and cd example
2. Run the app (replace the Snowplow Micro URI with your IP address and set your iPhone or Android simulator name or remove to use default):

flutter run --dart-define=ENDPOINT=http://192.168.100.127:9090 -d "iPhone 13 Pro"

To run the example app on Web:

1. Download ChromeDriver and launch it using chromedriver --port=4444
2. Change into the project folder and cd example
3. Run the app (replace the Snowplow Micro URI with your IP address):

flutter run --dart-define=ENDPOINT=http://0.0.0.0:9090 -d Chrome

Alternatively, if you use Visual Studio Code you may also run the example app using the "Run Example App" target (update your IP address in .vscode/launch.json).

Testing

The tracker functionality is verified using unit and integration tests. Unit tests test individual components of the tracker in isolation and do not make any external network requests. Integration tests use a Snowplow Micro instance to verify end-to-end tracking of events.

The unit tests are located in the tests subfolder in the root of the project. Having installed the Flutter SDK, run the tests using flutter test (or run them directly from Visual Studio Code).

The integration tests are located in the example/integration_test subfolder. These tests make use of the example app to provide end-to-end testing of the tracker.

Running the integration tests on Android/iOS:

1. Change into the project folder and cd example
2. Run the integration tests (replace the Snowplow Micro URI with your IP address and set your iPhone or Android simulator name or remove to use default):

flutter test integration_test --dart-define=ENDPOINT=http://192.168.100.127:9090 -d "iPhone 13 Pro"

Alternatively, you may also run the integration tests directly from Visual Studio Code.

To run the integration tests on Web:

1. Download ChromeDriver and launch it using chromedriver --port=4444
2. Change into the project folder and cd example
3. Run the integration tests (replace the Snowplow Micro URI with your IP address):

./tool/e2e_tests.sh http://0.0.0.0:9090 "-d web-server"

Copyright and License

The Snowplow Flutter Tracker is copyright 2022-present Snowplow Analytics Ltd.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this software except in compliance with the License.

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.