Skill 077

Fullstory User Properties API

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, setProperties with type: 'user' lets you add or update attributes about any user - including anonymous users.

Important: Every new browser/device starts as an anonymous user, tracked via the fs_uid first-party cookie (1-year expiry). 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 via setIdentity.

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

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

Anonymous Users in Fullstory

Every user starts as anonymous, tracked via the fs_uid first-party cookie:

• Cookie-based identity: Fullstory sets an fs_uid cookie (1-year expiry) that tracks the same anonymous user across sessions and page views
• Persistent across sessions: As long as the cookie exists, all sessions are linked to the same anonymous user
• Can receive user properties: Use setProperties to add attributes to anonymous users
• Properties transfer on identification: When setIdentity is called, ALL previous sessions (linked by the cookie) merge into the identified user
• Searchable and segmentable: Anonymous users work just like identified users in Fullstory

Reference: Why Fullstory uses First-Party Cookies

// User lands on your site (anonymous - "User 4521" in Fullstory)
FS('setProperties', {
  type: 'user',
  properties: {
    landing_page: '/pricing',
    referral_source: 'google_ads',
    campaign: 'spring_sale_2024',
  },
})

// ... user browses for a while ...

// Later, user creates an account and logs in
FS('setIdentity', {
  uid: 'user_abc123',
  properties: {
    displayName: 'Jane Smith',
    email: 'jane@example.com',
  },
})
// The anonymous properties (landing_page, referral_source, campaign)
// are now attached to the identified user "Jane Smith"

When to Use Each

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

For anonymous users (not yet logged in):

// User hasn't logged in yet, but we know something about them
FS('setProperties', {
  type: 'user',
  properties: {
    visitor_type: 'returning',
    referral_source: 'google_ads',
    landing_page: '/pricing',
  },
})
// These properties will be associated with the anonymous user
// and will persist if/when 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

API Reference

Basic Syntax

FS('setProperties', {
  type: 'user',
  properties: object,     // Required: Key/value pairs
  schema?: object         // Optional: Type hints
});

Parameters

Supported Property Types

Rate Limits

• Sustained: 30 calls per page per minute
• Burst: 10 calls per second

✅ GOOD IMPLEMENTATION EXAMPLES

Example 1: Post-Identification Profile Enrichment

// GOOD: Add properties after initial identification
// Step 1: Identify user on login (minimal properties)
FS('setIdentity', {
  uid: user.id,
  properties: {
    displayName: user.name,
    email: user.email,
  },
})

// Step 2: Enrich with additional data once loaded
async function loadUserProfile() {
  const profile = await fetchUserProfile(user.id)

  FS('setProperties', {
    type: 'user',
    properties: {
      companyName: profile.company.name,
      companySize: profile.company.employeeCount,
      industry: profile.company.industry,
      role: profile.role,
      department: profile.department,
      signupSource: profile.attribution.source,
      referralCode: profile.attribution.referralCode,
    },
  })
}

Why this is good:

