Fullstory User Properties API

Implementation Files: This document covers core concepts. For code examples, see:

• SKILL-WEB.md — JavaScript/TypeScript (Browser)
• SKILL-MOBILE.md — iOS, Android, Flutter, React Native

Overview

Fullstory's User Properties API allows developers to capture custom user data that enriches user profiles for search, filtering, segmentation, and analytics. Unlike setIdentity which links a session to a known user ID, user properties let you add or update attributes about any user — including anonymous users.

Important: Every new browser/device starts as an anonymous user. You can set user properties on anonymous users before they ever identify. These properties persist across sessions and transfer when/if the user later identifies.

Key use cases:

• Anonymous User Enrichment: Add attributes before the user logs in (referral source, landing page, visitor type)
• Progressive Profiling: Update properties as you learn more about the user
• Subscription/Plan Changes: Track plan upgrades without re-identifying
• Preference Tracking: Store user settings and preferences
• CRM Sync: Mirror key CRM fields in Fullstory

Core Concepts

setIdentity vs setProperties (User)

Key Distinction: Use setIdentity when you need to link a session to a known user (requires a uid). Use user properties when you just want to add or update attributes about the current user — this works for both identified AND anonymous users.

Anonymous Users

Every user starts as anonymous, tracked via platform-specific mechanisms:

• Web: fs_uid first-party cookie (1-year expiry)
• Mobile: Device-based identifier persisted in app storage

Key behaviors:

• Persistent across sessions: As long as the identifier exists, all sessions are linked to the same anonymous user
• Can receive user properties: Add attributes to anonymous users before identification
• Properties transfer on identification: When identity is set, ALL previous sessions merge into the identified user
• Searchable and segmentable: Anonymous users work just like identified users in Fullstory

When to Use Each

User logs in → setIdentity({ uid: "user_123", properties: { displayName: "Jane" } })
                ↓
User updates profile → setProperties (user) { plan: "pro" }
                ↓
User upgrades plan → setProperties (user) { plan: "enterprise" }

For anonymous users (not yet logged in):

• Use user properties to capture attributes like visitor type, referral source, landing page
• These properties persist and transfer when/if they later identify

Property Persistence

• User properties persist across sessions
• Properties can be updated at any time
• New properties are added; existing properties are overwritten
• Properties cannot be deleted via the API (contact support)

Special Fields

Supported Property Types

Rate Limits

Property Naming Conventions

Best Practices

1. Property Design

• Set core properties in setIdentity: displayName, email, and other stable attributes
• Use setProperties for updates: Don't re-identify just to update properties
• Include business-relevant data: plan, role, company, feature access
• Use explicit types: Specify schema for non-string values

2. Batching Updates

• Batch rapid updates: If updating multiple properties quickly, combine into one call
• Consider debouncing: For frequently changing data, debounce updates
• Watch rate limits: 30 calls/minute sustained, 10 calls/second burst

3. Property Categories

Recommended property categories for comprehensive user profiles:

4. Events + Properties

Track both the change (event) and the new state (property):

User upgrades plan:
  1. Event: "Plan Upgraded" with from_plan, to_plan, price_change
  2. Property: plan = "enterprise", planChangedAt = now

Relationship with Other APIs

setIdentity + setProperties Workflow

1. setIdentity: Called on login with core properties (displayName, email)
2. setProperties (user): Called later to add/update attributes without re-identifying

setProperties (user) vs setProperties (page)

setProperties vs trackEvent

Troubleshooting

Properties Not Appearing

Properties Show Wrong Values

displayName Keeps Getting Overwritten

Limits and Constraints

Property Limits

• Check your Fullstory plan for specific limits
• Property names: alphanumeric, underscores, hyphens
• Avoid high-cardinality properties (unique values for every user)

Value Requirements

• Strings: Must be valid UTF-8
• Numbers: Standard JSON number format
• Dates: ISO8601 format
• Arrays: Maximum length varies by plan

Key Takeaways for Agent

When helping developers implement User Properties:

1. Always emphasize:
   • Include type: 'user' (web) or use the user properties method
   • Use schema for non-string types
   • Batch updates to respect rate limits
   • displayName and email have special behavior in UI
2. Common mistakes to watch for:
   • Missing type parameter (web)
   • Excessive call frequency
   • Type mismatches in values
   • Overwriting displayName accidentally
   • Using setProperties instead of setIdentity for initial identification
3. Questions to ask developers:
   • Will the user be anonymous or identified?
   • How often will these properties be updated?
   • What data types are these values?
   • Do you need to track the change as an event too?
4. 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

• User Properties (Web): https://developer.fullstory.com/browser/identification/set-user-properties/
• User Properties (iOS): https://developer.fullstory.com/mobile/ios/identification/set-user-properties/
• User Properties (Android): https://developer.fullstory.com/mobile/android/identification/set-user-properties/
• User Properties (Flutter): https://developer.fullstory.com/mobile/flutter/identification/set-user-properties/
• User Properties (React Native): https://developer.fullstory.com/mobile/react-native/identification/set-user-properties/
• Custom Properties: https://developer.fullstory.com/browser/custom-properties/
• Help Center - Custom Properties: https://help.fullstory.com/hc/en-us/articles/360020623234