Fullstory Anonymize Users API

Overview

Fullstory's Anonymize Users API allows developers to release the identity of the current user and create a new anonymous session. This is essential for:

• User Logout: Properly ending an identified session when a user logs out
• Account Switching: Allowing users to switch between accounts cleanly
• Privacy Compliance: Implementing "forget me" or privacy-conscious features
• Shared Devices: Ensuring one user's session doesn't bleed into another's

When you call

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

Core Concepts

What Happens When You Anonymize

1. Current session is closed and marked as belonging to the identified user
2. A new

   fs_uid

   cookie is generated - breaking the link to all previous sessions
3. New anonymous session begins with a new session ID and new cookie
4. Previous user data is preserved - anonymizing doesn't delete history
5. Subsequent activity is anonymous until a new

   setIdentity

   call

Cookie Behavior: Normally, the

fs_uid

first-party cookie (1-year expiry) links all sessions from the same browser together. When

anonymize

is called, Fullstory generates a new

fs_uid

cookie, effectively creating a "new device" from Fullstory's perspective. Any future

setIdentity

calls will only merge sessions from the new cookie, not the old one.

Reference: Why Fullstory uses First-Party Cookies

Session Lifecycle

┌─────────────┐  Login   ┌─────────────┐  Logout  ┌─────────────┐
│  Anonymous  │ ───────► │ Identified  │ ───────► │ New Anon    │
│  Session A  │          │  Session B  │          │  Session C  │
└─────────────┘          └─────────────┘          └─────────────┘
                              │
              setIdentity     │    setIdentity
              (uid: 'xxx')    │    (anonymous: true)

When to Anonymize

API Reference

Basic Syntax

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

Parameters

anonymous

true

Rate Limits

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

Async Version

await FS('setIdentityAsync', {anonymous: true})

✅ GOOD IMPLEMENTATION EXAMPLES

Example 1: Basic Logout Handler

// GOOD: Proper logout with Fullstory anonymization
async function handleLogout() {
  try {
    // 1. Call your backend logout endpoint
    await fetch('/api/auth/logout', {method: 'POST'})

    // 2. Clear local authentication state
    clearAuthTokens()
    clearUserState()

    // 3. Anonymize in Fullstory BEFORE redirecting
    FS('setIdentity', {anonymous: true})

    // 4. Redirect to login page
    window.location.href = '/login'
  } catch (error) {
    console.error('Logout failed:', error)
    // Still anonymize even if backend fails
    FS('setIdentity', {anonymous: true})
    window.location.href = '/login'
  }
}

Why this is good:

• ✅ Anonymizes before redirect
• ✅ Handles errors gracefully
• ✅ Clears local state before anonymizing
• ✅ Ensures next user won't be associated with previous user

Example 2: React Logout with Auth Context

// GOOD: React hook pattern for logout with Fullstory
import {useCallback} from 'react'
import {useAuth} from './auth-context'
import {useNavigate} from 'react-router-dom'

function useLogout() {
  const {clearAuth} = useAuth()
  const navigate = useNavigate()

  const logout = useCallback(async () => {
    // Track the logout action before anonymizing
    FS('trackEvent', {
      name: 'User Logged Out',
      properties: {
        logoutMethod: 'manual',
        sessionDuration: getSessionDuration(),
      },
    })

    // Clear application auth state
    await clearAuth()

    // Anonymize the Fullstory session
    FS('setIdentity', {anonymous: true})

    // Navigate to home/login
    navigate('/login')
  }, [clearAuth, navigate])

  return logout
}

// Usage
function LogoutButton() {
  const logout = useLogout()
  return <button onClick={logout}>Sign Out</button>
}

Why this is good:

• ✅ Tracks logout event before anonymizing (preserves attribution)
• ✅ Integrated with React ecosystem
• ✅ Reusable across components
• ✅ Clean navigation after logout

Example 3: Account Switching

// GOOD: Clean account switching with proper session boundaries
async function switchAccount(newAccountId) {
  const newUser = await fetchAccountDetails(newAccountId)

  // Track the switch event under current user
  FS('trackEvent', {
    name: 'Account Switch Initiated',
    properties: {
      targetAccountId: newAccountId,
    },
  })

  // Step 1: Anonymize current session
  FS('setIdentity', {anonymous: true})

  // Step 2: Set up new account context
  await setupAccountContext(newUser)

  // Step 3: Identify as new user
  FS('setIdentity', {
    uid: newUser.id,
    properties: {
      displayName: newUser.name,
      email: newUser.email,
      accountType: newUser.type,
    },
  })

  // Refresh UI
  window.location.reload()
}

