Agent skills
fullstory-anonymize-users

Agent skill

fullstory-anonymize-users

Comprehensive guide for implementing Fullstory's User Anonymization API (setIdentity with anonymous:true) for web applications. Teaches proper logout handling, session management, privacy compliance, and user switching scenarios. Includes detailed good/bad examples for logout flows, multi-user applications, and privacy-conscious implementations.

View SKILL.md on GitHub Repository

Stars 163

Forks 31

Install this agent skill to your Project

npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/design/fullstory-anonymize-users

SKILL.md

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 }), the current session ends and a fresh anonymous session begins. The previously identified user remains in Fullstory's records, but subsequent activity is no longer linked to them.

Core Concepts

What Happens When You Anonymize

Current session is closed and marked as belonging to the identified user
A new fs_uid cookie is generated - breaking the link to all previous sessions
New anonymous session begins with a new session ID and new cookie
Previous user data is preserved - anonymizing doesn't delete history
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

Scenario	Should Anonymize?	Reason
User logs out	✅ Yes	Prevents session attribution to wrong user
User switches accounts	✅ Yes	Clean slate before new identification
User requests data deletion	❓ Consider	Part of broader privacy implementation
User clears browser data	❌ No	Fullstory handles this automatically
Page navigation	❌ No	Identity persists across pages
Session timeout	❓ Depends	Based on your security requirements

API Reference

Basic Syntax

javascript

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

Parameters

Parameter	Type	Required	Description
`anonymous`	boolean	Yes	Must be `true` to anonymize the user

Rate Limits

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

Async Version

javascript

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

✅ GOOD IMPLEMENTATION EXAMPLES

Example 1: Basic Logout Handler

javascript

// 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

jsx

// 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

javascript

// 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

javascript

// 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

javascript

// 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

javascript

// 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:

javascript

// GOOD: Include Fullstory anonymization
function handleLogout() {
  clearAuthTokens();
  clearUserState();
  
  // Anonymize before redirect
  FS('setIdentity', { anonymous: true });
  
  window.location.href = '/login';
}

Example 2: Anonymizing After Redirect

javascript

// 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:

javascript

// GOOD: Anonymize BEFORE navigation
async function handleLogout() {
  // Anonymize first
  await FS('setIdentityAsync', { anonymous: true });
  
  // Then navigate
  window.location.href = '/login';
}

Example 3: Anonymizing Repeatedly

javascript

// 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:

javascript

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

Example 4: Using Wrong Parameter

javascript

// 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:

javascript

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

Example 5: Anonymizing Without Tracking Important Events

javascript

// 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:

javascript

// 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

javascript

// 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:

javascript

// 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

javascript

// 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

javascript

// 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

javascript

// 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

javascript

// 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

javascript

// 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:

❌ Anonymize called after page navigation starts
❌ Anonymize never called (missing from logout flow)
❌ 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:

❌ Calling anonymize on every page load
❌ Calling anonymize on errors
❌ 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:

Always emphasize:
- Anonymize BEFORE navigation/redirects
- Use { anonymous: true } syntax exactly
- Track important events BEFORE anonymizing
- Single call per logout is sufficient
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
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?
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.

Maintainer

majiayu000 Core maintainer

Source details

Full Name: majiayu000/claude-skill-registry
Branch: main
Path in repo: skills/design/fullstory-anonymize-users
License: MIT License

Featured Tools

Join Our Newsletter

Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.

163 31

Explore

Didn't find tool you were looking for?

Search AI Tools

Install this agent skill to your Project

SKILL.md

Fullstory Anonymize Users API

Overview

Core Concepts

What Happens When You Anonymize

Session Lifecycle

When to Anonymize

API Reference

Basic Syntax

Parameters

Rate Limits

Async Version

✅ GOOD IMPLEMENTATION EXAMPLES

Example 1: Basic Logout Handler

Example 2: React Logout with Auth Context

Example 3: Account Switching

Example 4: Session Timeout Handler

Example 5: Privacy-Conscious Implementation

❌ BAD IMPLEMENTATION EXAMPLES

Example 1: Forgetting to Anonymize on Logout

Example 2: Anonymizing After Redirect

Example 3: Anonymizing Repeatedly

Example 4: Using Wrong Parameter

Example 5: Anonymizing Without Tracking Important Events

Example 6: Anonymizing During Errors Instead of Proper Handling

COMMON IMPLEMENTATION PATTERNS

Pattern 1: Logout Service

Pattern 2: Multi-Tenant Application

Pattern 3: Kiosk/Shared Device Mode

RELATIONSHIP WITH OTHER FS APIs

Anonymize vs setProperties

Anonymize + Re-identify Flow

TROUBLESHOOTING

Session Not Properly Ending

Too Many Session Splits

LIMITS AND CONSTRAINTS

Call Frequency

Session Behavior

KEY TAKEAWAYS FOR AGENT

REFERENCE LINKS

Recommended Agent Skills

agent-ops-spec

agent-ops-state

agent-ops-spec

agent-ops-testing

agent-ops-testing

agent-ops-state