Page and screen engagement

Page or screen activity (engagement) tracking enables you to measure the time users spent engaged on a page or screen and the extent of the page/screen they viewed. There are two mechanisms that the activity tracking is implemented:

Using page ping events on Web.
Using the screen summary entity on mobile.

On Web using page ping events#

Page pings are used to record users engaging with content on a web page after it has originally loaded. For example, it can be used to track how far down an article a user scrolls.

If enabled, the activity tracking function checks for engagement with a page after load. (E.g. mousemovement, scrolling etc...).

Page pings are identified by e=pp. As well as all the standard web fields, there are four additional fields that pp includes, which are used to identify how users are scrolling over web pages:

Atomic Table Column	Type	Description	Example values
`pp_xoffset_min`	integer	Minimum page x offset seen in the last ping period	`0`
`pp_xoffset_max`	integer	Maximum page x offset seen in the last ping period	`100`
`pp_yoffset_min`	integer	Minimum page y offset seen in the last ping period	`0`
`pp_yoffset_max`	integer	Maximum page y offset seen in the last ping period	`100`

On mobile#

note

Screen engagement tracking is available for native Android and iOS apps starting with version 6 of the trackers.

Screen engagement information is tracked on our mobile trackers in the screen_summary context entity. The entity is tracked along with these events:

application_foreground and application_background events (see lifecycle events).
screen_end event (see below).

Screen summary entity#

Entity that contains the screen engagement information.

screen_summary

Entity

Schema for an entity tracked with foreground/background/screen_end events with summary statistics about the screen view

Schema URIiglu:com.snowplowanalytics.mobile/screen_summary/jsonschema/1-0-0

Tracker compatibility

Web: ❌Mobile: ✅Tracked automatically: ✅

Example

{
  "foreground_sec": 10.2,
  "background_sec": 3.1,
  "last_item_index": 11,
  "items_count": 50,
  "min_x_offset": 0,
  "max_x_offset": 400,
  "min_y_offset": 0,
  "max_y_offset": 1000,
  "content_width": 400,
  "content_height": 5000
}

Schema

Table
JSON schema

Property	Description
`foreground_sec` number	Required. Time in seconds spent on the current screen while the app was in foreground
`background_sec` number	Optional. Time in seconds spent on the current screen while the app was in background
`last_item_index` integer	Optional. Index of the last viewed item in the list on the screen
`items_count` integer	Optional. Total number of items in the list on the screen
`min_x_offset` integer	Optional. Minimum horizontal scroll offset on the scroll view in pixels
`max_x_offset` integer	Optional. Maximum horizontal scroll offset on the scroll view in pixels
`min_y_offset` integer	Optional. Minimum vertical scroll offset on the scroll view in pixels
`max_y_offset` integer	Optional. Maximum vertical scroll offset on the scroll view in pixels
`content_width` integer	Optional. Width of the scroll view in pixels
`content_height` integer	Optional. Height of the scroll view in pixels