Why this is good:

• ✅ Tracks event before identity change
• ✅ Cleanly separates sessions between accounts
• ✅ No data contamination between accounts
• ✅ New user gets fresh identification

Example 4: Session Timeout Handler

// GOOD: Handling session timeout with Fullstory
class SessionManager {
  constructor() {
    this.timeoutDuration = 30 * 60 * 1000 // 30 minutes
    this.timeoutId = null
    this.lastActivity = Date.now()
  }

  startTimeout() {
    this.resetTimeout()
    document.addEventListener('click', () => this.resetTimeout())
    document.addEventListener('keypress', () => this.resetTimeout())
  }

  resetTimeout() {
    this.lastActivity = Date.now()
    if (this.timeoutId) clearTimeout(this.timeoutId)

    this.timeoutId = setTimeout(() => {
      this.handleSessionTimeout()
    }, this.timeoutDuration)
  }

  async handleSessionTimeout() {
    // Track timeout event while still identified
    FS('trackEvent', {
      name: 'Session Timeout',
      properties: {
        inactivityDuration: Date.now() - this.lastActivity,
        lastPage: window.location.pathname,
      },
    })

    // Anonymize the session
    FS('setIdentity', {anonymous: true})

    // Clear auth and redirect
    clearAuthState()
    showTimeoutModal()
  }
}

Why this is good:

• ✅ Tracks timeout before anonymizing
• ✅ Captures useful debugging info
• ✅ Clean session boundary on timeout
• ✅ User feedback via modal

Example 5: Privacy-Conscious Implementation

// GOOD: "Incognito mode" toggle for privacy-conscious users
class PrivacyManager {
  constructor() {
    this.isIncognitoMode = false
    this.originalUserId = null
  }

  async enableIncognitoMode(currentUserId) {
    // Store original user ID for potential re-identification
    this.originalUserId = currentUserId
    this.isIncognitoMode = true

    // Track before anonymizing
    FS('trackEvent', {
      name: 'Incognito Mode Enabled',
      properties: {},
    })

    // Anonymize - activity won't be linked to user
    FS('setIdentity', {anonymous: true})

    // Update UI
    showIncognitoIndicator()
  }

  async disableIncognitoMode() {
    if (!this.originalUserId) return

    this.isIncognitoMode = false

    // Re-identify user
    const user = await getCurrentUser()
    FS('setIdentity', {
      uid: user.id,
      properties: {
        displayName: user.name,
        email: user.email,
      },
    })

    // Track re-enablement
    FS('trackEvent', {
      name: 'Incognito Mode Disabled',
      properties: {},
    })

    hideIncognitoIndicator()
    this.originalUserId = null
  }
}

Why this is good:

• ✅ Gives users control over tracking
• ✅ Maintains ability to re-identify
• ✅ Clear user feedback
• ✅ Events tracked at session boundaries

❌ BAD IMPLEMENTATION EXAMPLES

Example 1: Forgetting to Anonymize on Logout

// BAD: No Fullstory anonymization on logout
function handleLogout() {
  clearAuthTokens()
  clearUserState()
  window.location.href = '/login'
  // Missing FS('setIdentity', { anonymous: true })!
}

Why this is bad:

• ❌ Next user's activity may be attributed to previous user
• ❌ Session continues under wrong identity
• ❌ Data integrity issues in analytics
• ❌ Privacy concern if sharing device

CORRECTED VERSION:

// GOOD: Include Fullstory anonymization
function handleLogout() {
  clearAuthTokens()
  clearUserState()

  // Anonymize before redirect
  FS('setIdentity', {anonymous: true})

  window.location.href = '/login'
}

Example 2: Anonymizing After Redirect

// BAD: Anonymizing after navigation starts
function handleLogout() {
  window.location.href = '/login'

  // BAD: This may never execute - page is already navigating!
  FS('setIdentity', {anonymous: true})
}

Why this is bad:

• ❌ Navigation starts before anonymization
• ❌ FS call may not complete
• ❌ Session may not properly close

CORRECTED VERSION:

// GOOD: Anonymize BEFORE navigation
async function handleLogout() {
  // Anonymize first
  await FS('setIdentityAsync', {anonymous: true})

  // Then navigate
  window.location.href = '/login'
}

