Fullstory Browser API v2: Getting Started Guide

📋 Version Note: This guide covers Fullstory Browser API v2. Always verify API syntax against the official documentation as the API may evolve. Rate limits, parameters, and features are subject to change.

Overview

This guide provides everything you need to implement Fullstory's Browser API v2 in your web application. It covers:

1. Initial Setup: Snippet installation and configuration
2. API Landscape: Understanding all available APIs
3. Implementation Order: What to implement first
4. Decision Framework: Choosing the right API for your data
5. Privacy Considerations: What to capture, mask, or exclude
6. Industry-Specific Guidance: Best practices for your vertical
7. Skill Navigation: Finding the right detailed guide

Complete Skill Inventory

Core API Skills

fullstory-identify-users

fullstory-anonymize-users

fullstory-user-properties

fullstory-page-properties

fullstory-element-properties

fullstory-analytics-events

fullstory-observe-callbacks

fullstory-logging

fullstory-user-consent

fullstory-capture-control

fullstory-async-methods

fullstory-privacy-controls

Strategy & Meta Skills

fullstory-privacy-strategy

universal-data-scoping-and-decoration

Industry-Specific Skills

fullstory-banking

fullstory-ecommerce

fullstory-gaming

fullstory-healthcare

fullstory-saas

fullstory-travel

fullstory-media-entertainment

Industry Comparison at a Glance

Different industries have vastly different requirements for Fullstory implementation. This table summarizes the key differences:

Privacy Defaults by Industry

What to Capture by Industry

Legend: ✅ = Capture, ⚠️ = Consider/Mask, ❌ = Exclude

Key Regulatory Requirements

I. The Fullstory API Ecosystem

Complete API Reference

FS('setIdentity', { uid, properties })

fullstory-identify-users

FS('setIdentity', { anonymous: true })

fullstory-anonymize-users

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

fullstory-user-properties

FS('setProperties', { type: 'page', ... })

fullstory-page-properties

data-fs-*

fullstory-element-properties

FS('trackEvent', { name, properties })

fullstory-analytics-events

FS('observe', { type, callback })

fullstory-observe-callbacks

FS('log', { level, msg })

fullstory-logging

FS('setIdentity', { consent: bool })

fullstory-user-consent

FS('shutdown')

FS('restart')

fullstory-capture-control

FS('*Async')

fullstory-async-methods

API Categories

┌─────────────────────────────────────────────────────────────────────┐
│                        FULLSTORY BROWSER API v2                      │
├─────────────────────────────────────────────────────────────────────┤
│  IDENTITY & USER                                                     │
│  ├── setIdentity (uid)        - Identify users                      │
│  ├── setIdentity (anonymous)  - Anonymize users                     │
│  ├── setIdentity (consent)    - Manage consent                      │
│  └── setProperties (user)     - Update user attributes              │
├─────────────────────────────────────────────────────────────────────┤
│  CONTEXT & PROPERTIES                                                │
│  ├── setProperties (page)     - Page-level context                  │
│  └── Element Properties       - Interaction-level context           │
├─────────────────────────────────────────────────────────────────────┤
│  EVENTS & ACTIONS                                                    │
│  └── trackEvent               - Discrete business events            │
├─────────────────────────────────────────────────────────────────────┤
│  PRIVACY & CONTROL                                                   │
│  ├── fs-exclude / fs-mask     - Element privacy classes             │
│  ├── shutdown / restart       - Capture control                     │
│  └── consent                  - User consent management             │
├─────────────────────────────────────────────────────────────────────┤
│  LIFECYCLE & UTILITIES                                               │
│  ├── observe                  - Lifecycle callbacks                 │
│  ├── log                      - Session logging                     │
│  ├── getSession               - Get session URL                     │
│  └── *Async variants          - Promise-based methods               │
└─────────────────────────────────────────────────────────────────────┘

II. Snippet Installation

Basic Snippet (v2)

Add this snippet to your HTML

<head>

