fullstorydev Fullstory Capture Control API (Shutdown/Restart)
Implementation Files: This document covers core concepts. For code examples, see:
- SKILL-WEB.md — JavaScript/TypeScript (Browser)
- SKILL-MOBILE.md — iOS, Android, Flutter, React Native
Overview
Fullstory's Capture Control APIs allow developers to programmatically stop and restart session capture. This provides fine-grained control over when Fullstory records sessions, which is useful for:
- Performance Optimization: Pause capture during resource-intensive operations
- Privacy Zones: Stop capture in sensitive areas
- Resource Management: Reduce overhead when not needed
- Testing: Control capture during development/testing
- Conditional Recording: Only capture certain user journeys
Core Concepts
Shutdown vs Restart
| Method | Effect | Use Case |
|---|---|---|
shutdown |
Stops capture, ends session | End recording permanently or temporarily |
restart |
Resumes capture, new session | Resume after shutdown |
Session Behavior
Active Session → shutdown() → Capture Stopped (session ends)
↓
restart()
↓
New Session Begins
Key Behaviors
| Behavior | Description |
|---|---|
| New session on restart | Restart creates a new session, not continues old one |
| Identity cleared | If identified before shutdown, re-identify after restart |
| Properties cleared | Page/element properties reset on restart |
| Async available (Web) | Web has async versions (shutdownAsync, restartAsync) |
API Methods by Platform
| Platform | Shutdown | Restart |
|---|---|---|
| Web | FS('shutdown') |
FS('restart') |
| iOS | FS.shutdown() |
FS.restart() |
| Android | FS.shutdown() |
FS.restart() |
| Flutter | FS.shutdown() |
FS.restart() |
| React Native | FullStory.shutdown() |
FullStory.restart() |
When to Use
✅ Good Use Cases
| Scenario | Why Use |
|---|---|
| Privacy zones (payment forms, sensitive data) | Don't capture sensitive input |
| Heavy data processing | Free up resources |
| User-requested privacy mode | Respect user preference |
| Internal/admin screens | Not useful for analytics |
| Development/testing | Avoid test data |
❌ Avoid Using For
| Scenario | Better Alternative |
|---|---|
| Consent management | Use consent APIs instead |
| User logout | Use anonymize instead |
| Page navigation | Capture persists across pages |
| Temporary pauses | Consider if really needed |
Critical: Re-identification After Restart
Identity is cleared when you shutdown. After calling restart(), you must re-identify the user:
1. User is identified → FS knows who they are
2. shutdown() called → Session ends
3. restart() called → NEW session starts, user is ANONYMOUS
4. identify() called → User is known again
Common mistake: Forgetting to re-identify after restart, resulting in anonymous sessions.
Best Practices
1. Always Re-identify After Restart
Save user information before shutdown and re-identify after restart.
2. Use Consent API for Consent
Don't use shutdown/restart for consent management. Use the dedicated consent APIs.
3. Pair Shutdown with Restart
If you shutdown in one place, ensure there's a path to restart:
- Entering privacy zone → shutdown
- Leaving privacy zone → restart + re-identify
4. Debounce Rapid Changes
Avoid calling shutdown/restart in rapid succession. This creates fragmented sessions.
5. Use Sync in Unload Handlers
On page/app close, use synchronous versions as async may not complete.
Common Patterns
Privacy Zone Pattern
1. User enters sensitive area
2. Track event "Entering Privacy Zone"
3. Save user identity
4. Call shutdown()
5. User exits sensitive area
6. Call restart()
7. Re-identify user
8. Track event "Exited Privacy Zone"
Conditional Capture Pattern
1. User logs in
2. Check capture rules (plan type, role, etc.)
3. If should capture: restart() + identify()
4. If should not capture: shutdown()
5. On user change: re-evaluate
Development Toggle Pattern
1. Check for dev flag (URL param, localStorage)
2. If dev mode: shutdown()
3. Allow toggle via keyboard shortcut or console
4. Persist preference for session
Troubleshooting
Sessions Not Resuming After Restart
| Cause | Solution |
|---|---|
| Fullstory blocked by ad blocker | Check browser console for errors |
| Page excluded from capture | Verify page isn't in exclusion list |
| User on excluded segment | Check targeting rules |
User Anonymous After Restart
| Cause | Solution |
|---|---|
| Forgot to re-identify | Always call identify after restart |
| User data not saved | Save user before shutdown |
Fragmented Sessions
| Cause | Solution |
|---|---|
| Rapid shutdown/restart | Add debouncing |
| Multiple components calling | Centralize capture control |
| Missing state tracking | Track isCapturing state |
Key Takeaways for Agent
When helping developers with Capture Control:
Always emphasize:
- Re-identify after restart (identity is lost)
- Use sync version in unload handlers
- Debounce rapid state changes
- Use consent API for consent, not shutdown
Common mistakes to watch for:
- Forgetting to re-identify
- Using shutdown for consent
- Rapid shutdown/restart cycles
- No restart logic after shutdown
Questions to ask developers:
- Why do you need to pause capture?
- Is this for privacy/consent or performance?
- How will you re-identify after restart?
- What triggers the restart?
Platform routing:
- Web (JavaScript/TypeScript) → See SKILL-WEB.md
- iOS (Swift/SwiftUI) → See SKILL-MOBILE.md § iOS
- Android (Kotlin) → See SKILL-MOBILE.md § Android
- Flutter (Dart) → See SKILL-MOBILE.md § Flutter
- React Native → See SKILL-MOBILE.md § React Native
Reference Links
- Web Capture Data: https://developer.fullstory.com/browser/fullcapture/capture-data/
- iOS Capture: https://developer.fullstory.com/mobile/ios/capture-data/
- Android Capture: https://developer.fullstory.com/mobile/android/capture-data/
- Flutter Capture: https://developer.fullstory.com/mobile/flutter/capture-data/
- React Native Capture: https://developer.fullstory.com/mobile/react-native/capture-data/