Comprehensive guide for implementing Fullstory's Asynchronous API methods (Async suffix variants) for web applications. Teaches proper Promise handling, await patterns, error handling, and when to use async vs fire-and-forget methods. Includes detailed good/bad examples for initialization waiting, session URL retrieval, and conditional flows to help developers handle Fullstory's asynchronous nature correctly.
Scanned 2/12/2026
Install via CLI
Skills Directoryopenskills install majiayu000/claude-skill-registry---
name: fullstory-async-methods
version: v2
description: Comprehensive guide for implementing Fullstory's Asynchronous API methods (Async suffix variants) for web applications. Teaches proper Promise handling, await patterns, error handling, and when to use async vs fire-and-forget methods. Includes detailed good/bad examples for initialization waiting, session URL retrieval, and conditional flows to help developers handle Fullstory's asynchronous nature correctly.
related_skills:
- fullstory-observe-callbacks
- fullstory-identify-users
- fullstory-analytics-events
- fullstory-capture-control
---
# 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 `await`ed
- 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
```javascript
// 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
```javascript
// 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
```javascript
// 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
```javascript
// 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
```javascript
// 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
```javascript
// 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
```javascript
// 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
```javascript
// 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:**
```javascript
// 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
```javascript
// 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:**
```javascript
// 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
```javascript
// 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:**
```javascript
// 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
```javascript
// 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:**
```javascript
// 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
```javascript
// 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:**
```javascript
// 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
```javascript
// 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
```javascript
// 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
```javascript
// 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._
No comments yet. Be the first to comment!
