Add screen engagement tracking of time spent and list items scrolled on a screen (close #654)

snowplow-demo-compose/src/main/java/com/snowplowanalytics/snowplowdemocompose/data/Tracking.kt

@@ -10,6 +10,7 @@ import com.snowplowanalytics.snowplow.configuration.NetworkConfiguration
 import com.snowplowanalytics.snowplow.configuration.TrackerConfiguration
 import com.snowplowanalytics.snowplow.controller.TrackerController
 import com.snowplowanalytics.snowplow.emitter.BufferOption
+import com.snowplowanalytics.snowplow.event.ListItemView
 import com.snowplowanalytics.snowplow.event.ScreenView
 import com.snowplowanalytics.snowplow.network.HttpMethod
 import com.snowplowanalytics.snowplow.payload.SelfDescribingJson
@@ -20,7 +21,10 @@ object Tracking {
     fun setup(namespace: String) : TrackerController {
         // Replace this collector endpoint with your own
         val networkConfig = NetworkConfiguration("https://23a6-82-26-43-253.ngrok.io", HttpMethod.POST)
-        val trackerConfig = TrackerConfiguration("appID").logLevel(LogLevel.DEBUG)
+        val trackerConfig = TrackerConfiguration("appID")
+            .logLevel(LogLevel.DEBUG)
+            .screenViewAutotracking(false)
+            .lifecycleAutotracking(true)
         val emitterConfig = EmitterConfiguration().bufferOption(BufferOption.Single)
 
         return Snowplow.createTracker(
@@ -48,4 +52,12 @@ object Tracking {
             Snowplow.defaultTracker?.track(event)
         })
     }
+
+    @Composable
+    fun TrackListItemView(index: Int, itemsCount: Int?) {
+        LaunchedEffect(Unit, block = {
+            val event = ListItemView(index, itemsCount)
+            Snowplow.defaultTracker?.track(event)
+        })
+    }
 }

snowplow-demo-compose/src/main/java/com/snowplowanalytics/snowplowdemocompose/ui/SchemaDetailScreen.kt

@@ -36,8 +36,7 @@ fun SchemaDetailScreen(
         "iglu:com.snowplowanalytics.iglu/anything-a/jsonschema/1-0-0", 
         hashMapOf("name" to schemaParts.name, "vendor" to schemaParts.vendor)
     )
-    Tracking.ManuallyTrackScreenView("schema_detail", entities = listOf(entity))
-
+
     Scaffold(
         topBar = {
             TopAppBar(

snowplow-demo-compose/src/main/java/com/snowplowanalytics/snowplowdemocompose/ui/SchemaListScreen.kt

@@ -4,6 +4,7 @@ import androidx.compose.foundation.clickable
 import androidx.compose.foundation.layout.*
 import androidx.compose.foundation.lazy.LazyColumn
 import androidx.compose.foundation.lazy.items
+import androidx.compose.foundation.lazy.itemsIndexed
 import androidx.compose.material.*
 import androidx.compose.material.icons.Icons
 import androidx.compose.material.icons.filled.ArrowForward
@@ -16,6 +17,7 @@ import androidx.compose.ui.text.style.TextOverflow
 import androidx.compose.ui.unit.dp
 import com.snowplowanalytics.snowplowdemocompose.R
 import com.snowplowanalytics.snowplowdemocompose.data.SchemaUrlParts
+import com.snowplowanalytics.snowplowdemocompose.data.Tracking
 
 @Composable
 fun SchemaListScreen(
@@ -38,7 +40,11 @@ fun SchemaListScreen(
             if (vm.errorMessage.isEmpty()) {
                 Column(modifier = Modifier.padding(contentPadding)) {
                     LazyColumn(modifier = Modifier.fillMaxHeight()) {
-                        items(vm.schemaPartsList) { schema ->
+                        itemsIndexed(vm.schemaPartsList) { index, schema ->
+                            Tracking.TrackListItemView(
+                                index = index,
+                                itemsCount = vm.schemaPartsList.size
+                            )
                             SchemaCard(schema = schema, onClick = onSchemaClicked)
                         }
                     }

snowplow-tracker/src/androidTest/java/com/snowplowanalytics/snowplow/internal/tracker/StateManagerTest.kt

@@ -454,6 +454,9 @@ internal open class MockStateMachine(
 ) : StateMachineInterface {
     var afterTrackEvents: MutableList<InspectableEvent> = ArrayList()
 
+    override val subscribedEventSchemasForEventsBefore: List<String>
+        get() = emptyList()
+
     override val subscribedEventSchemasForTransitions: List<String>
         get() = LinkedList(listOf("inc", "dec"))
 
@@ -469,6 +472,10 @@ internal open class MockStateMachine(
     override val subscribedEventSchemasForFiltering: List<String>
         get() = Collections.singletonList("s1")
 
+    override fun eventsBefore(event: Event): List<Event>? {
+        return null
+    }
+
     override fun transition(event: Event, state: State?): State? {
         val e = event as SelfDescribing
         var currentState = state as MockState?

snowplow-tracker/src/androidTest/java/com/snowplowanalytics/snowplow/screenviews/ScreenSummaryStateMachineTest.kt

@@ -0,0 +1,172 @@
+/*
+ * Copyright (c) 2015-2023 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
+
+import android.content.Context
+import androidx.test.ext.junit.runners.AndroidJUnit4
+import androidx.test.platform.app.InstrumentationRegistry
+import com.snowplowanalytics.core.constants.TrackerConstants
+import com.snowplowanalytics.core.screenviews.ScreenSummaryState
+import com.snowplowanalytics.snowplow.Snowplow
+import com.snowplowanalytics.snowplow.Snowplow.removeAllTrackers
+import com.snowplowanalytics.snowplow.configuration.Configuration
+import com.snowplowanalytics.snowplow.configuration.NetworkConfiguration
+import com.snowplowanalytics.snowplow.configuration.PluginConfiguration
+import com.snowplowanalytics.snowplow.controller.TrackerController
+import com.snowplowanalytics.snowplow.event.*
+import com.snowplowanalytics.snowplow.network.HttpMethod
+import com.snowplowanalytics.snowplow.payload.SelfDescribingJson
+import com.snowplowanalytics.snowplow.util.EventSink
+import com.snowplowanalytics.snowplow.util.TimeTraveler
+import org.junit.After
+import org.junit.Assert
+import org.junit.Before
+import org.junit.Test
+import org.junit.runner.RunWith
+import java.util.*
+import kotlin.time.DurationUnit
+import kotlin.time.toDuration
+
+@RunWith(AndroidJUnit4::class)
+class ScreenSummaryStateMachineTest {
+
+    var timeTraveler = TimeTraveler()
+
+    @Before
+    fun setUp() {
+        ScreenSummaryState.dateGenerator = { timeTraveler.generateTimestamp() }
+    }
+
+    @After
+    fun tearDown() {
+        removeAllTrackers()
+    }
+
+    // --- TESTS
+
+    @Test
+    fun tracksTransitionToBackgroundAndForeground() {
+        val eventSink = EventSink()
+        val tracker = createTracker(listOf(eventSink))
+
+        tracker.track(ScreenView(name = "Screen 1"))
+        timeTraveler.travelBy(10.toDuration(DurationUnit.SECONDS))
+        tracker.track(Background())
+        Thread.sleep(200)
+
+        timeTraveler.travelBy(5.toDuration(DurationUnit.SECONDS))
+        tracker.track(Foreground())
+        Thread.sleep(200)
+
+        val events = eventSink.trackedEvents
+        Assert.assertEquals(3, events.size)
+
+        val backgroundSummary = getScreenSummary(events.find { it.schema == Background.schema })
+        Assert.assertEquals(10.0, backgroundSummary?.get("foreground_sec"))
+        Assert.assertEquals(0.0, backgroundSummary?.get("background_sec"))
+
+        val foregroundSummary = getScreenSummary(events.find { it.schema == Foreground.schema })
+        Assert.assertEquals(10.0, foregroundSummary?.get("foreground_sec"))
+        Assert.assertEquals(5.0, foregroundSummary?.get("background_sec"))
+    }
+
+    @Test
+    fun tracksScreenEndEventWithScreenSummary() {
+        val eventSink = EventSink()
+        val tracker = createTracker(listOf(eventSink))
+
+        tracker.track(ScreenView(name = "Screen 1"))
+        Thread.sleep(200)
+        timeTraveler.travelBy(10.toDuration(DurationUnit.SECONDS))
+        tracker.track(ScreenView(name = "Screen 2"))
+        Thread.sleep(200)
+
+        val events = eventSink.trackedEvents
+        Assert.assertEquals(3, events.size)
+
+        val screenSummary = getScreenSummary(events.find { it.schema == TrackerConstants.SCHEMA_SCREEN_END })
+        Assert.assertEquals(10.0, screenSummary?.get("foreground_sec"))
+        Assert.assertEquals(0.0, screenSummary?.get("background_sec"))
+    }
+
+    @Test
+    fun updatesListMetrics() {
+        val eventSink = EventSink()
+        val tracker = createTracker(listOf(eventSink))
+
+        tracker.track(ScreenView(name = "Screen 1"))
+        Thread.sleep(200)
+        tracker.track(ListItemView(index = 1, itemsCount = 10))
+        Thread.sleep(200)
+        tracker.track(ListItemView(index = 3, itemsCount = 10))
+        Thread.sleep(200)
+        tracker.track(ListItemView(index = 2, itemsCount = 10))
+        Thread.sleep(200)
+        tracker.track(ScreenView(name = "Screen 2"))
+        Thread.sleep(200)
+
+        val events = eventSink.trackedEvents
+        Assert.assertEquals(3, events.size)
+
+        val screenSummary = getScreenSummary(events.find { it.schema == TrackerConstants.SCHEMA_SCREEN_END })
+        Assert.assertEquals(3, screenSummary?.get("last_item_index"))
+        Assert.assertEquals(10, screenSummary?.get("items_count"))
+    }
+
+    @Test
+    fun updatesScrollMetrics() {
+        val eventSink = EventSink()
+        val tracker = createTracker(listOf(eventSink))
+
+        tracker.track(ScreenView(name = "Screen 1"))
+        Thread.sleep(200)
+        tracker.track(ScrollChanged(yOffset = 10, viewHeight = 20, contentHeight = 100))
+        Thread.sleep(200)
+        tracker.track(ScrollChanged(xOffset = 15, yOffset = 30, viewWidth = 15, viewHeight = 20, contentWidth = 150, contentHeight = 100))
+        Thread.sleep(200)
+        tracker.track(ScrollChanged(yOffset = 20, viewHeight = 20, contentHeight = 100))
+        Thread.sleep(200)
+        tracker.track(ScreenView(name = "Screen 2"))
+        Thread.sleep(200)
+
+        val events = eventSink.trackedEvents
+        Assert.assertEquals(3, events.size)
+
+        val screenSummary = getScreenSummary(events.find { it.schema == TrackerConstants.SCHEMA_SCREEN_END })
+        Assert.assertEquals(10, screenSummary?.get("min_y_offset"))
+        Assert.assertEquals(15, screenSummary?.get("min_x_offset"))
+        Assert.assertEquals(50, screenSummary?.get("max_y_offset"))
+        Assert.assertEquals(30, screenSummary?.get("max_x_offset"))
+        Assert.assertEquals(150, screenSummary?.get("content_width"))
+        Assert.assertEquals(100, screenSummary?.get("content_height"))
+    }
+
+    // --- PRIVATE
+    private val context: Context
+        get() = InstrumentationRegistry.getInstrumentation().targetContext
+
+    private fun getScreenSummary(event: InspectableEvent?): Map<String, Any?>? {
+        val entity = event?.entities?.find { it.map["schema"] == TrackerConstants.SCHEMA_SCREEN_SUMMARY }
+        return entity?.map?.get("data") as? Map<String, Any?>
+    }
+
+    private fun createTracker(configurations: List<Configuration>): TrackerController {
+        val networkConfig = NetworkConfiguration(MockNetworkConnection(HttpMethod.POST, 200))
+        return Snowplow.createTracker(
+            context,
+            namespace = "ns" + Math.random().toString(),
+            network = networkConfig,
+            configurations = configurations.toTypedArray()
+        )
+    }
+}

snowplow-tracker/src/androidTest/java/com/snowplowanalytics/snowplow/util/EventSink.kt

@@ -0,0 +1,23 @@
+package com.snowplowanalytics.snowplow.util
+
+import com.snowplowanalytics.snowplow.configuration.*
+import com.snowplowanalytics.snowplow.tracker.InspectableEvent
+
+class EventSink : Configuration, PluginIdentifiable, PluginFilterCallable {
+
+    var trackedEvents = mutableListOf<InspectableEvent>()
+
+    override val identifier: String
+        get() = "EventSink"
+
+    override val filterConfiguration: PluginFilterConfiguration?
+        get() = PluginFilterConfiguration { event ->
+            trackedEvents.add(event)
+            false
+        }
+
+    override fun copy(): Configuration {
+        TODO("Not yet implemented")
+    }
+
+}

snowplow-tracker/src/androidTest/java/com/snowplowanalytics/snowplow/util/TimeTraveler.kt

@@ -26,4 +26,8 @@ class TimeTraveler {
     fun generateDate(): Date {
         return date
     }
+
+    fun generateTimestamp(): Long {
+        return date.time
+    }
 }

snowplow-tracker/src/main/java/com/snowplowanalytics/core/constants/TrackerConstants.kt

@@ -65,6 +65,14 @@ object TrackerConstants {
         "iglu:com.snowplowanalytics.snowplow.ecommerce/user/jsonschema/1-0-0"
     const val SCHEMA_ECOMMERCE_PAGE =
         "iglu:com.snowplowanalytics.snowplow.ecommerce/page/jsonschema/1-0-0"
+    const val SCHEMA_SCREEN_END =
+        "iglu:com.snowplowanalytics.mobile/screen_end/jsonschema/1-0-0"
+    const val SCHEMA_SCREEN_SUMMARY =
+        "iglu:com.snowplowanalytics.mobile/screen_summary/jsonschema/1-0-0"
+    const val SCHEMA_LIST_ITEM_VIEW =
+        "iglu:com.snowplowanalytics.mobile/list_item_view/jsonschema/1-0-0"
+    const val SCHEMA_SCROLL_CHANGED =
+        "iglu:com.snowplowanalytics.mobile/scroll_changed/jsonschema/1-0-0"
     const val POST_CONTENT_TYPE = "application/json; charset=utf-8"
     const val EVENT_PAGE_VIEW = "pv"
     const val EVENT_STRUCTURED = "se"

snowplow-tracker/src/main/java/com/snowplowanalytics/core/event/ScreenEnd.kt

@@ -0,0 +1,30 @@
+/*
+ * Copyright (c) 2015-2023 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.event
+
+import com.snowplowanalytics.core.constants.TrackerConstants
+import java.util.*
+
+class ScreenEnd : AbstractSelfDescribing() {
+
+    // Tracker methods
+    override val dataPayload: Map<String, Any?>
+        get() {
+            val payload = HashMap<String, Any?>()
+            return payload
+        }
+
+    override val schema: String
+        get() = TrackerConstants.SCHEMA_SCREEN_END
+
+}

snowplow-tracker/src/main/java/com/snowplowanalytics/core/tracker/ScreenState.kt → snowplow-tracker/src/main/java/com/snowplowanalytics/core/screenviews/ScreenState.kt

@@ -10,7 +10,7 @@
  * "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.core.tracker
+package com.snowplowanalytics.core.screenviews
 
 import androidx.annotation.RestrictTo
 import com.snowplowanalytics.core.constants.Parameters

snowplow-tracker/src/main/java/com/snowplowanalytics/core/tracker/ScreenStateMachine.kt → snowplow-tracker/src/main/java/com/snowplowanalytics/core/screenviews/ScreenStateMachine.kt

@@ -10,7 +10,7 @@
  * "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.core.tracker
+package com.snowplowanalytics.core.screenviews
 
 import com.snowplowanalytics.core.constants.Parameters
 import com.snowplowanalytics.core.constants.TrackerConstants
@@ -50,6 +50,9 @@ class ScreenStateMachine : StateMachineInterface {
     override val subscribedEventSchemasForFiltering: List<String>
         get() = emptyList()
 
+    override val subscribedEventSchemasForEventsBefore: List<String>
+        get() = emptyList()
+
     override fun transition(event: Event, state: State?): State? {
         val screenView = event as? ScreenView
         val screenState: ScreenState? = if (state != null) {
@@ -108,6 +111,10 @@ class ScreenStateMachine : StateMachineInterface {
         return null
     }
 
+    override fun eventsBefore(event: Event): List<Event>? {
+        return null
+    }
+
     companion object {
         val ID: String
             get() = "ScreenContext"