# Page and screen engagement
> Measure user engagement time and scrolling depth using page ping events on web and screen summary entities on mobile.
> Source: https://docs.snowplow.io/docs/events/ootb-data/page-activity-tracking/
> Documentation index: https://docs.snowplow.io/llms.txt

Activity or engagement tracking enables you to measure the time a user spent engaged on a page or screen, and the extent of the page or screen they viewed.

Snowplow provides implementations for web and mobile platforms:

- Page ping events on web
- Screen summary entity on mobile

Both page and screen activity tracking are included in the [Snowplow Unified Digital package](/docs/modeling-your-data/modeling-your-data-with-dbt/dbt-models/dbt-unified-data-model/) to calculate engagement metrics. The legacy [Web package](/docs/modeling-your-data/modeling-your-data-with-dbt/dbt-models/legacy/dbt-web-data-model/) handles page pings as well.

## Page engagement

Page ping events record users engaging with content on a web page after it has initially loaded. This includes scroll position.

Where activity autotracking is available, you can configure your tracker to send page ping events at regular intervals. They're considered a type of "heartbeat" event that indicates the user is still present and engaging with the page.

Page ping events are [baked-in events](/docs/fundamentals/events/) that have no schema. They populate the [page offset atomic event parameters](/docs/fundamentals/canonical-event/#baked-in-event-fields).

This table shows the support for page ping tracking across the main client-side [Snowplow tracker SDKs](/docs/sources/). Python is the only server-side tracker that provides page ping events.

| Tracker                                                                    | Supported | Since version | Auto-tracking | Notes                              |
| -------------------------------------------------------------------------- | --------- | ------------- | ------------- | ---------------------------------- |
| [Web](/docs/sources/web-trackers/tracking-events/activity-page-pings/)     | ✅         | 0.10.0        | ✅             |                                    |
| iOS                                                                        | ❌         |               |               |                                    |
| Android                                                                    | ❌         |               |               |                                    |
| React Native                                                               | ❌         |               |               |                                    |
| [Flutter](/docs/sources/flutter-tracker/initialization-and-configuration/) | ✅         | 0.1.0         | ✅             | Only on web                        |
| Roku                                                                       | ❌         |               |               |                                    |
| [Python](/docs/sources/python-tracker/tracking-specific-events/)           | ✅         | 0.8.0         | ❌             | Detect activity and track manually |
| [Google Tag Manager](/docs/sources/google-tag-manager/snowplow-template/)  | ✅         | v3            | ✅             |                                    |

We recommend using the [Base web tracking plan template](/docs/event-studio/tracking-plans/templates/#base-web) for web tracking. It includes page pings.

### Activity metrics entity

Since JavaScript tracker version 4.8.0, you can also attach [detailed activity metrics](/docs/sources/web-trackers/tracking-events/activity-page-pings/#activity-metrics) to each page ping. The detailed metrics show how much interaction happened on the page, including the number of clicks, touches, key presses, absolute scroll distance (in either direction), and distance traveled by the mouse.

> **Tip: Agentic browsers**
>
> This can be helpful, for example, for distinguishing human and agent actions in an agentic browser session. Agents typically produce very little activity, navigating to pages directly and not clicking on links.

### `activity_metrics`

**Type:** Schema

Quantitative user interaction metrics accumulated between page pings

**Properties:**

| Property                   | Description                                                                 |
| -------------------------- | --------------------------------------------------------------------------- |
| `mouseDistance` _integer_  | _Required._ Cumulative Euclidean mouse distance in pixels                   |
| `scrollDistance` _integer_ | _Required._ Cumulative absolute scroll distance in pixels (both directions) |
| `keyPresses` _integer_     | _Required._ Number of key presses                                           |
| `clicks` _integer_         | _Required._ Number of clicks                                                |
| `touches` _integer_        | _Required._ Number of touch events                                          |

## Screen engagement

Use screen engagement tracking to track a `screen_end` event when a user navigates away from a screen.

The trackers can also track a `screen_summary` entity that contains screen engagement data. This entity is sent along with [lifecycle](/docs/events/ootb-data/mobile-lifecycle-events/) and `screen_end` events.

This table shows the support for screen engagement tracking across the main client-side [Snowplow tracker SDKs](/docs/sources/). The server-side trackers don't include screen engagement tracking.

| Tracker                                                                                                        | Supported | Since version | Auto-tracking | Notes                           |
| -------------------------------------------------------------------------------------------------------------- | --------- | ------------- | ------------- | ------------------------------- |
| [Web](/docs/sources/web-trackers/tracking-events/screen-views/#screen-engagement-tracking)                     | ✅         | 4.2.0         | ✅/❌           | Requires screen tracking plugin |
| [iOS](/docs/sources/mobile-trackers/tracking-events/screen-tracking/#screen-engagement-tracking)               | ✅         | 6.0.0         | ✅             |                                 |
| [Android](/docs/sources/mobile-trackers/tracking-events/screen-tracking/#screen-engagement-tracking)           | ✅         | 6.0.0         | ✅             |                                 |
| [React Native](/docs/sources/react-native-tracker/tracking-events/screen-tracking/#screen-engagement-tracking) | ✅         | 2.1.0         | ✅             | Only on mobile                  |
| [Flutter](/docs/sources/flutter-tracker/tracking-events/#screen-engagement-tracking)                           | ✅         | 0.1.0         | ✅             | Only on mobile                  |
| Roku                                                                                                           | ❌         |               |               |                                 |
| Google Tag Manager                                                                                             | ❌         |               |               |                                 |

We recommend using the [Base mobile tracking plan template](/docs/event-studio/tracking-plans/templates/#base-mobile) for mobile tracking. It includes screen end events.

### Screen end event

This event can be tracked automatically just before the transition to the next screen, based on the firing of the next screen view event. It has no properties.

### `screen_end`

**Type:** Event

Schema for an event tracked before transitioning to a new screen

**Properties:**

**Example warehouse query (Snowflake):**

```sql
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'
```

### List item view event

Track this event to mark which items are visible in a list. When screen engagement tracking is enabled, this event won't be sent to the Collector but used to update the tracker state for the screen summary entity.

If you're using the iOS tracker with SwiftUI, you can configure it to [automatically track this event](/docs/sources/mobile-trackers/tracking-events/screen-tracking/#list-item-view-tracking).

### `list_item_view`

**Type:** Event

Schema for an event tracked when an item is displayed in a list

**Properties:**

| Property                | Description                                               |
| ----------------------- | --------------------------------------------------------- |
| `index` _integer_       | _Required._ Index of the item in a list on the screen     |
| `items_count` _integer_ | _Optional._ Total number of items in a list on the screen |

**Example warehouse query (Snowflake):**

```sql
select
unstruct_event_com_snowplowanalytics_mobile_list_item_view_1 list_item_view_1
from
atomic.events
where
events.collector_tstamp > getdate() - interval '1 hour'
and events.event = 'unstruct'
and events.event_name = 'list_item_view'
and events.event_vendor = 'com.snowplowanalytics.mobile'
```

### Scroll changed event

Track this event to mark changes in scroll position on a screen. When screen engagement tracking is enabled, this event won't be sent to the Collector but used to update the tracker state for the screen summary entity.

### `scroll_changed`

**Type:** Event

Schema for an event tracked when a scroll view's scroll position changes

**Properties:**

| Property                   | Description                                                        |
| -------------------------- | ------------------------------------------------------------------ |
| `x_offset` _integer_       | _Optional._ Horizontal scroll offset in pixels                     |
| `y_offset` _integer_       | _Optional._ Vertical scroll offset in pixels                       |
| `view_width` _integer_     | _Optional._ The width of the scroll view in pixels                 |
| `view_height` _integer_    | _Optional._ The height of the scroll view in pixels                |
| `content_width` _integer_  | _Optional._ The width of the content in the scroll view in pixels  |
| `content_height` _integer_ | _Optional._ The height of the content in the scroll view in pixels |

**Example warehouse query (Snowflake):**

```sql
select
unstruct_event_com_snowplowanalytics_mobile_scroll_changed_1 scroll_changed_1
from
atomic.events
where
events.collector_tstamp > getdate() - interval '1 hour'
and events.event = 'unstruct'
and events.event_name = 'scroll_changed'
and events.event_vendor = 'com.snowplowanalytics.mobile'
```

### Screen summary entity

Entity that contains screen engagement information, including how long a user spends on a screen in the foreground and background, as well as information about scroll depth and list items.

The entity data is based on tracker state captured from lifecycle, list item view, and scroll changed events.

### `screen_summary`

**Type:** Schema

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

**Properties:**

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