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
`pp_xoffset_min`	integer	Minimum page x offset seen in the last ping period
`pp_xoffset_max`	integer	Maximum page x offset seen in the last ping period
`pp_yoffset_min`	integer	Minimum page y offset seen in the last ping period
`pp_yoffset_max`	integer	Maximum page y offset seen in the last ping period

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.

On Web using page ping events​

On mobile​

Screen summary entity​

screen_summary

Screen end event​