Fullstory Browser API v2: Getting Started Guide

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

Strategy & Meta Skills

Industry-Specific Skills

---

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

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

How Fullstory Tracks Users (First-Party Cookies)

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

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:

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

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

---

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 for complete guide

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 for complete guide

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 for complete guide

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 for complete guide

---

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

Privacy & Control

Lifecycle & Utilities

Industry-Specific

Strategy

Framework Integration

---

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.