Merge branch 'release/0.3.0'

Author: mscwilson

CHANGELOG.md

@@ -1,3 +1,7 @@
+# 0.3.0
+* Enable screen and application context on mobile (#27)  
+* Add anonymous tracking features (#16)
+
 # 0.2.0
 * Configure custom POST path (#15)  
 * Upgrade underlying mobile native trackers to version 4 (#17)  

README.md

@@ -47,7 +47,7 @@ This will add a line with the dependency like this to your `pubspec.yaml`:
 
 ```yml
 dependencies:
-    snowplow_tracker: ^0.2.0
+    snowplow_tracker: ^0.3.0
 ```
 
 Import the package into your Dart code:
@@ -157,7 +157,7 @@ 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 integration tests (replace the Snowplow Micro URI with your IP address and set your iPhone or Android simulator name or remove to use default):
+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):
 
 ```bash
 flutter run --dart-define=ENDPOINT=http://192.168.100.127:9090 -d "iPhone 13 Pro"
@@ -167,13 +167,13 @@ To run the example app on Web:
 
 1. [Download ChromeDriver](https://chromedriver.chromium.org/downloads) 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):
+3. Run the app (replace the Snowplow Micro URI with your IP address):
 
 ```bash
 flutter run --dart-define=ENDPOINT=http://0.0.0.0:9090 -d Chrome
 ```
 
-Alternatively, you may also run the integration tests from Visual Studio Code using the "Run Example App" target (update your IP address in launch.json).
+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
 

android/src/main/kotlin/com/snowplowanalytics/snowplow_tracker/SnowplowTrackerController.kt

@@ -39,6 +39,9 @@ object SnowplowTrackerController {
         val gdprConfigReader = messageReader.gdprConfig
         gdprConfigReader?.let { controllers.add(it.toConfiguration()) }
 
+        val emitterConfigReader = messageReader.emitterConfig
+        emitterConfigReader?.let { controllers.add(it.toConfiguration()) }
+
         Snowplow.createTracker(
                 context,
                 messageReader.namespace,

android/src/main/kotlin/com/snowplowanalytics/snowplow_tracker/TrackerVersion.kt

@@ -12,5 +12,5 @@
 package com.snowplowanalytics.snowplow_tracker
 
 object TrackerVersion {
-    val TRACKER_VERSION = "flutter-0.2.0"
+    val TRACKER_VERSION = "flutter-0.3.0"
 }

android/src/main/kotlin/com/snowplowanalytics/snowplow_tracker/readers/configurations/EmitterConfigurationReader.kt

@@ -0,0 +1,28 @@
+// Copyright (c) 2022 Snowplow Analytics Ltd. All rights reserved.
+//
+// This program is licensed to you under the Apache License Version 2.0,
+// and you may not use this file except in compliance with the Apache License Version 2.0.
+// You may obtain a copy of the Apache License Version 2.0 at http://www.apache.org/licenses/LICENSE-2.0.
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the Apache License Version 2.0 is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the Apache License Version 2.0 for the specific language governing permissions and limitations there under.
+
+package com.snowplowanalytics.snowplow_tracker.readers.configurations
+
+import com.snowplowanalytics.snowplow.configuration.EmitterConfiguration
+
+class EmitterConfigurationReader(values: Map<String, Any>) {
+    private val valuesDefault = values.withDefault { null }
+
+    val serverAnonymisation: Boolean? by valuesDefault
+
+    fun toConfiguration(): EmitterConfiguration {
+        val emitterConfig = EmitterConfiguration()
+
+        serverAnonymisation?.let { emitterConfig.serverAnonymisation(it) }
+
+        return emitterConfig
+    }
+}

android/src/main/kotlin/com/snowplowanalytics/snowplow_tracker/readers/configurations/TrackerConfigurationReader.kt

@@ -25,6 +25,10 @@ class TrackerConfigurationReader(values: Map<String, Any>) {
     val platformContext: Boolean? by valuesDefault
     val geoLocationContext: Boolean? by valuesDefault
     val sessionContext: Boolean? by valuesDefault
+    val userAnonymisation: Boolean? by valuesDefault
+    val screenContext: Boolean? by valuesDefault
+    val applicationContext: Boolean? by valuesDefault
+
 
     fun toConfiguration(context: Context): TrackerConfiguration {
         val trackerConfig = DefaultTrackerConfiguration.toConfiguration(appId, context)
@@ -45,6 +49,9 @@ class TrackerConfigurationReader(values: Map<String, Any>) {
         platformContext?.let { trackerConfig.platformContext(it) }
         geoLocationContext?.let { trackerConfig.geoLocationContext(it) }
         sessionContext?.let { trackerConfig.sessionContext(it) }
+        userAnonymisation?.let { trackerConfig.userAnonymisation(it) }
+        screenContext?.let { trackerConfig.screenContext(it) }
+        applicationContext?.let { trackerConfig.applicationContext(it) }
 
         return trackerConfig
     }
@@ -54,9 +61,7 @@ object DefaultTrackerConfiguration {
     fun toConfiguration(appId: String?, context: Context): TrackerConfiguration {
         val trackerConfig = TrackerConfiguration(appId ?: context.getPackageName())
                 .trackerVersionSuffix(TrackerVersion.TRACKER_VERSION)
-
-        trackerConfig.applicationContext(false)
-        trackerConfig.screenContext(false)
+        
         trackerConfig.screenViewAutotracking(false)
         trackerConfig.lifecycleAutotracking(false)
         trackerConfig.installAutotracking(false)

android/src/main/kotlin/com/snowplowanalytics/snowplow_tracker/readers/messages/CreateTrackerMessageReader.kt

@@ -33,4 +33,9 @@ class CreateTrackerMessageReader(val values: Map<String, Any>) {
             GdprConfigurationReader(it as Map<String, Any>)
         }
     }
+    val emitterConfig: EmitterConfigurationReader? by lazy {
+        values.get("emitterConfig")?.let {
+            EmitterConfigurationReader(it as Map<String, Any>)
+        }
+    }
 }

dartdoc_options.yaml

@@ -15,7 +15,10 @@ dartdoc:
     "Sessions and data model":
       markdown: doc/05-sessions.md
       name: Sessions and data model
-  categoryOrder: ["Getting started", "Initialization and configuration", "Tracking events", "Adding data to your events", "Sessions and data model"]
+    "Anonymous tracking":
+      markdown: doc/06-anonymous-tracking.md
+      name: Anonymous tracking
+  categoryOrder: ["Getting started", "Initialization and configuration", "Tracking events", "Adding data to your events", "Sessions and data model", "Anonymous tracking"]
   showUndocumentedCategories: true
   errors:
     - unresolved-doc-reference

doc/01-getting-started.md

@@ -16,7 +16,7 @@ This will add a line with the dependency like to your pubspec.yaml:
 
 ```yml
 dependencies:
-    snowplow_tracker: ^0.2.0
+    snowplow_tracker: ^0.3.0
 ```
 
 Import the package into your Dart code:

doc/02-configuration.md

@@ -25,6 +25,7 @@ The only required attributes of the `Snowplow.createTracker` method are `namespa
 | `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.           |
 
 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.
 
@@ -37,16 +38,28 @@ Setting a custom POST path can be useful in avoiding adblockers; it replaces the
 | `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 context should be attached to tracked events. | ✔ | ✔ | | true |
-| `geoLocationContext` | `bool?` | Indicates whether geo-location context should be attached to tracked events. | ✔ | ✔ | ✔ | false |
-| `sessionContext` | `bool?` | Indicates whether session context should be attached to tracked events. | ✔ | ✔ | ✔ | true |
-| `webPageContext` | `bool?` | Indicates whether context about current web page should be attached to tracked events. | | | ✔ | true |
+| `platformContext` | `bool?` | Indicates whether [platform](http://iglucentral.com/schemas/com.snowplowanalytics.snowplow/mobile_context/jsonschema/1-0-2) (mobile) context 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) context 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) context should be attached to tracked events. | ✔ | ✔ | ✔ | true |
+| `webPageContext` | `bool?` | Indicates whether context 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) context should be attached to tracked events. | ✔ | ✔ | | true |
+| `applicationContext` | `bool?` | Indicates whether [application](http://iglucentral.com/schemas/com.snowplowanalytics.mobile/application/jsonschema/1-0-0) context should be attached to tracked events. | ✔ | ✔ | | true |
 | `webActivityTracking` | WebActivityTracking?` | Enables activity tracking using page views and pings on the Web. | | | ✔ | true |
+| `userAnonymisation` | `bool?` | Anonymises certain user identifiers. | ✔ | ✔ | ✔ | false |
 
 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.
 
+See the separate page for information about anonymous tracking.
+
+## Configuration of emitter properties: `EmitterConfiguration`
+This Configuration class was added in v0.3.0. Currently, the only property is `serverAnonymisation`.
+
+| Attribute | Type      | Description            | Android | iOS | Web | Default                                       |
+|-----------|-----------|------------------------|---------|-----|-----|-----------------------------------------------|
+| `serverAnonymisation`   | `bool?` | Prevents tracking of server-side user identifiers. | ✔       | ✔   | ✔   | false |
+
 ## 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.