• ✅ Quick identification on login (doesn't block on profile load)
• ✅ Rich data added once available
• ✅ Clean separation of concerns
• ✅ Properties available for segmentation

Example 2: Subscription/Plan Updates

// GOOD: Track subscription changes without re-identifying
async function handlePlanUpgrade(newPlan) {
  // Process the upgrade
  await processUpgrade(newPlan)

  // Update user properties to reflect new plan
  FS('setProperties', {
    type: 'user',
    properties: {
      plan: newPlan.name,
      planTier: newPlan.tier,
      monthlyPrice: newPlan.price,
      billingCycle: newPlan.billingCycle,
      planChangedAt: new Date().toISOString(),
      previousPlan: getCurrentPlan().name,
    },
    schema: {
      monthlyPrice: 'real',
      planChangedAt: 'date',
    },
  })

  // Also track as an event for funnel analysis
  FS('trackEvent', {
    name: 'Plan Upgraded',
    properties: {
      fromPlan: getCurrentPlan().name,
      toPlan: newPlan.name,
      priceDifference: newPlan.price - getCurrentPlan().price,
    },
  })
}

Why this is good:

• ✅ Updates user properties without re-identification
• ✅ Tracks both current state (property) and change (event)
• ✅ Uses schema for proper type handling
• ✅ Captures before/after for analysis

Example 3: Progressive Profiling (Onboarding)

// GOOD: Build up user profile through onboarding steps
class OnboardingFlow {
  // Step 1: Basic info collected
  completeBasicInfo(data) {
    FS('setProperties', {
      type: 'user',
      properties: {
        companyName: data.companyName,
        companySize: data.companySize,
        onboardingStep: 1,
        onboardingStartedAt: new Date().toISOString(),
      },
      schema: {
        onboardingStep: 'int',
        onboardingStartedAt: 'date',
      },
    })
  }

  // Step 2: Use case selection
  completeUseCaseSelection(useCases) {
    FS('setProperties', {
      type: 'user',
      properties: {
        primaryUseCase: useCases.primary,
        secondaryUseCases: useCases.secondary, // Array of strings
        onboardingStep: 2,
      },
      schema: {
        secondaryUseCases: 'strs',
        onboardingStep: 'int',
      },
    })
  }

  // Step 3: Integration setup
  completeIntegrationSetup(integrations) {
    FS('setProperties', {
      type: 'user',
      properties: {
        connectedIntegrations: integrations.connected,
        integrationCount: integrations.connected.length,
        onboardingStep: 3,
      },
      schema: {
        connectedIntegrations: 'strs',
        integrationCount: 'int',
        onboardingStep: 'int',
      },
    })
  }

  // Final step: Mark complete
  completeOnboarding() {
    FS('setProperties', {
      type: 'user',
      properties: {
        onboardingComplete: true,
        onboardingCompletedAt: new Date().toISOString(),
        onboardingStep: 4,
      },
      schema: {
        onboardingComplete: 'bool',
        onboardingCompletedAt: 'date',
        onboardingStep: 'int',
      },
    })
  }
}

Why this is good:

• ✅ Builds profile incrementally
• ✅ Each step adds relevant properties
• ✅ Tracks progress via onboardingStep
• ✅ Enables segment analysis of drop-off points

Example 4: Feature Usage Tracking

// GOOD: Track feature adoption at user level
class FeatureUsageTracker {
  trackFeatureFirstUse(featureName) {
    const propertyName = `firstUsed_${featureName}`

    FS('setProperties', {
      type: 'user',
      properties: {
        [propertyName]: new Date().toISOString(),
      },
      schema: {
        [propertyName]: 'date',
      },
    })
  }

  updateFeatureEngagement(features) {
    FS('setProperties', {
      type: 'user',
      properties: {
        featuresUsed: features.used,
        mostUsedFeature: features.mostUsed,
        featureUsageScore: features.engagementScore,
        lastActiveFeature: features.lastUsed,
        lastFeatureUseAt: new Date().toISOString(),
      },
      schema: {
        featuresUsed: 'strs',
        featureUsageScore: 'int',
        lastFeatureUseAt: 'date',
      },
    })
  }
}

// Usage
const tracker = new FeatureUsageTracker()
tracker.trackFeatureFirstUse('advanced_export')
tracker.updateFeatureEngagement({
  used: ['dashboard', 'reports', 'advanced_export'],
  mostUsed: 'reports',
  engagementScore: 85,
  lastUsed: 'advanced_export',
})

Why this is good:

• ✅ Tracks feature adoption dates
• ✅ Maintains engagement metrics
• ✅ Enables feature-based segmentation
• ✅ Supports adoption analysis

Example 5: CRM Data Sync

// GOOD: Sync key CRM fields to Fullstory
async function syncCRMData(userId) {
  const crmData = await fetchFromCRM(userId)

  FS('setProperties', {
    type: 'user',
    properties: {
      // Sales/Account info
      accountOwner: crmData.owner.name,
      accountStage: crmData.stage,
      dealValue: crmData.opportunity.value,
      closeDate: crmData.opportunity.expectedClose,

      // Health metrics
      healthScore: crmData.health.score,
      churnRisk: crmData.health.churnRisk,
      npsScore: crmData.health.nps,

      // Engagement
      lastContactDate: crmData.lastContact,
      meetingsScheduled: crmData.meetings.scheduled,
      supportTicketsOpen: crmData.support.openTickets,

      // Sync metadata
      crmSyncedAt: new Date().toISOString(),
    },
    schema: {
      dealValue: 'real',
      closeDate: 'date',
      healthScore: 'int',
      churnRisk: 'real',
      npsScore: 'int',
      lastContactDate: 'date',
      meetingsScheduled: 'int',
      supportTicketsOpen: 'int',
      crmSyncedAt: 'date',
    },
  })
}

Why this is good:

• ✅ Bridges CRM and product analytics
• ✅ Enables sales context in session replay
• ✅ Supports health-based segmentation
• ✅ Tracks sync time for data freshness

❌ BAD IMPLEMENTATION EXAMPLES

Example 1: Using setProperties Instead of setIdentity

// BAD: Trying to use setProperties for initial identification
FS('setProperties', {
  type: 'user',
  properties: {
    uid: user.id, // This won't work!
    displayName: user.name,
    email: user.email,
  },
})

Why this is bad:

• ❌ setProperties doesn't establish identity
• ❌ uid as a property doesn't link sessions
• ❌ User remains anonymous
• ❌ Misunderstanding of API purpose

CORRECTED VERSION:

// GOOD: Use setIdentity for identification
FS('setIdentity', {
  uid: user.id,
  properties: {
    displayName: user.name,
    email: user.email,
  },
})

Example 2: Calling Before Identification

// BAD: Setting user properties before user is identified
function updateUserPreferences(preferences) {
  // This won't persist properly if user is anonymous!
  FS('setProperties', {
    type: 'user',
    properties: {
      theme: preferences.theme,
      language: preferences.language,
    },
  })
}

Why this is bad:

• ❌ Properties on anonymous users are session-scoped
• ❌ Data won't persist across sessions
• ❌ Can't segment by these properties reliably

CORRECTED VERSION:

// GOOD: Check identification status first
function updateUserPreferences(preferences) {
  // Only set user properties if identified
  if (isUserIdentified()) {
    FS('setProperties', {
      type: 'user',
      properties: {
        theme: preferences.theme,
        language: preferences.language,
      },
    })
  }
  // For anonymous users, consider page properties or just skip
}

Example 3: Excessive Calls

// BAD: Calling setProperties too frequently
function handleFormFieldChange(fieldName, value) {
  // BAD: This fires on every keystroke!
  FS('setProperties', {
    type: 'user',
    properties: {
      [`form_${fieldName}`]: value,
    },
  })
}

Why this is bad:

• ❌ Will hit rate limits (30/min, 10/sec)
• ❌ Wastes API calls on intermediate states
• ❌ Transient form data isn't good for user properties

CORRECTED VERSION:

// GOOD: Batch updates on form submission
function handleFormSubmit(formData) {
  // Set meaningful final values
  FS('setProperties', {
    type: 'user',
    properties: {
      preferredContact: formData.contactMethod,
      marketingOptIn: formData.optIn,
      timezone: formData.timezone,
    },
  })

  // Track the form submission as event
  FS('trackEvent', {
    name: 'Preferences Updated',
    properties: formData,
  })
}

Example 4: Wrong Type for Properties

// BAD: Missing type parameter
FS('setProperties', {
  properties: {
    plan: 'premium',
  },
  // Missing type: 'user'!
})

Why this is bad:

• ❌ Missing required type parameter
• ❌ API call will fail or behave unexpectedly
• ❌ Easy to miss in testing

CORRECTED VERSION:

// GOOD: Include type parameter
FS('setProperties', {
  type: 'user', // Required!
  properties: {
    plan: 'premium',
  },
})

Example 5: Type Mismatches

// BAD: Incorrect value formats
FS('setProperties', {
  type: 'user',
  properties: {
    accountBalance: '$1,234.56', // BAD: Formatted currency
    loginCount: 'forty-two', // BAD: Written number
    isPremium: 'yes', // BAD: String instead of boolean
    signupDate: 'January 15, 2024', // BAD: Not ISO8601
  },
  schema: {
    accountBalance: 'real',
    loginCount: 'int',
    isPremium: 'bool',
    signupDate: 'date',
  },
})

Why this is bad:

• ❌ Values don't match declared types
• ❌ Parsing will fail
• ❌ Properties won't be queryable correctly

CORRECTED VERSION:

// GOOD: Properly formatted values
FS('setProperties', {
  type: 'user',
  properties: {
    accountBalance: 1234.56,
    currency: 'USD', // Separate field for formatting
    loginCount: 42,
    isPremium: true,
    signupDate: '2024-01-15T00:00:00Z',
  },
  schema: {
    accountBalance: 'real',
    loginCount: 'int',
    isPremium: 'bool',
    signupDate: 'date',
  },
})

Example 6: Overwriting Important Properties

// BAD: Carelessly overwriting displayName
function updateLastActivity() {
  FS('setProperties', {
    type: 'user',
    properties: {
      displayName: 'Active User', // BAD: Overwrites the real name!
      lastActivityAt: new Date().toISOString(),
    },
  })
}

Why this is bad:

• ❌ Overwrites displayName with generic value
• ❌ Loses actual user name in Fullstory UI
• ❌ Makes sessions hard to identify

CORRECTED VERSION:

// GOOD: Only update intended properties
function updateLastActivity() {
  FS('setProperties', {
    type: 'user',
    properties: {
      lastActivityAt: new Date().toISOString(),
      isRecentlyActive: true,
    },
    schema: {
      lastActivityAt: 'date',
      isRecentlyActive: 'bool',
    },
  })
}

COMMON IMPLEMENTATION PATTERNS

Pattern 1: Property Manager Class

// Centralized user property management
class UserPropertyManager {
  constructor() {
    this.pendingProperties = {}
    this.flushTimeout = null
  }

  // Queue properties for batched update
  queue(properties, schema = {}) {
    Object.assign(this.pendingProperties, properties)

    // Debounce to batch rapid updates
    if (this.flushTimeout) clearTimeout(this.flushTimeout)
    this.flushTimeout = setTimeout(() => this.flush(), 1000)
  }

  // Immediately send properties
  flush() {
    if (Object.keys(this.pendingProperties).length === 0) return

    FS('setProperties', {
      type: 'user',
      properties: this.pendingProperties,
    })

    this.pendingProperties = {}
    this.flushTimeout = null
  }

  // Update specific category of properties
  updateEngagement(data) {
    this.queue({
      lastActiveAt: new Date().toISOString(),
      sessionCount: data.sessionCount,
      pageViewsTotal: data.pageViews,
    })
  }

  updateSubscription(plan) {
    // Subscription updates are important - flush immediately
    FS('setProperties', {
      type: 'user',
      properties: {
        plan: plan.name,
        planTier: plan.tier,
        planUpdatedAt: new Date().toISOString(),
      },
    })
  }
}

Pattern 2: Property Sync on Page Load

// Sync important properties on each page load
async function syncUserProperties() {
  const user = await getCurrentUser()
  if (!user) return

  // Fetch latest data
  const [profile, subscription, usage] = await Promise.all([
    fetchProfile(user.id),
    fetchSubscription(user.id),
    fetchUsageStats(user.id),
  ])

  // Sync to Fullstory
  FS('setProperties', {
    type: 'user',
    properties: {
      // Profile
      displayName: profile.fullName,
      email: profile.email,
      role: profile.role,

      // Subscription
      plan: subscription.plan,
      planStatus: subscription.status,
      mrr: subscription.mrr,

      // Usage
      lastLoginAt: usage.lastLogin,
      totalLogins: usage.loginCount,
      daysActive: usage.activeDays,
    },
    schema: {
      mrr: 'real',
      lastLoginAt: 'date',
      totalLogins: 'int',
      daysActive: 'int',
    },
  })
}

// Run on app initialization
initApp().then(syncUserProperties)

Pattern 3: Event-Driven Property Updates

// Update properties based on key events
const eventPropertyMap = {
  trial_started: (event) => ({
    trialStartedAt: new Date().toISOString(),
    trialPlan: event.plan,
    isTrialing: true,
  }),

  trial_converted: (event) => ({
    trialConvertedAt: new Date().toISOString(),
    isTrialing: false,
    isPaying: true,
    plan: event.plan,
  }),

  trial_expired: (event) => ({
    trialExpiredAt: new Date().toISOString(),
    isTrialing: false,
    isPaying: false,
  }),

  feature_enabled: (event) => ({
    [`feature_${event.feature}_enabled`]: true,
    [`feature_${event.feature}_enabledAt`]: new Date().toISOString(),
  }),
}

function handleBusinessEvent(eventName, eventData) {
  // Track the event
  FS('trackEvent', {
    name: eventName,
    properties: eventData,
  })

  // Update user properties if mapping exists
  const propertyUpdater = eventPropertyMap[eventName]
  if (propertyUpdater) {
    FS('setProperties', {
      type: 'user',
      properties: propertyUpdater(eventData),
    })
  }
}

RELATIONSHIP WITH OTHER APIs

setIdentity + setProperties Workflow

// Initial identification with core properties
FS('setIdentity', {
  uid: user.id,
  properties: {
    displayName: user.name,
    email: user.email,
  },
})

// Later: add more properties
FS('setProperties', {
  type: 'user',
  properties: {
    company: companyData.name,
    role: roleData.title,
  },
})

setProperties (user) vs setProperties (page)

// User properties: persist across sessions, about the person
FS('setProperties', {
  type: 'user',
  properties: {
    plan: 'enterprise',
    accountAge: 365,
  },
})

// Page properties: session-scoped, about the current context
FS('setProperties', {
  type: 'page',
  properties: {
    pageName: 'Dashboard',
    filters: ['active', 'recent'],
  },
})

setProperties vs trackEvent

// Properties: current state (what IS)
FS('setProperties', {
  type: 'user',
  properties: {
    plan: 'professional',
    seats: 10,
  },
})

// Events: actions/changes (what HAPPENED)
FS('trackEvent', {
  name: 'Plan Upgraded',
  properties: {
    from: 'starter',
    to: 'professional',
    seatChange: 5,
  },
})

TROUBLESHOOTING

Properties Not Appearing

Symptom: User properties don't show in Fullstory

Common Causes:

1. ❌ User not identified first
2. ❌ Missing type: 'user' parameter
3. ❌ Type mismatches in values
4. ❌ Rate limits exceeded

Solutions:

• ✅ Ensure setIdentity called first
• ✅ Always include type: 'user'
• ✅ Use schema for explicit typing
• ✅ Batch updates to avoid rate limits

Properties Show Wrong Values

Symptom: Property values are incorrect or unexpected type

Common Causes:

1. ❌ Value format doesn't match schema type
2. ❌ Formatted strings for numeric values
3. ❌ Boolean as string ("true" vs true)

Solutions:

• ✅ Use clean numeric values
• ✅ Use actual boolean types
• ✅ Format dates as ISO8601
• ✅ Specify schema explicitly

displayName Keeps Getting Overwritten

Symptom: User's display name changes unexpectedly

Common Causes:

1. ❌ Multiple places setting displayName
2. ❌ Automated scripts overwriting
3. ❌ Race conditions in property updates

Solutions:

• ✅ Set displayName only in identification flow
• ✅ Audit all setProperties calls
• ✅ Use dedicated fields for other "name" data

LIMITS AND CONSTRAINTS

Property Limits

• Check your Fullstory plan for specific limits
• Property names: alphanumeric, underscores, hyphens
• Avoid high-cardinality properties

Call Frequency

• Sustained: 30 calls per page per minute
• Burst: 10 calls per second

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:

   • User must be identified first (setIdentity)
   • Include type: 'user' parameter
   • Use schema for non-string types
   • Batch updates to respect rate limits

2. Common mistakes to watch for:

   • Missing type parameter
   • Setting properties before identification
   • Excessive call frequency
   • Type mismatches in values
   • Overwriting displayName accidentally

3. Questions to ask developers:

   • Will the user be anonymous or identified? (Both work - setProperties doesn't require identification)
   • 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. Best practices to recommend:

   • Set core properties in setIdentity
   • Use setProperties for subsequent updates
   • Track important changes as events too
   • Consider property batching for frequent updates

REFERENCE LINKS

• Set User Properties: https://developer.fullstory.com/browser/identification/set-user-properties/
• Custom Properties: https://developer.fullstory.com/browser/custom-properties/
• Identify Users: https://developer.fullstory.com/browser/identification/identify-users/
• Help Center - Custom Properties: https://help.fullstory.com/hc/en-us/articles/360020623234

This skill document was created to help Agent understand and guide developers in implementing Fullstory's User Properties API correctly for web applications.