Tracking Fields Reference
Complete reference of all data fields collected by the Pipetrace tracking script.
The Pipetrace tracking script sends page, device, and identifier data with events. Visitor identifiers persist in localStorage, a first-party cookie, and IndexedDB; session identifiers use sessionStorage.
Jump to Section
Identifiers
Identifiers for visitors and browser sessions
| Field | Type | Required | Description |
|---|---|---|---|
site_id | Your unique tracking ID from the data-site attribute | ||
visitor_id | Persistent visitor identifier stored in browser storage and sent with events | ||
session_id | Tab session ID; renewed after 30 minutes of inactivity, including SPA use |
Event Metadata
Core event information
| Field | Type | Required | Description |
|---|---|---|---|
event_contract_version | No | Current tracker sends 2; stored as event_data.contract_version | |
event_page_instance_id | No | Shared by one pageview, its interactions and its exit; stored in event_data.page_instance_id | |
event_type | Type of event (pageview, page_exit, custom, etc.) | ||
timestamp | When the event occurred |
Page Context
Information about the current page
| Field | Type | Required | Description |
|---|---|---|---|
url | No | Full page URL including query string | |
path | No | URL path (e.g., /pricing, /blog/post-1) | |
title | No | Document title from <title> tag |
Referrer Attribution
Traffic source information
| Field | Type | Required | Description |
|---|---|---|---|
referrer | No | Full referrer URL | |
referrer_source | No | Parsed source (google, facebook, chatgpt, etc.) | |
referrer_medium | No | Traffic medium (search, social, ai, referral, direct) |
Device Information
Visitor's device and browser details
| Field | Type | Required | Description |
|---|---|---|---|
device_type | No | desktop, mobile, or tablet | |
browser | No | Browser name (Chrome, Firefox, Safari, Edge, Opera) | |
browser_version | No | Major browser version number | |
os | No | Operating system (Windows, macOS, iOS, Android, Linux) | |
os_version | No | OS version number |
Screen & Viewport
Display dimensions and resolution
| Field | Type | Required | Description |
|---|---|---|---|
screen_width | No | Physical screen width in pixels | |
screen_height | No | Physical screen height in pixels | |
viewport_width | No | Browser viewport width in pixels | |
viewport_height | No | Browser viewport height in pixels |
Connection Quality
Network information (when available)
| Field | Type | Required | Description |
|---|---|---|---|
connection_type | No | 4g, 3g, 2g, or slow-2g |
Locale
Language and timezone
| Field | Type | Required | Description |
|---|---|---|---|
language | No | Browser language code (e.g., en-US, pt-BR) | |
timezone | No | IANA timezone (e.g., America/New_York) |
Session Context
Session and visitor flags
| Field | Type | Required | Description |
|---|---|---|---|
is_new_session | No | True for the first pageview of a session | |
is_new_visitor | No | True when the server recognizes a new persistent visitor identifier | |
entry_page | No | First page visited in this session | |
page_num | No | One-based page number for contract v2; legacy unversioned trackers started at 2 |
UTM Parameters
Campaign tracking parameters
| Field | Type | Required | Description |
|---|---|---|---|
utm_source | No | Traffic source (google, newsletter, etc.) | |
utm_medium | No | Marketing medium (cpc, email, social) | |
utm_campaign | No | Campaign name or ID | |
utm_content | No | Content variation (for A/B testing) | |
utm_term | No | Paid search keywords |
Engagement Metrics
Sent with page_exit events
| Field | Type | Required | Description |
|---|---|---|---|
time_on_page | No | Seconds spent on the page (active time only) | |
scroll_depth | No | Maximum scroll depth (0-100%) | |
engagement_score | No | Calculated engagement score (0-100) | |
is_bounce | No | True if visitor only viewed one page |
Core Web Vitals
Observed document metrics sent once in a web_vitals event; missing samples are omitted
| Field | Type | Required | Description |
|---|---|---|---|
web_vitals_lcp | No | Largest Contentful Paint in ms | |
web_vitals_fid | No | First Input Delay in ms (legacy) | |
web_vitals_inp | No | Interaction to Next Paint in ms | |
web_vitals_cls | No | Cumulative Layout Shift score (zero is valid when supported) | |
web_vitals_fcp | No | First Contentful Paint in ms | |
web_vitals_ttfb | No | Time to First Byte in ms |
Engagement Score Calculation
The engagement score (0-100) is calculated from multiple factors:
| Factor | Max Points | Formula |
|---|---|---|
| Time on Page | 30 | min(30, seconds / 2) |
| Scroll Depth | 30 | depth × 0.3 |
| Click Count | 20 | min(20, clicks × 4) |
| Interactions | 20 | min(20, interactions × 2) |
Web Vitals Thresholds
Google's recommended thresholds for Core Web Vitals:
| Metric | Good | Needs Improvement | Poor |
|---|---|---|---|
| LCP | ≤ 2.5s | ≤ 4.0s | > 4.0s |
| INP | ≤ 200ms | ≤ 500ms | > 500ms |
| CLS | ≤ 0.1 | ≤ 0.25 | > 0.25 |
| FCP | ≤ 1.8s | ≤ 3.0s | > 3.0s |
| TTFB | ≤ 800ms | ≤ 1.8s | > 1.8s |