{
  "description": "Schema for an entity tracked with foreground/background/screen_end events with summary statistics about the screen view",
  "properties": {
    "foreground_sec": {
      "type": "number",
      "description": "Time in seconds spent on the current screen while the app was in foreground",
      "minimum": 0,
      "maximum": 2147483647
    },
    "background_sec": {
      "type": [
        "number",
        "null"
      ],
      "description": "Time in seconds spent on the current screen while the app was in background",
      "minimum": 0,
      "maximum": 2147483647
    },
    "last_item_index": {
      "type": [
        "integer",
        "null"
      ],
      "description": "Index of the last viewed item in the list on the screen",
      "minimum": 0,
      "maximum": 65535
    },
    "items_count": {
      "type": [
        "integer",
        "null"
      ],
      "description": "Total number of items in the list on the screen",
      "minimum": 0,
      "maximum": 65535
    },
    "min_x_offset": {
      "type": [
        "integer",
        "null"
      ],
      "description": "Minimum horizontal scroll offset on the scroll view in pixels",
      "minimum": -2147483647,
      "maximum": 2147483647
    },
    "max_x_offset": {
      "type": [
        "integer",
        "null"
      ],
      "description": "Maximum horizontal scroll offset on the scroll view in pixels",
      "minimum": -2147483647,
      "maximum": 2147483647
    },
    "min_y_offset": {
      "type": [
        "integer",
        "null"
      ],
      "description": "Minimum vertical scroll offset on the scroll view in pixels",
      "minimum": -2147483647,
      "maximum": 2147483647
    },
    "max_y_offset": {
      "type": [
        "integer",
        "null"
      ],
      "description": "Maximum vertical scroll offset on the scroll view in pixels",
      "minimum": -2147483647,
      "maximum": 2147483647
    },
    "content_width": {
      "type": [
        "integer",
        "null"
      ],
      "description": "Width of the scroll view in pixels",
      "minimum": 0,
      "maximum": 2147483647
    },
    "content_height": {
      "type": [
        "integer",
        "null"
      ],
      "description": "Height of the scroll view in pixels",
      "minimum": 0,
      "maximum": 2147483647
    }
  },
  "additionalProperties": false,
  "type": "object",
  "required": [
    "foreground_sec"
  ],
  "self": {
    "vendor": "com.snowplowanalytics.mobile",
    "name": "screen_summary",
    "format": "jsonschema",
    "version": "1-0-0"
  },
  "$schema": "http://iglucentral.com/schemas/com.snowplowanalytics.self-desc/schema/jsonschema/1-0-0#"
}

Screen end event#

This event is tracked automatically by the mobile trackers just before the transition to the next screen.

The event has no properties.

screen_end

Event

Schema for an event tracked before transitioning to a new screen

Schema URIiglu:com.snowplowanalytics.mobile/screen_end/jsonschema/1-0-0

Tracker compatibility

Web: ❌Mobile: ✅Tracked automatically: ✅

Schema

Table
JSON schema

Property	Description

{
  "description": "Schema for an event tracked before transitioning to a new screen",
  "properties": {},
  "additionalProperties": false,
  "type": "object",
  "self": {
    "vendor": "com.snowplowanalytics.mobile",
    "name": "screen_end",
    "format": "jsonschema",
    "version": "1-0-0"
  },
  "$schema": "http://iglucentral.com/schemas/com.snowplowanalytics.self-desc/schema/jsonschema/1-0-0#"
}

Warehouse query

Snowflake
BigQuery
Databricks
Redshift & Postgres

select
unstruct_event_com_snowplowanalytics_mobile_screen_end_1 screen_end_1
from
atomic.events
where
events.collector_tstamp > getdate() - interval '1 hour'
and events.event = 'unstruct'
and events.event_name = 'screen_end'
and events.event_vendor = 'com.snowplowanalytics.mobile'

select
unstruct_event_com_snowplowanalytics_mobile_screen_end_1_0_0
from
PIPELINE_NAME.events events
where
events.collector_tstamp > timestamp_sub(current_timestamp(), interval 1 hour)
and events.event = 'unstruct'
and events.event_name = 'screen_end'
and events.event_vendor = 'com.snowplowanalytics.mobile'

select
unstruct_event_com_snowplowanalytics_mobile_screen_end_1
from
atomic.events events
where
events.collector_tstamp > timestampadd(HOUR, -1, current_timestamp())
and events.event = 'unstruct'
and events.event_name = 'screen_end'
and events.event_vendor = 'com.snowplowanalytics.mobile'
and unstruct_event_com_snowplowanalytics_mobile_screen_end_1 is not null

select
"screen_end_1".*
from
atomic.events events
join atomic.com_snowplowanalytics_mobile_screen_end_1 "screen_end_1"
  on "screen_end_1".root_id = events.event_id and "screen_end_1".root_tstamp = events.collector_tstamp
where
events.collector_tstamp > getdate() - interval '1 hour'
and "screen_end_1".root_tstamp > getdate() - interval '1 hour'
and events.event = 'unstruct'
and events.event_name = 'screen_end'
and events.event_vendor = 'com.snowplowanalytics.mobile'

How to track#

To track page activity on Web, see the activity tracking documentation.

To track screen engagement on mobile, see the screen engagement documentation.

Use in modeling#

Page and screen activity events are used by our Snowplow Unified Package (starting from version 0.2.0) to calculate page engagement metrics. The Snowplow Web Package can process page ping events.