Skip to content

Add lifecycle autotracking config option #39

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Dec 5, 2023
Merged

Add lifecycle autotracking config option #39

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
8b21a4c
Add lifecycleAutotracking config option
mscwilson Dec 4, 2023
4022179
Update docs
mscwilson Dec 4, 2023
e828382
Fix table
mscwilson Dec 5, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 13 additions & 12 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,18 +20,19 @@ It is build on top of Snowplow's native [iOS](https://github.com/snowplow/snowpl

## 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 | ✔ | ✔ | ✔ |
| 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 | ✔ | ✔ | |

## Quick Start

Expand Down
2 changes: 2 additions & 0 deletions ...m/snowplowanalytics/snowplow_tracker/readers/configurations/TrackerConfigurationReader.kt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,7 @@ class TrackerConfigurationReader(values: Map<String, Any>) {
val userAnonymisation: Boolean? by valuesDefault
val screenContext: Boolean? by valuesDefault
val applicationContext: Boolean? by valuesDefault
val lifecycleAutotracking: Boolean? by valuesDefault


fun toConfiguration(context: Context): TrackerConfiguration {
Expand All @@ -52,6 +53,7 @@ class TrackerConfigurationReader(values: Map<String, Any>) {
userAnonymisation?.let { trackerConfig.userAnonymisation(it) }
screenContext?.let { trackerConfig.screenContext(it) }
applicationContext?.let { trackerConfig.applicationContext(it) }
lifecycleAutotracking?.let { trackerConfig.lifecycleAutotracking(it) }

return trackerConfig
}
Expand Down
31 changes: 17 additions & 14 deletions doc/02-configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,23 +34,26 @@ Setting a custom POST path can be useful in avoiding adblockers; it replaces the

`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) 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 |
| 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 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) 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?` | Anonymises 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. | ✔ | ✔ | | 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.
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 tab in their browser), no page ping fires.

Lifecycle autotracking is only available on mobile apps (iOS and Android). When configured, 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).

See the separate page for information about anonymous tracking.

Expand Down
2 changes: 1 addition & 1 deletion example/android/build.gradle
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ buildscript {
}

dependencies {
classpath 'com.android.tools.build:gradle:7.0.4'
classpath 'com.android.tools.build:gradle:7.1.3'
classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
}
}
Expand Down
2 changes: 1 addition & 1 deletion example/ios/Podfile.lock
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,4 +38,4 @@ SPEC CHECKSUMS:

PODFILE CHECKSUM: ef19549a9bc3046e7bb7d2fab4d021637c0c58a3

