Fullstory Asynchronous Methods API

Overview

Fullstory's Browser API provides asynchronous versions of all methods by appending Async to the method name. These async methods return Promise-like objects that resolve when Fullstory has started and the action completes. This is essential for:

• Initialization Waiting: Wait for Fullstory to fully bootstrap before taking actions
• Session URL Retrieval: Get the session replay URL for logging, support tickets, etc.
• Error Handling: Know if an API call succeeded or failed
• Sequential Operations: Ensure operations complete in order
• Conditional Logic: Take action based on Fullstory state

Core Concepts

Sync vs Async Methods

Method Type	Returns	Use When
FS('methodName')	undefined	Fire-and-forget, don't need result
FS('methodNameAsync')	Promise-like	Need result, error handling, or sequencing

Promise-like Object

The object returned from async methods:

• Can be awaited
• Supports .then() chaining
• Important: .catch() may not work in older browsers without Promise polyfill
• May reject if Fullstory fails to initialize

Available Async Methods

Every FS method has an async variant:

Sync Method	Async Method
FS('setIdentity', {...})	FS('setIdentityAsync', {...})
FS('setProperties', {...})	FS('setPropertiesAsync', {...})
FS('trackEvent', {...})	FS('trackEventAsync', {...})
FS('getSession')	FS('getSessionAsync')
FS('shutdown')	FS('shutdownAsync')
FS('restart')	FS('restartAsync')
FS('log', {...})	FS('logAsync', {...})

---

API Reference

Basic Syntax

// Async/await pattern
const result = await FS('methodNameAsync', params);

// Promise pattern
FS('methodNameAsync', params)
  .then(result => { /* handle result */ });

Return Values

Method	Resolves With
getSessionAsync	Session URL string
setIdentityAsync	undefined (completion signal)
setPropertiesAsync	undefined
trackEventAsync	undefined
shutdownAsync	undefined
restartAsync	undefined
observeAsync	Observer object with .disconnect()

Rejection Scenarios

The Promise may reject when:

• Malformed or missing configuration (no _fs_org)
• User on unsupported browser
• Error in rec/settings or rec/page calls
• Organization over quota
• Fullstory script blocked by ad blocker (may not reliably reject)

---

✅ GOOD IMPLEMENTATION EXAMPLES

Example 1: Get Session URL for Support

// GOOD: Get session URL for support ticket
async function attachSessionToSupportTicket(ticketId) {
  try {
    const sessionUrl = await FS('getSessionAsync');
    
    // Attach to support ticket
    await updateSupportTicket(ticketId, {
      fullstoryUrl: sessionUrl,
      attachedAt: new Date().toISOString()
    });
    
    console.log('Session attached to ticket:', sessionUrl);
    return sessionUrl;
  } catch (error) {
    console.warn('Could not get Fullstory session:', error);
    // Continue without session URL - non-critical
    return null;
  }
}

// Usage
document.getElementById('help-button').addEventListener('click', async () => {
  const ticket = await createSupportTicket(userIssue);
  await attachSessionToSupportTicket(ticket.id);
  showTicketConfirmation(ticket);
});

Why this is good:

• ✅ Uses try/catch for error handling
• ✅ Gracefully handles Fullstory being unavailable
• ✅ Non-blocking failure (user can still submit ticket)
• ✅ Returns null on failure for caller to handle

Example 2: Wait for Fullstory Before Critical Actions

// GOOD: Ensure Fullstory is ready before identifying
async function initializeAnalytics(user) {
  try {
    // Wait for Fullstory to be ready
    await FS('setIdentityAsync', {
      uid: user.id,
      properties: {
        displayName: user.name,
        email: user.email
      }
    });
    
    console.log('User identified successfully');
    
    // Now safe to track initial events
    await FS('trackEventAsync', {
      name: 'Session Started',
      properties: {
        entryPage: window.location.pathname,
        referrer: document.referrer
      }
    });
    
    return true;
  } catch (error) {
    console.error('Fullstory initialization failed:', error);
    // Analytics failure shouldn't break the app
    return false;
  }
}