<script>
  window['_fs_host'] = 'fullstory.com'
  window['_fs_script'] = 'edge.fullstory.com/s/fs.js'
  window['_fs_org'] = 'YOUR_ORG_ID'
  window['_fs_namespace'] = 'FS'

  ;(function (m, n, e, t, l, o, g, y) {
    if (e in m) {
      if (m.console && m.console.log) {
        m.console.log('Fullstory namespace conflict. Please set window["_fs_namespace"].')
      }
      return
    }
    g = m[e] = function (a, b, s) {
      g.q ? g.q.push([a, b, s]) : g._api(a, b, s)
    }
    g.q = []
    o = n.createElement(t)
    o.async = 1
    o.crossOrigin = 'anonymous'
    o.src = 'https://' + _fs_script
    y = n.getElementsByTagName(t)[0]
    y.parentNode.insertBefore(o, y)
    g.identify = function (i, v, s) {
      g(l, {uid: i}, s)
      if (v) g(l, v, s)
    }
    g.setUserVars = function (v, s) {
      g(l, v, s)
    }
    g.event = function (i, v, s) {
      g('event', {n: i, p: v}, s)
    }
    g.anonymize = function () {
      g.identify(!!0)
    }
    g.shutdown = function () {
      g('rec', !1)
    }
    g.restart = function () {
      g('rec', !0)
    }
    g.log = function (a, b) {
      g('log', [a, b])
    }
    g.consent = function (a) {
      g('consent', !arguments.length || a)
    }
    g.identifyAccount = function (i, v) {
      o = 'account'
      v = v || {}
      v.acctId = i
      g(o, v)
    }
    g.clearUserCookie = function () {}
    g.setVars = function (n, p) {
      g('setVars', [n, p])
    }
    g._w = {}
    y = 'XMLHttpRequest'
    g._w[y] = m[y]
    y = 'fetch'
    g._w[y] = m[y]
    if (m[y])
      m[y] = function () {
        return g._w[y].apply(this, arguments)
      }
    g._v = '2.0.0'
  })(window, document, window['_fs_namespace'], 'script', 'identify')
</script>

Configuration Options

_fs_org

_fs_namespace

'FS'

_fs_capture_on_startup

true

_fs_host

'fullstory.com'

_fs_script

'edge.fullstory.com/s/fs.js'

How Fullstory Tracks Users (First-Party Cookies)

Fullstory uses first-party cookies set on YOUR domain to track users:

fs_uid

fs_cid

fs_lua

Why First-Party Cookies Matter:

Key Behaviors:

• Anonymous users persist: Same

  fs_uid

  cookie = same user across sessions (until cookie expires/deleted)
• Session merging: When

  setIdentity

  is called, ALL previous anonymous sessions from that cookie merge into the identified user
• Anonymization resets:

  setIdentity({ anonymous: true })

  generates a NEW

  fs_uid

  cookie, breaking the link to previous sessions

Reference: Why Fullstory uses First-Party Cookies

Private by Default Mode (Recommended for Sensitive Industries)

Fullstory offers a Private by Default capture mode that inverts the default behavior:

fs-mask

fs-exclude

fs-unmask

When to Use Private by Default:

• ✅ Banking / Financial services
• ✅ Healthcare / HIPAA-regulated
• ✅ Enterprise SaaS with customer data
• ✅ Any app where "default open" is too risky

Enable via:

• New accounts: Select during onboarding wizard
• Existing accounts: Contact Fullstory Support

Reference: Fullstory Private by Default

Consent-Required Configuration (GDPR)

For GDPR compliance, don't capture until consent is given:

<script>
  window['_fs_capture_on_startup'] = false // Don't capture until consent
  window['_fs_org'] = 'YOUR_ORG_ID'
  // ... rest of snippet
</script>

Then call when consent is granted:

FS('setIdentity', {consent: true})

III. Implementation Order

Recommended Implementation Sequence

Phase 1: Foundation
├── 1. Install snippet
├── 2. Implement privacy controls (fs-exclude, fs-mask)
├── 3. Implement user identification (login flow)
├── 4. Implement anonymization (logout flow)
└── 5. Set up basic page properties (pageName)

Phase 2: Context
├── 6. Add user properties (plan, role, company)
├── 7. Enhance page properties (search terms, filters)
└── 8. Add element properties (product IDs, positions)

Phase 3: Events
├── 9. Implement key business events
├── 10. Add funnel tracking
└── 11. Add feature usage tracking

Phase 4: Advanced
├── 12. Set up observers for session URL
├── 13. Implement consent flows (if GDPR required)
├── 14. Add error logging
└── 15. Implement capture control (if needed)

Minimum Viable Implementation

For a basic integration, implement these APIs:

// 1. Identify users on login
FS('setIdentity', {
  uid: user.id,
  properties: {
    displayName: user.name,
    email: user.email,
  },
})

// 2. Set page context
FS('setProperties', {
  type: 'page',
  properties: {
    pageName: 'Dashboard',
  },
})