Example 3: Anonymizing Repeatedly

// BAD: Calling anonymize multiple times
function handleLogout() {
  // Excessive calls
  FS('setIdentity', {anonymous: true})
  FS('setIdentity', {anonymous: true})
  FS('setIdentity', {anonymous: true})

  window.location.href = '/login'
}

Why this is bad:

• ❌ Wastes API call quota
• ❌ Creates unnecessary session splits
• ❌ May hit rate limits
• ❌ No benefit from multiple calls

CORRECTED VERSION:

// GOOD: Single anonymization call
function handleLogout() {
  FS('setIdentity', {anonymous: true})
  window.location.href = '/login'
}

Example 4: Using Wrong Parameter

// BAD: Wrong way to anonymize
FS('setIdentity', {uid: null}) // BAD: uid shouldn't be null
FS('setIdentity', {uid: 'anonymous'}) // BAD: This identifies as user "anonymous"!
FS('setIdentity', {uid: ''}) // BAD: Empty string uid
FS('setIdentity', {}) // BAD: Missing required parameters

Why this is bad:

• ❌ uid: null may cause errors
• ❌ uid: 'anonymous' creates an identified user named "anonymous"
• ❌ Empty string uid is invalid
• ❌ Empty object doesn't anonymize

CORRECTED VERSION:

// GOOD: Proper anonymization syntax
FS('setIdentity', {anonymous: true})

Example 5: Anonymizing Without Tracking Important Events

// BAD: Missing opportunity to track logout event
function handleLogout() {
  // Just anonymizing without capturing useful data
  FS('setIdentity', {anonymous: true})
  window.location.href = '/login'
}

Why this is bad:

• ❌ No record of intentional logout vs session timeout
• ❌ Can't analyze logout patterns
• ❌ Loses attribution for the logout event itself

CORRECTED VERSION:

// GOOD: Track event before anonymizing
function handleLogout() {
  // Track while still identified
  FS('trackEvent', {
    name: 'User Logged Out',
    properties: {
      logoutMethod: 'user_initiated',
      pageAtLogout: window.location.pathname,
    },
  })

  // Then anonymize
  FS('setIdentity', {anonymous: true})
  window.location.href = '/login'
}

Example 6: Anonymizing During Errors Instead of Proper Handling

// BAD: Using anonymization to "hide" errors
function handleError(error) {
  // Don't use anonymization to hide error attribution!
  FS('setIdentity', {anonymous: true})
  console.error(error)
}

Why this is bad:

• ❌ Loses error attribution to user for debugging
• ❌ Makes it harder to help affected users
• ❌ Misuse of anonymization API
• ❌ Creates confusing session boundaries

CORRECTED VERSION:

// GOOD: Log errors while identified, only anonymize on logout
function handleError(error) {
  // Track the error - attribution helps debugging!
  FS('trackEvent', {
    name: 'Application Error',
    properties: {
      errorMessage: error.message,
      errorCode: error.code,
      page: window.location.pathname,
    },
  })

  // Show error UI without anonymizing
  showErrorMessage(error)
}

COMMON IMPLEMENTATION PATTERNS

Pattern 1: Logout Service

// Centralized logout service
class LogoutService {
  static async logout(options = {}) {
    const {trackEvent = true, redirectUrl = '/login', reason = 'user_initiated'} = options

    // Track logout if requested
    if (trackEvent) {
      FS('trackEvent', {
        name: 'User Logged Out',
        properties: {
          reason: reason,
          sessionDuration: getSessionDuration(),
        },
      })
    }

    // Backend logout
    try {
      await fetch('/api/logout', {method: 'POST'})
    } catch (e) {
      console.warn('Backend logout failed:', e)
    }

    // Clear client state
    clearAuthTokens()
    clearUserState()
    clearLocalStorage()

    // Anonymize Fullstory
    FS('setIdentity', {anonymous: true})

    // Redirect
    if (redirectUrl) {
      window.location.href = redirectUrl
    }
  }
}

// Usage
await LogoutService.logout()
await LogoutService.logout({reason: 'session_timeout', redirectUrl: '/timeout'})

Pattern 2: Multi-Tenant Application