// Usage in app bootstrap
async function bootstrap() {
  const user = await authenticateUser();
  
  // Initialize analytics (don't block on failure)
  initializeAnalytics(user);
  
  // Continue app initialization
  renderApp();
}

Why this is good:

• ✅ Waits for identification to complete
• ✅ Sequential: identify before tracking events
• ✅ Handles errors gracefully
• ✅ Doesn't block app on analytics failure

Example 3: Session URL in Error Reports

// GOOD: Include session URL in error logging
async function captureError(error, context = {}) {
  let sessionUrl = null;
  
  try {
    // Try to get session URL, but don't let it block error reporting
    sessionUrl = await Promise.race([
      FS('getSessionAsync'),
      new Promise((_, reject) => 
        setTimeout(() => reject(new Error('Timeout')), 2000)
      )
    ]);
  } catch (e) {
    // Session URL unavailable - continue without it
  }
  
  // Send error to monitoring service
  await errorMonitor.captureException(error, {
    ...context,
    fullstoryUrl: sessionUrl,
    timestamp: new Date().toISOString()
  });
  
  // Also log to Fullstory if available
  if (typeof FS !== 'undefined') {
    FS('log', {
      level: 'error',
      msg: error.message
    });
  }
}

// Usage
window.addEventListener('error', (event) => {
  captureError(event.error, {
    source: 'window.onerror',
    filename: event.filename,
    lineno: event.lineno
  });
});

Why this is good:

• ✅ Timeout prevents hanging on unresponsive FS
• ✅ Error reporting continues without session URL
• ✅ Enriches error context when available
• ✅ Logs error to Fullstory too

Example 4: Observer Pattern with Async

// GOOD: Set up Fullstory observers with proper cleanup
async function setupFullstoryObservers() {
  const observers = [];
  
  try {
    // Observer for when Fullstory starts capturing
    const startObserver = await FS('observeAsync', {
      type: 'start',
      callback: () => {
        console.log('Fullstory started capturing');
        initializeSessionTracking();
      }
    });
    observers.push(startObserver);
    
    // Observer for session URL availability
    const sessionObserver = await FS('observeAsync', {
      type: 'session',
      callback: (session) => {
        console.log('Session URL:', session.url);
        storeSessionUrl(session.url);
      }
    });
    observers.push(sessionObserver);
    
    // Return cleanup function
    return () => {
      observers.forEach(obs => obs.disconnect());
    };
    
  } catch (error) {
    console.warn('Could not set up Fullstory observers:', error);
    return () => {}; // No-op cleanup
  }
}

// Usage with React
function App() {
  useEffect(() => {
    let cleanup = () => {};
    
    setupFullstoryObservers().then(cleanupFn => {
      cleanup = cleanupFn;
    });
    
    return () => cleanup();
  }, []);
  
  return <AppContent />;
}

Why this is good:

• ✅ Proper async observer setup
• ✅ Cleanup function for component unmount
• ✅ Handles initialization failure
• ✅ Multiple observers managed together

Example 5: Conditional Feature Based on FS Status

// GOOD: Enable features only if Fullstory is working
class SessionReplayFeature {
  constructor() {
    this.isAvailable = false;
    this.sessionUrl = null;
  }
  
  async initialize() {
    try {
      // Check if Fullstory is capturing
      this.sessionUrl = await FS('getSessionAsync');
      this.isAvailable = true;
      return true;
    } catch (error) {
      this.isAvailable = false;
      console.info('Session replay feature unavailable:', error.message);
      return false;
    }
  }
  
  getShareableLink() {
    if (!this.isAvailable || !this.sessionUrl) {
      return null;
    }
    return this.sessionUrl;
  }
  
  renderShareButton() {
    if (!this.isAvailable) {
      return null; // Don't show button if FS unavailable
    }
    
    return `<button onclick="copySessionLink()">Share Session</button>`;
  }
}

// Usage
const sessionReplay = new SessionReplayFeature();

async function initializeUI() {
  await sessionReplay.initialize();
  
  if (sessionReplay.isAvailable) {
    showSessionReplayUI();
  }
}