// 3. Track key events
FS('trackEvent', {
  name: 'Feature Used',
  properties: {
    featureName: 'export',
  },
})

// 4. Anonymize on logout
FS('setIdentity', {anonymous: true})

IV. Privacy First: Three Privacy Modes

Before capturing any data, understand the three privacy modes:

Privacy Mode Comparison

.fs-exclude

.fs-mask

.fs-unmask

Quick Privacy Decision

Is this data regulated (HIPAA, PCI, GLBA)?
     │
     YES → fs-exclude (nothing leaves device)
     │
     NO
     │
     ▼
Is this PII (name, email, address)?
     │
     YES → fs-mask (structure captured, text replaced)
     │
     NO
     │
     ▼
Is this public/business data?
     │
     YES → fs-unmask or default (everything captured)

Privacy by Industry Quick Reference

V. Quick Decision Guide

"Where should I put this data?"

Is this data about WHO the user is?
(plan, role, company, signup date)
     │
     YES → User Properties (setIdentity or setProperties type: 'user')
     │
     NO
     │
     ▼
Is this data the same for the entire page?
(search term, product ID on detail page, filters)
     │
     YES → Page Properties (setProperties type: 'page')
     │
     NO
     │
     ▼
Is this data specific to one element among many?
(product ID in a grid, position in list)
     │
     YES → Element Properties (data-fs-* attributes)
     │
     NO
     │
     ▼
Is this a discrete action/event?
(purchase, signup, feature used)
     │
     YES → Event (trackEvent)

Quick Reference Table

setIdentity

fullstory-identify-users

setProperties(user)

fullstory-user-properties

setProperties(page)

fullstory-page-properties

fullstory-element-properties

trackEvent

fullstory-analytics-events

setIdentity(anonymous)

fullstory-anonymize-users

observe

getSession

fullstory-observe-callbacks

setIdentity(consent)

fullstory-user-consent

shutdown

restart

fullstory-capture-control

log

fullstory-logging

fullstory-privacy-controls

VI. Industry-Specific Quick Start

Banking/Financial Services

// Use internal customer ID, never SSN or account numbers
FS('setIdentity', {uid: customer.customerId})

// Exclude all financial data, use ranges if needed
// Add fs-exclude to: balances, transactions, account numbers
FS('trackEvent', {
  name: 'transfer_completed',
  properties: {
    transfer_type: 'internal',
    amount_range: '$100-$500', // Never exact amount
  },
})

→ See

fullstory-banking

E-commerce

// Rich product tracking is valuable
FS('setProperties', {
  type: 'page',
  properties: {
    pageName: 'Product Detail',
    productId: product.id,
    productName: product.name,
    price: product.price, // Prices are fine in e-commerce
  },
})

// Track conversions with full details
FS('trackEvent', {
  name: 'purchase_completed',
  properties: {
    order_id: order.id,
    revenue: order.total,
    item_count: order.items.length,
  },
})

→ See

fullstory-ecommerce

Healthcare

// Extremely limited capture - use anonymous sessions if possible
FS('setIdentity', {uid: generateSessionId()}) // No linking to patient

// Exclude EVERYTHING medical - masking is NOT sufficient
// Use Private by Default mode
// Only track: navigation, errors, page load times

→ See

fullstory-healthcare

SaaS

// Rich user identification for feature adoption
FS('setIdentity', {
  uid: user.id,
  properties: {
    displayName: user.firstName,
    plan: organization.plan,
    role: user.role,
    org_id: organization.id,
  },
})

// Track feature usage comprehensively
FS('trackEvent', {
  name: 'feature_first_use',
  properties: {
    feature_name: 'report_builder',
    days_since_signup: user.daysSinceSignup,
  },
})

→ See

fullstory-saas

VII. Common Integration Patterns

Pattern 1: React Integration

// hooks/useFullstory.js
import {useEffect} from 'react'
import {useAuth} from './useAuth'
import {useLocation} from 'react-router-dom'

export function useFullstory() {
  const {user, isAuthenticated} = useAuth()
  const location = useLocation()

  // Handle user identification
  useEffect(() => {
    if (isAuthenticated && user) {
      FS('setIdentity', {
        uid: user.id,
        properties: {
          displayName: user.name,
          email: user.email,
          plan: user.plan,
        },
      })
    }
  }, [user, isAuthenticated])

  // Handle page changes
  useEffect(() => {
    const pageName = getPageName(location.pathname)
    FS('setProperties', {
      type: 'page',
      properties: {pageName},
    })
  }, [location])

  // Return helper functions
  return {
    trackEvent: (name, properties) => {
      FS('trackEvent', {name, properties})
    },
    setUserProperty: (properties) => {
      FS('setProperties', {type: 'user', properties})
    },
  }
}