COCOAPODS: 1.12.0
COCOAPODS: 1.12.1
2 changes: 1 addition & 1 deletion example/ios/Runner.xcodeproj/project.pbxproj
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -155,7 +155,7 @@
97C146E61CF9000F007C117D /* Project object */ = {
isa = PBXProject;
attributes = {
LastUpgradeCheck = 1300;
LastUpgradeCheck = 1430;
ORGANIZATIONNAME = "";
TargetAttributes = {
97C146ED1CF9000F007C117D = {
Expand Down
2 changes: 1 addition & 1 deletion example/ios/Runner.xcodeproj/xcshareddata/xcschemes/Runner.xcscheme
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
<?xml version="1.0" encoding="UTF-8"?>
<Scheme
LastUpgradeVersion = "1300"
LastUpgradeVersion = "1430"
version = "1.3">
<BuildAction
parallelizeBuildables = "YES"
Expand Down
84 changes: 46 additions & 38 deletions example/pubspec.lock
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,10 +5,10 @@ packages:
dependency: transitive
description:
name: args
sha256: eef6c46b622e0494a36c5a12d10d77fb4e855501a91c1b9ef9339326e58f0596
sha256: c372bb384f273f0c2a8aaaa226dad84dc27c8519a691b888725dec59518ad53a
url: "https://pub.dev"
source: hosted
version: "2.4.2"
version: "2.4.1"
async:
dependency: transitive
description:
Expand Down Expand Up @@ -45,18 +45,18 @@ packages:
dependency: transitive
description:
name: collection
sha256: "4a07be6cb69c84d677a6c3096fcf960cc3285a8330b4603e0d463d15d9bd934c"
sha256: ee67cb0715911d28db6bf4af1026078bd6f0128b07a5f66fb2ed94ec6783c09a
url: "https://pub.dev"
source: hosted
version: "1.17.1"
version: "1.18.0"
crypto:
dependency: transitive
description:
name: crypto
sha256: ff625774173754681d66daaf4a448684fb04b78f902da9cb3d308c19cc5e8bab
sha256: aa274aa7774f8964e4f4f38cc994db7b6158dd36e9187aaceaddc994b35c6c67
url: "https://pub.dev"
source: hosted
version: "3.0.3"
version: "3.0.2"
cupertino_icons:
dependency: "direct main"
description:
Expand Down Expand Up @@ -103,10 +103,10 @@ packages:
dependency: "direct main"
description:
name: flutter_markdown
sha256: "86b76dbf30496024d6c816bdc13b97de9449dce1f035a73ee7b4ab7f67eab70b"
sha256: dc6d5258653f6857135b32896ccda7f7af0c54dcec832495ad6835154c6c77c0
url: "https://pub.dev"
source: hosted
version: "0.6.16"
version: "0.6.15"
flutter_test:
dependency: "direct dev"
description: flutter
Expand All @@ -126,10 +126,10 @@ packages:
dependency: "direct dev"
description:
name: http
sha256: "5895291c13fa8a3bd82e76d5627f69e0d85ca6a30dcac95c4ea19a5d555879c2"
sha256: "6aa2946395183537c8b880962d935877325d6a09a2867c3970c05c0fed6ac482"
url: "https://pub.dev"
source: hosted
version: "0.13.6"
version: "0.13.5"
http_parser:
dependency: transitive
description:
Expand All @@ -147,50 +147,50 @@ packages:
dependency: transitive
description:
name: js
sha256: f2c445dce49627136094980615a031419f7f3eb393237e4ecd97ac15dea343f3
sha256: a5e201311cb08bf3912ebbe9a2be096e182d703f881136ec1e81a2338a9e120d
url: "https://pub.dev"
source: hosted
version: "0.6.7"
version: "0.6.4"
lints:
dependency: transitive
description:
name: lints
sha256: "0a217c6c989d21039f1498c3ed9f3ed71b354e69873f13a8dfc3c9fe76f1b452"
sha256: "5e4a9cd06d447758280a8ac2405101e0e2094d2a1dbdd3756aec3fe7775ba593"
url: "https://pub.dev"
source: hosted
version: "2.1.1"
version: "2.0.1"
markdown:
dependency: transitive
description:
name: markdown
sha256: "8e332924094383133cee218b676871f42db2514f1f6ac617b6cf6152a7faab8e"
sha256: b3c60dee8c2af50ad0e6e90cceba98e47718a6ee0a7a6772c77846a0cc21f78b
url: "https://pub.dev"
source: hosted
version: "7.1.0"
version: "7.0.1"
matcher:
dependency: transitive
description:
name: matcher
sha256: "6501fbd55da300384b768785b83e5ce66991266cec21af89ab9ae7f5ce1c4cbb"
sha256: "1803e76e6653768d64ed8ff2e1e67bea3ad4b923eb5c56a295c3e634bad5960e"
url: "https://pub.dev"
source: hosted
version: "0.12.15"
version: "0.12.16"
material_color_utilities:
dependency: transitive
description:
name: material_color_utilities
sha256: d92141dc6fe1dad30722f9aa826c7fbc896d021d792f80678280601aff8cf724
sha256: "9528f2f296073ff54cb9fee677df673ace1218163c3bc7628093e7eed5203d41"
url: "https://pub.dev"
source: hosted
version: "0.2.0"
version: "0.5.0"
meta:
dependency: transitive
description:
name: meta
sha256: "3c74dbf8763d36539f114c799d8a2d87343b5067e9d796ca22b5eb8437090ee3"
sha256: a6e590c838b18133bb482a2745ad77c5bb7715fb0451209e1a7567d416678b8e
url: "https://pub.dev"
source: hosted
version: "1.9.1"
version: "1.10.0"
path:
dependency: transitive
description:
Expand All @@ -203,10 +203,10 @@ packages:
dependency: transitive
description:
name: platform
sha256: "4a451831508d7d6ca779f7ac6e212b4023dd5a7d08a27a63da33756410e32b76"
sha256: ae68c7bfcd7383af3629daafb32fb4e8681c7154428da4febcff06200585f102
url: "https://pub.dev"
source: hosted
version: "3.1.0"
version: "3.1.2"
process:
dependency: transitive
description:
Expand All @@ -231,26 +231,26 @@ packages:
dependency: transitive
description:
name: source_span
sha256: dd904f795d4b4f3b870833847c461801f6750a9fa8e61ea5ac53f9422b31f250
sha256: "53e943d4206a5e30df338fd4c6e7a077e02254531b138a15aec3bd143c1a8b3c"
url: "https://pub.dev"
source: hosted
version: "1.9.1"
version: "1.10.0"
stack_trace:
dependency: transitive
description:
name: stack_trace
sha256: c3c7d8edb15bee7f0f74debd4b9c5f3c2ea86766fe4178eb2a18eb30a0bdaed5
sha256: "73713990125a6d93122541237550ee3352a2d84baad52d375a4cad2eb9b7ce0b"
url: "https://pub.dev"
source: hosted
version: "1.11.0"
version: "1.11.1"
stream_channel:
dependency: transitive
description:
name: stream_channel
sha256: "83615bee9045c1d322bbbd1ba209b7a749c2cbcdcb3fdd1df8eb488b3279c1c8"
sha256: ba2aa5d8cc609d96bbb2899c28934f9e1af5cddbd60a827822ea467161eb54e7
url: "https://pub.dev"
source: hosted
version: "2.1.1"
version: "2.1.2"
string_scanner:
dependency: transitive
description:
Expand Down Expand Up @@ -279,18 +279,18 @@ packages:
dependency: transitive
description:
name: test_api
sha256: eb6ac1540b26de412b3403a163d919ba86f6a973fe6cc50ae3541b80092fdcfb
sha256: "5c2f730018264d276c20e4f1503fd1308dfbbae39ec8ee63c5236311ac06954b"
url: "https://pub.dev"
source: hosted
version: "0.5.1"
version: "0.6.1"
typed_data:
dependency: transitive
description:
name: typed_data
sha256: facc8d6582f16042dd49f2463ff1bd6e2c9ef9f3d5da3d9b087e244a7b564b3c
sha256: "26f87ade979c47a150c9eaab93ccd2bebe70a27dc0b4b29517f2904f04eb11a5"
url: "https://pub.dev"
source: hosted
version: "1.3.2"
version: "1.3.1"
uuid:
dependency: "direct main"
description:
Expand All @@ -311,10 +311,18 @@ packages:
dependency: transitive
description:
name: vm_service
sha256: f6deed8ed625c52864792459709183da231ebf66ff0cf09e69b573227c377efe
sha256: c538be99af830f478718b51630ec1b6bee5e74e52c8a802d328d9e71d35d2583
url: "https://pub.dev"
source: hosted
version: "11.10.0"
web:
dependency: transitive
description:
name: web
sha256: afe077240a270dcfd2aafe77602b4113645af95d0ad31128cc02bce5ac5d5152
url: "https://pub.dev"
source: hosted
version: "11.3.0"
version: "0.3.0"
webdriver:
dependency: transitive
description:
Expand All @@ -324,5 +332,5 @@ packages:
source: hosted
version: "3.0.2"
sdks:
dart: ">=3.0.0 <4.0.0"
flutter: ">=3.10.0"
dart: ">=3.2.0-194.0.dev <4.0.0"
flutter: ">=3.3.0"
Loading