Why this is good:

• ✅ Graceful degradation when FS unavailable
• ✅ Feature flag based on actual FS status
• ✅ No broken UI if FS blocked
• ✅ Clear availability check

Example 6: Sequential Operations

// GOOD: Ensure proper sequence of FS operations
async function completeCheckout(orderData) {
  try {
    // 1. First, ensure user is identified
    await FS('setIdentityAsync', {
      uid: orderData.userId,
      properties: {
        displayName: orderData.customerName,
        email: orderData.customerEmail
      }
    });
    
    // 2. Update user properties with purchase info
    await FS('setPropertiesAsync', {
      type: 'user',
      properties: {
        lifetimeValue: orderData.customerLTV,
        totalOrders: orderData.customerOrderCount,
        lastOrderAt: new Date().toISOString()
      }
    });
    
    // 3. Track the purchase event
    await FS('trackEventAsync', {
      name: 'Order Completed',
      properties: {
        orderId: orderData.id,
        revenue: orderData.total,
        itemCount: orderData.items.length
      }
    });
    
    // 4. Get session URL for order records
    const sessionUrl = await FS('getSessionAsync');
    
    // 5. Update order with session URL
    await saveOrderSessionUrl(orderData.id, sessionUrl);
    
    console.log('Checkout tracked successfully');
    
  } catch (error) {
    // Log but don't fail checkout
    console.error('Analytics tracking failed:', error);
  }
}

Why this is good:

• ✅ Operations happen in correct order
• ✅ User identified before properties set
• ✅ Event tracked after user data set
• ✅ Session URL captured at end
• ✅ Errors don't break checkout

---

❌ BAD IMPLEMENTATION EXAMPLES

Example 1: Blocking App on Fullstory

// BAD: Blocking application startup on Fullstory
async function startApp() {
  // This will hang if Fullstory is blocked!
  const sessionUrl = await FS('getSessionAsync');
  
  // App never starts if FS fails
  renderApp();
}

Why this is bad:

• ❌ App hangs if Fullstory blocked by ad blocker
• ❌ Promise may never resolve
• ❌ Critical path depends on non-critical service
• ❌ No timeout or error handling

CORRECTED VERSION:

// GOOD: Non-blocking initialization
async function startApp() {
  // Start app immediately
  renderApp();
  
  // Initialize analytics separately
  try {
    await Promise.race([
      FS('getSessionAsync'),
      new Promise((_, reject) => 
        setTimeout(() => reject(new Error('Timeout')), 5000)
      )
    ]);
    enableAnalyticsFeatures();
  } catch (error) {
    console.warn('Fullstory unavailable, continuing without analytics');
  }
}

Example 2: Missing Error Handling

// BAD: No error handling for async call
async function trackPurchase(order) {
  const sessionUrl = await FS('getSessionAsync');  // May throw!
  saveSessionToOrder(order.id, sessionUrl);  // Never runs if above fails
  
  await FS('trackEventAsync', {  // Also may throw
    name: 'Purchase',
    properties: { orderId: order.id }
  });
}

Why this is bad:

• ❌ Unhandled promise rejection
• ❌ Subsequent code won't run on failure
• ❌ No graceful degradation
• ❌ Could crash in strict mode

CORRECTED VERSION:

// GOOD: Proper error handling
async function trackPurchase(order) {
  let sessionUrl = null;
  
  try {
    sessionUrl = await FS('getSessionAsync');
  } catch (error) {
    console.warn('Could not get session URL:', error);
  }
  
  if (sessionUrl) {
    saveSessionToOrder(order.id, sessionUrl);
  }
  
  try {
    await FS('trackEventAsync', {
      name: 'Purchase',
      properties: { 
        orderId: order.id,
        hasSessionUrl: !!sessionUrl
      }
    });
  } catch (error) {
    console.warn('Could not track purchase event:', error);
  }
}

Example 3: Using .catch() Without Polyfill

// BAD: .catch() may not work in older browsers
FS('getSessionAsync')
  .then(url => console.log('Session:', url))
  .catch(err => console.error('Error:', err));  // May fail silently in IE11!