Pattern 2: Privacy-First Component Wrapper

// components/PrivacyWrapper.js
export function SensitiveData({ children, level = 'mask' }) {
  const className = level === 'exclude' ? 'fs-exclude' : 'fs-mask';
  return <div className={className}>{children}</div>;
}

export function PublicData({ children }) {
  return <div className="fs-unmask">{children}</div>;
}

// Usage
<SensitiveData level="exclude">
  <CreditCardForm />
</SensitiveData>

<SensitiveData>
  <UserProfile />  {/* Masked by default */}
</SensitiveData>

<PublicData>
  <ProductGrid />  {/* Visible */}
</PublicData>

VIII. Testing Your Integration

1. Verify Snippet Installation

Open browser console and check:

typeof FS !== 'undefined' // Should be true
FS('getSession') // Should return session URL

2. Check Privacy Controls

In browser DevTools:

• Verify

  .fs-exclude

  classes on sensitive elements
• Verify

  .fs-mask

  classes on PII fields
• Watch a session replay and confirm masked/excluded content

3. Check User Identification

After login, verify in Fullstory:

• Session shows user's displayName
• User can be found by search
• User properties appear in session details

4. Validate Events

After triggering events:

• Check Events panel in Fullstory session
• Verify event properties are captured correctly
• Test event-based searches work

IX. Troubleshooting

Fullstory Not Loading

if (typeof FS === 'undefined') {
  console.error('Fullstory not loaded - check snippet installation')
}

Common causes:

• Snippet not in

  <head>

• Wrong org ID
• Ad blocker blocking script
• Content Security Policy blocking

User Not Identified

console.log('Identifying user:', user.id)
FS('setIdentity', {uid: user.id})

Common causes:

• uid is undefined or null
• setIdentity called before FS loads
• Identity called with wrong syntax

Privacy Not Working

Common causes:

• CSS class not on element (check DevTools)
• Child element needs its own class
• Conflicting CSS selector rules in Settings

X. Related Skills Reference

Core Data Capture

fullstory-identify-users

fullstory-anonymize-users

fullstory-user-properties

fullstory-page-properties

fullstory-element-properties

fullstory-analytics-events

Privacy & Control

fullstory-privacy-controls

fullstory-privacy-strategy

fullstory-user-consent

fullstory-capture-control

Lifecycle & Utilities

fullstory-async-methods

fullstory-observe-callbacks

fullstory-logging

Industry-Specific

fullstory-banking

fullstory-ecommerce

fullstory-gaming

fullstory-healthcare

fullstory-saas

fullstory-travel

fullstory-media-entertainment

Strategy

universal-data-scoping-and-decoration

Framework Integration

fullstory-stable-selectors

data-*

Key Takeaways for Agent

When helping developers get started with Fullstory:

1. Privacy first:

   • Ask what industry/regulations apply
   • Point to appropriate industry skill
   • Default to more restrictive privacy in regulated industries

2. Implementation order matters:

   • Start with privacy controls
   • Then identification (login/logout)
   • Add page properties (pageName is crucial for Journeys)
   • Then events and element properties

3. Minimum viable integration:

   • Privacy classes on sensitive elements
   • setIdentity on login
   • setIdentity anonymous on logout
   • setProperties(page) with pageName
   • A few key trackEvent calls

4. Industry matters:

   • Healthcare: Default exclude, BAA required
   • Banking: Exclude financial data, use ranges
   • E-commerce: Can capture most product data
   • SaaS: Rich feature tracking is valuable

5. Common first questions:

   • "How do I link sessions to users?" →

     fullstory-identify-users

   • "Where should I put this data?" →

     universal-data-scoping-and-decoration

   • "How do I track conversions?" →

     fullstory-analytics-events

   • "What should I mask vs exclude?" →

     fullstory-privacy-controls

6. Point to specific skills for detailed implementation guidance

Reference Links

• Getting Started: https://developer.fullstory.com/browser/getting-started/
• Privacy Controls: https://help.fullstory.com/hc/en-us/articles/360020623574
• Custom Properties: https://developer.fullstory.com/browser/custom-properties/
• Help Center: https://help.fullstory.com/

This getting started guide provides the foundation for implementing Fullstory Browser API v2. For detailed implementation guidance on any specific API or industry, refer to the linked skill documents.