// For apps with workspace/tenant switching
class TenantManager {
  async switchTenant(newTenantId) {
    const currentUser = getCurrentUser()

    // Track switch under current context
    FS('trackEvent', {
      name: 'Tenant Switch',
      properties: {
        fromTenant: currentUser.tenantId,
        toTenant: newTenantId,
      },
    })

    // Start fresh session for new tenant context
    FS('setIdentity', {anonymous: true})

    // Update tenant context
    await loadTenantContext(newTenantId)

    // Re-identify with new tenant context
    FS('setIdentity', {
      uid: currentUser.id,
      properties: {
        displayName: currentUser.name,
        email: currentUser.email,
        tenantId: newTenantId,
        tenantName: await getTenantName(newTenantId),
      },
    })
  }
}

Pattern 3: Kiosk/Shared Device Mode

// For shared devices like kiosks
class KioskMode {
  sessionTimeout = 5 * 60 * 1000 // 5 minutes

  async startSession(user) {
    FS('setIdentity', {
      uid: user.id,
      properties: {
        displayName: user.name,
        deviceMode: 'kiosk',
        locationId: getKioskLocation(),
      },
    })

    // Auto-logout after timeout
    setTimeout(() => this.endSession(), this.sessionTimeout)
  }

  async endSession() {
    FS('trackEvent', {
      name: 'Kiosk Session Ended',
      properties: {
        endReason: 'timeout',
        location: getKioskLocation(),
      },
    })

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

    // Reset to welcome screen
    showWelcomeScreen()
  }
}

RELATIONSHIP WITH OTHER FS APIs

Anonymize vs setProperties

// setProperties updates user info without changing identity
FS('setProperties', {
  type: 'user',
  properties: {lastActiveAt: new Date().toISOString()},
})

// anonymous: true ends the session entirely
FS('setIdentity', {anonymous: true}) // New session starts

Anonymize + Re-identify Flow

// Common pattern: switch users
FS('setIdentity', {anonymous: true}) // End session 1

// Some time passes, new user logs in

FS('setIdentity', {
  // Start session 2
  uid: newUser.id,
  properties: {displayName: newUser.name},
})

TROUBLESHOOTING

Session Not Properly Ending

Symptom: New user activity appears under old user

Common Causes:

1. ❌ Anonymize called after page navigation starts
2. ❌ Anonymize never called (missing from logout flow)
3. ❌ Using wrong syntax (uid: null instead of anonymous: true)

Solutions:

• ✅ Use async version and await completion
• ✅ Audit all logout paths to ensure anonymization
• ✅ Use

  { anonymous: true }

  syntax

Too Many Session Splits

Symptom: User has many short, fragmented sessions

Common Causes:

1. ❌ Calling anonymize on every page load
2. ❌ Calling anonymize on errors
3. ❌ Multiple anonymize calls in single flow

Solutions:

• ✅ Only anonymize on actual logout/switch events
• ✅ Audit code for unintended anonymize calls
• ✅ Use single anonymize call per logout flow

LIMITS AND CONSTRAINTS

Call Frequency

• Sustained: 30 calls per page per minute
• Burst: 10 calls per second
• Single call per logout is sufficient

Session Behavior

• Anonymization creates a new session immediately
• Previous session data remains intact and attributed
• Subsequent activity is anonymous until next identification

KEY TAKEAWAYS FOR AGENT

When helping developers implement User Anonymization:

1. Always emphasize:

   • Anonymize BEFORE navigation/redirects
   • Use

     { anonymous: true }

     syntax exactly
   • Track important events BEFORE anonymizing
   • Single call per logout is sufficient

2. Common mistakes to watch for:

   • Forgetting to anonymize on logout
   • Anonymizing after redirect starts
   • Using wrong syntax (uid: null, uid: 'anonymous')
   • Over-calling anonymize
   • Missing trackEvent before anonymize

3. Questions to ask developers:

   • What are all the logout/signout paths in your app?
   • Do users switch between accounts?
   • Is this a shared device scenario?
   • What events should be tracked before logout?

4. Integration considerations:

   • Must anonymize in all logout paths
   • Consider session timeout handling
   • Account switching needs anonymize between identifications
   • Order matters: track events → anonymize → redirect

REFERENCE LINKS

• Anonymize Users: https://developer.fullstory.com/browser/identification/anonymize-users/
• Identify Users: https://developer.fullstory.com/browser/identification/identify-users/
• Help Center - Anonymizing: https://help.fullstory.com/hc/en-us/articles/360020623514-Anonymizing-Users

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