Why this is bad:

• ❌ .catch() not supported in browsers without Promise
• ❌ Fullstory's Promise-like object may not implement catch
• ❌ Errors may go unhandled

CORRECTED VERSION:

// GOOD: Use try/catch with async/await
async function getSession() {
  try {
    const url = await FS('getSessionAsync');
    console.log('Session:', url);
    return url;
  } catch (err) {
    console.error('Error:', err);
    return null;
  }
}

// OR: Use .then() only with error callback
FS('getSessionAsync').then(
  url => console.log('Session:', url),
  err => console.error('Error:', err)  // Second arg to .then() works
);

Example 4: Unnecessary Async Usage

// BAD: Using async when you don't need the result
async function handleButtonClick() {
  // Don't need to await fire-and-forget events
  await FS('trackEventAsync', {
    name: 'Button Clicked',
    properties: { buttonId: 'submit' }
  });
  
  // User waits unnecessarily
  proceedWithAction();
}

Why this is bad:

• ❌ Adds unnecessary latency to user action
• ❌ User waits for analytics to complete
• ❌ No value from awaiting (result not used)

CORRECTED VERSION:

// GOOD: Fire-and-forget for events
function handleButtonClick() {
  // Don't await - fire and forget
  FS('trackEvent', {
    name: 'Button Clicked',
    properties: { buttonId: 'submit' }
  });
  
  // Proceed immediately
  proceedWithAction();
}

Example 5: Race Condition with Async

// BAD: Race condition between identify and track
async function onLogin(user) {
  // These run in parallel - trackEvent may fire before identity!
  FS('setIdentityAsync', { uid: user.id });
  FS('trackEventAsync', { name: 'Login' });
}

Why this is bad:

• ❌ Event may fire before identity is set
• ❌ Event could be attributed to anonymous user
• ❌ Data integrity issue

CORRECTED VERSION:

// GOOD: Sequential with proper awaiting
async function onLogin(user) {
  // First identify
  await FS('setIdentityAsync', { 
    uid: user.id,
    properties: { displayName: user.name }
  });
  
  // Then track event (now properly attributed)
  await FS('trackEventAsync', { 
    name: 'Login',
    properties: { method: 'password' }
  });
}

// OR: For non-critical, use sync versions (they queue properly)
function onLogin(user) {
  FS('setIdentity', { uid: user.id });  // Queued first
  FS('trackEvent', { name: 'Login' });  // Queued second
  // Fullstory processes queue in order
}

---

COMMON IMPLEMENTATION PATTERNS

Pattern 1: Safe Async Wrapper

// Wrapper for safe FS async calls with timeout
async function safeFS(method, params, options = {}) {
  const { timeout = 5000, fallback = null } = options;
  
  // Check if FS exists
  if (typeof FS === 'undefined') {
    console.warn(`FS not available for ${method}`);
    return fallback;
  }
  
  try {
    const result = await Promise.race([
      FS(method, params),
      new Promise((_, reject) => 
        setTimeout(() => reject(new Error(`FS ${method} timeout`)), timeout)
      )
    ]);
    return result;
  } catch (error) {
    console.warn(`FS ${method} failed:`, error.message);
    return fallback;
  }
}

// Usage
const sessionUrl = await safeFS('getSessionAsync', undefined, {
  timeout: 3000,
  fallback: null
});

await safeFS('trackEventAsync', {
  name: 'Page View',
  properties: { page: '/home' }
});

Pattern 2: Initialization Status Manager

// Track Fullstory initialization status
class CaptureStatusManager {
  constructor() {
    this.status = 'pending';
    this.sessionUrl = null;
    this.error = null;
    this.callbacks = [];
  }
  
  async initialize() {
    try {
      this.sessionUrl = await FS('getSessionAsync');
      this.status = 'ready';
      this.callbacks.forEach(cb => cb(this.sessionUrl));
    } catch (error) {
      this.status = 'failed';
      this.error = error;
    }
    
    return this.status === 'ready';
  }
  
