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

[matus-tomlein]

Issue #654

This PR adds screen engagement tracking to the tracker.

Screen engagement tracking is enabled by default. It can be disabled using the TrackerConfiguration.screenEngagementAutotracking configuration option.

It consists of the following events and entities:

• Screen summary entity.
• Screen end event.
• List item view event (optional).
• Scroll changed event (optional).

Screen summary entity

The screen engagement information is attached in a screen_summary entity. The entity has information about the time spent on the screen in foreground and background.

It also contains information about the scroll depth on the screen – this is in the form of the last item in a list that the user reached in the screen out of all list items. It is updated using a list_item_view event, see below.

The screen summary entity is attached to the following events:

• foreground event
• background event
• screen end event

Screen end event

The screen_end event is a new event that is tracked automatically before transitioning from one screen view to another screen view event. It does not have any properties, it's only tracked to contain the screen summary information.

In order to implement it, I added a beforeEvents function to the state machines. Using this function, the state machines can return a list of events to be tracked before another event. The new ScreenSummaryStateMachine returns the screen end event whenever a screen view event is tracked.

List item view events

List item view events are tracked as the user scrolls through a list view on the screen. Whenever an item in the list is shown, the event should be tracked. It contains two information:

1. The index of the list item shown.
2. The total number of items in the list.

If screen engagement tracking is enabled, the list item view events are aggregated into the screen_summary entity. This means that they are not tracked individually, but the maximum index of viewed items and the total number of items are tracked in the entity on the next screen end or background/foreground event.

In JetPack compose app, list item view tracking can be implemented similarly as manual screen view tracking – by adding a LaunchedEffect to the list item component. I have updated the compose demo app to include this. The launched effect looks like this:

        LaunchedEffect(Unit, block = {
            val event = ListItemView(index, itemsCount)
            Snowplow.defaultTracker?.track(event)
        })

Scroll changed events

Scroll changed events are similar to the list item view events. They are tracked when the position of a scroll view changes – when the user scrolls. In contrast with the list item view events, the scroll changed events track the position in pixels.

Users will need to implement them manually since we can't provide automatic tracking. In Android Activities, this is a matter of adding a listener for on scroll changed and tracking a ScrollChanged event with the current position. The event will be aggregated into the screen_summary entity and populate the properties max_y_offset and content_height.

Iglu Central PR with schemas

Schemas for the new events and entity are not yet published on Iglu Central, they are in review in this PR.

Demo

I have recorded a demo of how the screen engagement tracking works here.

[mscwilson]

LGTM! Fantastic addition.