Fullstory Page Properties API
Implementation Files: This document covers core concepts. For code examples, see:
Overview
Fullstory's Page Properties API allows developers to capture contextual information about the current page or screen that enriches sessions for search, filtering, segmentation, and journey analysis. Unlike user properties that persist across sessions, page properties are session-scoped and reset when the URL/screen changes.
Key use cases:
- Page/Screen Naming: Define semantic names that enrich ALL events on that page across Fullstory
- Search Context: Capture search terms and filters on results pages
- Checkout State: Track cart value, step number, coupon codes
- Content Context: Capture article categories, author, publish date
- Dynamic State: Record filters, sort orders, view modes
Core Concepts
Page Property Lifecycle
Page/Screen Load → setProperties(page) → Properties Active → Navigation → Properties Reset
↓ ↓
Same page, call again Merged with existing props
Key Behaviors
| Behavior |
Description |
| Session-scoped |
Properties persist for the current page until navigation |
| Merge on repeat calls |
Multiple calls on same page merge properties |
| Reset on navigation |
Properties clear when URL/screen changes |
| pageName special field |
Creates named Pages for use across Fullstory |
Page Properties vs Other Property Types
| Type |
Scope |
Persists |
Best For |
| User Properties |
User |
Across sessions |
User attributes, plan, role |
| Page Properties |
Page/Screen |
Until navigation |
Page context, search, filters |
| Element Properties |
Element |
Interaction |
Click-level context |
| Event Properties |
Event |
One event |
Action-specific data |
⚠️ Critical: The 1,000 pageName Limit
Fullstory limits you to 1,000 unique pageName values. Once exceeded, additional page names are silently ignored.
The Strategy: Use a generic page name + properties for variations.
❌ BAD: Unique pageName for every product
pageName: "iPhone 15 Pro Max 256GB Space Black"
pageName: "iPhone 15 Pro Max 512GB Natural Titanium"
pageName: "Samsung Galaxy S24 Ultra 256GB..."
→ Exhausts 1,000 limit quickly!
✅ GOOD: Generic pageName + properties for context
pageName: "Product Detail"
+ productName: "iPhone 15 Pro Max"
+ productCategory: "Smartphones"
+ productBrand: "Apple"
+ productPrice: 1199
| Scenario |
❌ Wrong (unique pageName) |
✅ Right (generic + properties) |
| Product pages |
"iPhone 15 Pro Detail" |
pageName: "Product Detail" + productName property |
| User profiles |
"John Smith's Profile" |
pageName: "User Profile" + profileUserId property |
| Article pages |
"How to Cook Pasta" |
pageName: "Article" + articleTitle, articleCategory properties |
| Search results |
"Search: blue shoes" |
pageName: "Search Results" + searchTerm property |
| Category pages |
"Men's Running Shoes" |
pageName: "Category" + categoryName, categoryPath properties |
Think of it this way: pageName defines the type of page (e.g., "Product Detail", "Checkout", "Search Results"). Properties describe the specific instance (which product, what search term, etc.). This gives you unlimited variation tracking while staying well under the 1,000 limit.
Why pageName Matters Across Fullstory
pageName and page properties aren't just for Journeys — they enrich every event that occurs on that page:
| Fullstory Feature |
How Page Properties Help |
| Search |
Find sessions where pageName = "Checkout" AND cartValue > 500 |
| Segments |
Create segments like "Users who visited Product pages with priceRange = 'premium'" |
| Funnels |
Build funnels using pageName steps: "Home → Category → Product Detail → Cart → Checkout" |
| Journeys |
Map user flows across named pages |
| Metrics |
Track conversion rates per page type, filter by page properties |
| Dashboards |
Break down metrics by pageName or page properties |
| Event Analysis |
Every click, rage click, error on a page carries the page context |
Special Fields
| Field |
Behavior |
pageName |
Creates a named Page used across all of Fullstory. Limited to 1,000 unique values. Takes precedence over URL-based page definitions. |
Rate Limits
| Type |
Limit |
| Sustained |
30 calls per page per minute |
| Burst |
10 calls per second |
Property Limits
| Limit |
Value |
| Properties per page |
50 unique properties (exclusive of pageName) |
| Properties across all pages |
500 unique properties |
| Unique pageName values |
1,000 site-wide |
Best Practices
1. pageName Strategy
- Set pageName first: Include pageName on the initial setProperties call
- Use generic names: Aim for 10-50 unique pageNames, not thousands
- Don't change pageName: Once set on a page, subsequent pageName values are ignored
- Store variations in properties: Product names, article titles, user IDs go in properties
2. Property Categories
Recommended property categories by page type:
| Page Type |
Recommended Properties |
| Search Results |
searchTerm, resultsCount, activeFilters, sortBy |
| Product Detail |
productId, productName, category, price, inStock |
| Checkout |
checkoutStep, cartValue, itemCount, hasCoupon |
| Article/Content |
articleId, category, author, publishDate, readTime |
| Dashboard |
activeView, dateRange, selectedFilters |
3. Navigation Handling
- Web SPAs: Re-set page properties on every route change
- Mobile: Set properties on each screen appearance
- Properties reset automatically: On URL/screen change, start fresh
4. Events + Page Properties
All events on a page inherit its context:
Page: Product Detail (productId: SKU-123, price: 99.99)
↓
Event: "Add to Cart" ← automatically searchable by page context
Event: "Image Zoomed" ← knows which product
Error Event ← tied to specific product page
Page Properties vs Events
| Scenario |
Use Page Property |
Use Event |
| User is viewing product SKU-123 |
✅ productId: "SKU-123" |
❌ |
| User clicked "Add to Cart" |
❌ |
✅ Product Added |
| Search results show 50 items |
✅ resultsCount: 50 |
❌ |
| User applied a filter |
✅ Update activeFilters |
✅ Filter Applied event |
| User is on checkout step 2 |
✅ checkoutStep: 2 |
❌ |
| User completed checkout |
❌ |
✅ Order Completed |
Rule of thumb: Page properties describe state that persists while on the page. Events capture moments in time.
Troubleshooting
pageName Not Showing in Journeys
| Cause |
Solution |
| pageName never set |
Always include pageName in initial call |
| Exceeded 1,000 limit |
Use generic names, check count in Fullstory |
| Trying to change pageName |
Once set, subsequent values are ignored |
Properties Not Persisting
| Cause |
Solution |
| Navigation occurred |
Re-set properties after each navigation |
| Wrong type parameter |
Verify type: 'page' (web) |
| Page refreshed |
Properties reset on refresh |
SPA/Screen Navigation Not Tracked
| Cause |
Solution |
| Not calling on navigation |
Listen for route/screen changes |
| Only setting on initial load |
Hook into router events |
| Route change not detected |
Use platform-specific navigation listeners |
Key Takeaways for Agent
When helping developers implement Page Properties:
Always emphasize:
- Include pageName — it enriches ALL events on that page
- Use generic pageName values (max 1,000) + properties for variations
- Re-set properties on every navigation (SPA/mobile)
- Page properties enable filtering across Search, Segments, Funnels, Metrics, and Dashboards
Common mistakes to watch for:
- Missing pageName property
- Dynamic pageName values (product names, user names)
- Changing pageName on same page (subsequent calls ignored)
- User data in page properties (should be user properties)
- Not handling navigation in SPAs/mobile apps
Questions to ask developers:
- Is this a SPA or traditional page navigation?
- What page/screen types do you have?
- What context is relevant to each page type?
- Do you need this data in Journeys/Funnels?
Platform routing:
- Web (JavaScript/TypeScript) → See SKILL-WEB.md
- iOS (Swift/SwiftUI) → See SKILL-MOBILE.md § iOS
- Android (Kotlin) → See SKILL-MOBILE.md § Android
- Flutter (Dart) → See SKILL-MOBILE.md § Flutter
- React Native → See SKILL-MOBILE.md § React Native
Reference Links
1---2name: fullstory-page-properties3description: Core concepts for Fullstory's Page Properties API (setProperties with type 'page'). Platform-agnostic guide covering page naming, session-scoped properties, the 1,000 pageName limit, and best practices. See SKILL-WEB.md and SKILL-MOBILE.md for implementation examples.4---56# Fullstory Page Properties API78> **Implementation Files**: This document covers core concepts. For code examples, see:9> - [SKILL-WEB.md](./SKILL-WEB.md) — JavaScript/TypeScript (Browser)10> - [SKILL-MOBILE.md](./SKILL-MOBILE.md) — iOS, Android, Flutter, React Native1112## Overview1314Fullstory's Page Properties API allows developers to capture contextual information about the current page or screen that enriches sessions for search, filtering, segmentation, and journey analysis. Unlike user properties that persist across sessions, page properties are session-scoped and reset when the URL/screen changes.1516Key use cases:17- **Page/Screen Naming**: Define semantic names that enrich ALL events on that page across Fullstory18- **Search Context**: Capture search terms and filters on results pages19- **Checkout State**: Track cart value, step number, coupon codes20- **Content Context**: Capture article categories, author, publish date21- **Dynamic State**: Record filters, sort orders, view modes2223---2425## Core Concepts2627### Page Property Lifecycle2829```30Page/Screen Load → setProperties(page) → Properties Active → Navigation → Properties Reset31 ↓ ↓32 Same page, call again Merged with existing props33```3435### Key Behaviors3637| Behavior | Description |38|----------|-------------|39| **Session-scoped** | Properties persist for the current page until navigation |40| **Merge on repeat calls** | Multiple calls on same page merge properties |41| **Reset on navigation** | Properties clear when URL/screen changes |42| **pageName special field** | Creates named Pages for use across Fullstory |4344### Page Properties vs Other Property Types4546| Type | Scope | Persists | Best For |47|------|-------|----------|----------|48| User Properties | User | Across sessions | User attributes, plan, role |49| Page Properties | Page/Screen | Until navigation | Page context, search, filters |50| Element Properties | Element | Interaction | Click-level context |51| Event Properties | Event | One event | Action-specific data |5253---5455## ⚠️ Critical: The 1,000 pageName Limit5657Fullstory limits you to **1,000 unique `pageName` values**. Once exceeded, additional page names are silently ignored.5859**The Strategy**: Use a **generic page name** + **properties for variations**.6061```62❌ BAD: Unique pageName for every product63 pageName: "iPhone 15 Pro Max 256GB Space Black"64 pageName: "iPhone 15 Pro Max 512GB Natural Titanium"65 pageName: "Samsung Galaxy S24 Ultra 256GB..."66 → Exhausts 1,000 limit quickly!6768✅ GOOD: Generic pageName + properties for context69 pageName: "Product Detail"70 + productName: "iPhone 15 Pro Max"71 + productCategory: "Smartphones"72 + productBrand: "Apple"73 + productPrice: 119974```7576| Scenario | ❌ Wrong (unique pageName) | ✅ Right (generic + properties) |77|----------|---------------------------|--------------------------------|78| Product pages | `"iPhone 15 Pro Detail"` | `pageName: "Product Detail"` + `productName` property |79| User profiles | `"John Smith's Profile"` | `pageName: "User Profile"` + `profileUserId` property |80| Article pages | `"How to Cook Pasta"` | `pageName: "Article"` + `articleTitle`, `articleCategory` properties |81| Search results | `"Search: blue shoes"` | `pageName: "Search Results"` + `searchTerm` property |82| Category pages | `"Men's Running Shoes"` | `pageName: "Category"` + `categoryName`, `categoryPath` properties |8384> **Think of it this way**: `pageName` defines the **type** of page (e.g., "Product Detail", "Checkout", "Search Results"). Properties describe the **specific instance** (which product, what search term, etc.). This gives you unlimited variation tracking while staying well under the 1,000 limit.8586---8788## Why pageName Matters Across Fullstory8990`pageName` and page properties aren't just for Journeys — they enrich **every event** that occurs on that page:9192| Fullstory Feature | How Page Properties Help |93|-------------------|-------------------------|94| **Search** | Find sessions where `pageName = "Checkout"` AND `cartValue > 500` |95| **Segments** | Create segments like "Users who visited Product pages with priceRange = 'premium'" |96| **Funnels** | Build funnels using pageName steps: "Home → Category → Product Detail → Cart → Checkout" |97| **Journeys** | Map user flows across named pages |98| **Metrics** | Track conversion rates per page type, filter by page properties |99| **Dashboards** | Break down metrics by pageName or page properties |100| **Event Analysis** | Every click, rage click, error on a page carries the page context |101102---103104## Special Fields105106| Field | Behavior |107|-------|----------|108| `pageName` | Creates a named Page used **across all of Fullstory**. Limited to 1,000 unique values. Takes precedence over URL-based page definitions. |109110---111112## Rate Limits113114| Type | Limit |115|------|-------|116| Sustained | 30 calls per page per minute |117| Burst | 10 calls per second |118119---120121## Property Limits122123| Limit | Value |124|-------|-------|125| Properties per page | 50 unique properties (exclusive of pageName) |126| Properties across all pages | 500 unique properties |127| Unique pageName values | 1,000 site-wide |128129---130131## Best Practices132133### 1. pageName Strategy134135- **Set pageName first**: Include pageName on the initial setProperties call136- **Use generic names**: Aim for 10-50 unique pageNames, not thousands137- **Don't change pageName**: Once set on a page, subsequent pageName values are ignored138- **Store variations in properties**: Product names, article titles, user IDs go in properties139140### 2. Property Categories141142Recommended property categories by page type:143144| Page Type | Recommended Properties |145|-----------|----------------------|146| Search Results | searchTerm, resultsCount, activeFilters, sortBy |147| Product Detail | productId, productName, category, price, inStock |148| Checkout | checkoutStep, cartValue, itemCount, hasCoupon |149| Article/Content | articleId, category, author, publishDate, readTime |150| Dashboard | activeView, dateRange, selectedFilters |151152### 3. Navigation Handling153154- **Web SPAs**: Re-set page properties on every route change155- **Mobile**: Set properties on each screen appearance156- **Properties reset automatically**: On URL/screen change, start fresh157158### 4. Events + Page Properties159160All events on a page inherit its context:161162```163Page: Product Detail (productId: SKU-123, price: 99.99)164 ↓165Event: "Add to Cart" ← automatically searchable by page context166Event: "Image Zoomed" ← knows which product167Error Event ← tied to specific product page168```169170---171172## Page Properties vs Events173174| Scenario | Use Page Property | Use Event |175|----------|-------------------|-----------|176| User is viewing product SKU-123 | ✅ `productId: "SKU-123"` | ❌ |177| User clicked "Add to Cart" | ❌ | ✅ `Product Added` |178| Search results show 50 items | ✅ `resultsCount: 50` | ❌ |179| User applied a filter | ✅ Update `activeFilters` | ✅ `Filter Applied` event |180| User is on checkout step 2 | ✅ `checkoutStep: 2` | ❌ |181| User completed checkout | ❌ | ✅ `Order Completed` |182183**Rule of thumb**: Page properties describe **state that persists while on the page**. Events capture **moments in time**.184185---186187## Troubleshooting188189### pageName Not Showing in Journeys190191| Cause | Solution |192|-------|----------|193| pageName never set | Always include pageName in initial call |194| Exceeded 1,000 limit | Use generic names, check count in Fullstory |195| Trying to change pageName | Once set, subsequent values are ignored |196197### Properties Not Persisting198199| Cause | Solution |200|-------|----------|201| Navigation occurred | Re-set properties after each navigation |202| Wrong type parameter | Verify `type: 'page'` (web) |203| Page refreshed | Properties reset on refresh |204205### SPA/Screen Navigation Not Tracked206207| Cause | Solution |208|-------|----------|209| Not calling on navigation | Listen for route/screen changes |210| Only setting on initial load | Hook into router events |211| Route change not detected | Use platform-specific navigation listeners |212213---214215## Key Takeaways for Agent216217When helping developers implement Page Properties:2182191. **Always emphasize**:220 - Include pageName — it enriches ALL events on that page221 - Use generic pageName values (max 1,000) + properties for variations222 - Re-set properties on every navigation (SPA/mobile)223 - Page properties enable filtering across Search, Segments, Funnels, Metrics, and Dashboards2242252. **Common mistakes to watch for**:226 - Missing pageName property227 - Dynamic pageName values (product names, user names)228 - Changing pageName on same page (subsequent calls ignored)229 - User data in page properties (should be user properties)230 - Not handling navigation in SPAs/mobile apps2312323. **Questions to ask developers**:233 - Is this a SPA or traditional page navigation?234 - What page/screen types do you have?235 - What context is relevant to each page type?236 - Do you need this data in Journeys/Funnels?2372384. **Platform routing**:239 - Web (JavaScript/TypeScript) → See SKILL-WEB.md240 - iOS (Swift/SwiftUI) → See SKILL-MOBILE.md § iOS241 - Android (Kotlin) → See SKILL-MOBILE.md § Android242 - Flutter (Dart) → See SKILL-MOBILE.md § Flutter243 - React Native → See SKILL-MOBILE.md § React Native244245---246247## Reference Links248249- **Page Properties (Web)**: https://developer.fullstory.com/browser/set-page-properties/250- **Page Properties (iOS)**: https://developer.fullstory.com/mobile/ios/capture-data/set-page-properties/251- **Page Properties (Android)**: https://developer.fullstory.com/mobile/android/capture-data/set-page-properties/252- **Page Properties (Flutter)**: https://developer.fullstory.com/mobile/flutter/capture-data/set-page-properties/253- **Page Properties (React Native)**: https://developer.fullstory.com/mobile/react-native/capture-data/set-page-properties/254- **Custom Properties**: https://developer.fullstory.com/browser/custom-properties/255- **Help Center - Page Properties**: https://help.fullstory.com/hc/en-us/articles/360020623454
fullstorydev