Fullstory Asynchronous Methods API

Implementation Files: This document covers core concepts. For code examples, see:

• SKILL-WEB.md — JavaScript/TypeScript (Browser)
• SKILL-MOBILE.md — Platform differences for iOS, Android, Flutter, React Native

Note: The Async suffix pattern is specific to the web/browser SDK. Mobile SDKs use different asynchronous mechanisms (completion handlers, delegates, listeners).

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

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:

Return Values

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)

When to Use Async vs Sync

Use Async When:

Use Sync (Fire-and-Forget) When:

Best Practices

1. Always Use Timeouts

// Prevent hanging if Fullstory is blocked
const result = await Promise.race([
  FS('getSessionAsync'),
  new Promise((_, reject) => 
    setTimeout(() => reject(new Error('Timeout')), 5000)
  )
]);

2. Don't Block Critical Paths

// BAD: App hangs if FS blocked
await FS('getSessionAsync');
renderApp();

// GOOD: App starts immediately
renderApp();
FS('getSessionAsync').then(url => enrichWithSession(url));

3. Use try/catch, Not .catch()

// GOOD: Works reliably
try {
  const url = await FS('getSessionAsync');
} catch (error) {
  // Handle error
}

// RISKY: .catch() may not work in older browsers
FS('getSessionAsync')
  .then(url => {})
  .catch(err => {});  // May fail silently

4. Handle Sequencing Correctly

// GOOD: Sequential operations
await FS('setIdentityAsync', { uid: user.id });
await FS('trackEventAsync', { name: 'Login' });

// BAD: Race condition
FS('setIdentityAsync', { uid: user.id });
FS('trackEventAsync', { name: 'Login' });  // May fire before identity!

Troubleshooting

Promise Never Resolves

Rejection Errors

.catch() Not Working

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. Platform routing:

   • Web (JavaScript/TypeScript) → See SKILL-WEB.md
   • Mobile platforms → See SKILL-MOBILE.md for platform-specific patterns

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/