  onReady(callback) {
    if (this.status === 'ready') {
      callback(this.sessionUrl);
    } else if (this.status === 'pending') {
      this.callbacks.push(callback);
    }
    // If failed, don't call
  }
  
  isReady() {
    return this.status === 'ready';
  }
  
  getSessionUrl() {
    return this.sessionUrl;
  }
}

// Global instance
const fsStatus = new CaptureStatusManager();

// Initialize once
fsStatus.initialize();

// Use anywhere
fsStatus.onReady((url) => {
  console.log('FS ready with session:', url);
});

Pattern 3: Analytics Queue with Fallback

// Queue analytics calls with sync fallback
class AnalyticsQueue {
  constructor() {
    this.useAsync = true;
    this.pending = [];
  }
  
  async track(eventName, properties) {
    if (this.useAsync) {
      try {
        await FS('trackEventAsync', {
          name: eventName,
          properties
        });
      } catch (error) {
        // Fall back to sync
        console.warn('Async tracking failed, using sync');
        this.useAsync = false;
        FS('trackEvent', { name: eventName, properties });
      }
    } else {
      FS('trackEvent', { name: eventName, properties });
    }
  }
  
  async identify(uid, properties) {
    if (this.useAsync) {
      try {
        await FS('setIdentityAsync', { uid, properties });
      } catch (error) {
        this.useAsync = false;
        FS('setIdentity', { uid, properties });
      }
    } else {
      FS('setIdentity', { uid, properties });
    }
  }
}

---

WHEN TO USE ASYNC VS SYNC

Use Async When:

Scenario	Why
Need session URL	Must wait for URL to be available
Error handling needed	Need to know if call failed
Sequential operations	Must ensure order of operations
Conditional logic	Need result to decide next action
Initialization checks	Need to know when FS is ready

Use Sync (Fire-and-Forget) When:

Scenario	Why
Simple event tracking	Don't need confirmation
Non-critical operations	Failure is acceptable
Performance critical paths	Don't want to add latency
Rapid-fire events	Queueing handles order
User-facing actions	Don't delay user experience

---

TROUBLESHOOTING

Promise Never Resolves

Symptom: await FS('methodAsync') hangs forever

Common Causes:

1. ❌ Fullstory script blocked by ad blocker
2. ❌ Script failed to load
3. ❌ Network issues preventing initialization

Solutions:

• ✅ Always use timeout wrapper
• ✅ Don't block critical paths
• ✅ Implement fallback behavior

Rejection Errors

Symptom: Promise rejects with error

Common Causes:

1. ❌ Missing _fs_org configuration
2. ❌ Unsupported browser
3. ❌ Organization over quota
4. ❌ Configuration error

Solutions:

• ✅ Check Fullstory setup
• ✅ Verify configuration
• ✅ Handle rejections gracefully

.catch() Not Working

Symptom: Errors not caught by .catch()

Common Causes:

1. ❌ Browser doesn't have native Promise
2. ❌ Fullstory's Promise-like doesn't implement catch

Solutions:

• ✅ Use async/await with try/catch
• ✅ Use .then() with error callback

---

KEY TAKEAWAYS FOR AGENT

When helping developers with Async Methods:

1. Always emphasize:

   • Use timeouts to prevent hanging
   • Handle rejections gracefully
   • Don't block critical paths on FS
   • Use try/catch, not .catch()

2. Common mistakes to watch for:

   • Blocking app startup on FS
   • Missing error handling
   • Using async when sync would work
   • Race conditions between calls
   • .catch() without polyfill check

3. Questions to ask developers:

   • Do you need the result?
   • Is this on a critical path?
   • What should happen if FS fails?
   • Is proper sequencing required?

4. Best practices to recommend:

   • Wrap in timeout for safety
   • Use sync for fire-and-forget
   • Graceful degradation always
   • Don't let analytics break core features

---

REFERENCE LINKS

• Asynchronous Methods: https://developer.fullstory.com/browser/asynchronous-methods/
• Get Session Details: https://developer.fullstory.com/browser/get-session-details/
• Callbacks and Delegates: https://developer.fullstory.com/browser/fullcapture/callbacks-and-delegates/

---

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