2026-05-06-documentation-overhaul
UXCam Documentation Overhaul — Implementation Plan
For Claude: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
Goal: Fix deprecated API references, add Android 3.10.0 + iOS 3.8.1 content, update changelogs, and improve quality/depth of React Native, Flutter, iOS, and cross-platform docs.
Architecture: Priority-driven approach — fix dangerous deprecated code examples first (what customers copy-paste), then add missing SDK version content, then improve thin/missing documentation pages. Each task is a logical commit.
Branch: v0.0.1-github (working branch) → PR to v1.1 (main)
Phase 1: Changelog Updates (Android 3.10.0, 3.9.0, 3.8.14, iOS 3.8.1)
Task 1: Update Android Changelog with 3.10.0, 3.9.0, and 3.8.14
Files:
- Modify:
docs/CHANGE LOG/android-changelog.md(add entries at top)
Step 1: Add Android 3.10.0 entry
Insert after the # UXCam Android Changelog heading and <br />, BEFORE the 3.9.1 entry:
### V. 3.10.0 - May 5, 2026
* **New**: Readable fragment screen tagging — fragment screens now show as `Activity/Fragment` (e.g. `MainActivity/HomeFragment`) instead of hex hashes (e.g. `MainActivity/0xa1b2c3`) in the dashboard timeline
* **New**: Opt-out available via `UXConfig.Builder.enableReadableFragmentNames(false)` for customers with analytics tied to legacy hash names
* **Note**: Existing occlusion rules using old hex hash names continue to work — the SDK matches against both names
* Feat (frame-sync): marker-based occlusion via `FrameSyncManager`
* Fix (occlusion): evict detached Compose occlusions on read
* Fix (capture): skip captures when activity view tree isn't laid out yet
* Fix (occlusion): key `autoByRoot` by `View` to prevent silent bucket loss
* Fix (logcat): use `ProcessBuilder` to process logcat data across all API levels
<br />Step 2: Replace the incomplete 3.9.0 entry
Replace:
### V. 3.9.0 - Mar 2026
* Interim release (bundled by React Native 6.0.15). Detailed notes pending.With:
### V. 3.9.0 - Mar 31, 2026
* Feat (identity): user identity is now in-memory only, decoupled from session restart
* Fix: simplified deferred startup lifecycle handling
* Fix (screenshot): centralized blur backend routing
* Fix: redact screen action details for occluded `EditText` views
* Fix: allow gesture tracking on auto-occluded `EditText` views
* Fix (Cordova): text fields get automatically occluded
* Fix: add support for blur radius greater than 25pxStep 3: Add 3.8.14 entry
Insert between the 3.9.0 and 3.8.13 entries:
<br />
### V. 3.8.14 - Mar 13, 2026
* Fix (response): prevent NPE when null data is received from server
* Fix: session cancelling due to `OutOfMemoryException`
* Fix: allow per-view occlusion to apply alongside full-screen occlusionStep 4: Commit
docs(changelog): add Android 3.10.0, expand 3.9.0, add 3.8.14
Task 2: Update iOS Changelog with 3.8.1
Files:
- Modify:
docs/CHANGE LOG/ios-changelog.md(add entry at top)
Step 1: Add iOS 3.8.1 entry
Insert after the # UXCam iOS Changelog heading, BEFORE the 3.8.0 entry:
### V. 3.8.1 - May 2026
* Optimized video recording flow — major internal refactoring of video pipeline architecture for improved performance and stability
* Added missing public headers: `UXCamOcclusionParameter` and `UXCamOcclusionScreen`
* Fix: video duration drift under backpressure
* Fix: sensitive animation occlusion handling for modal/popover presentation and dismissal
* Fix: image rotation issue for image-only mode
* Fix: Flutter late-attach and capture pipeline improvementsStep 2: Expand 3.7.12 entry
Replace:
### V. 3.7.12 - Apr 1, 2026
* No changelog published for this release.With:
### V. 3.7.12 - Apr 1, 2026
* Fixed crash related to `NSFileHandleOperationException`, `NSInvalidArgumentException`, internal logging, `setupDisplayLink`, and status bar orientation
* Updated occlusion metadataStep 3: Commit
docs(changelog): add iOS 3.8.1, expand 3.7.12
Phase 2: Deprecated API Fixes Across All Platforms
Task 3: Fix optIntoSchematicRecordings() in iOS docs
optIntoSchematicRecordings() in iOS docsFiles:
- Modify:
docs/Mobile SDK Installation/ios/index.md - Modify:
docs/Mobile SDK Installation/ios/swiftui-ios.md - Modify:
docs/Mobile SDK Installation/ios/screen-tagging/automatic-screen-tagging-swiftui-ios.md
Step 1: Fix iOS main index.md
In ios/index.md, replace line 133:
UXCam.optIntoSchematicRecordings()With:
UXCam.optIntoVideoRecordings()Also fix the JumpCallout anchor on line 15:
<JumpCallout to="#android-sdk--quickstart">Jump to Quickstart</JumpCallout>
→
<JumpCallout to="#quick-start-only-a-couple-of-lines-of-code">Jump to Quickstart</JumpCallout>
Step 2: Fix swiftui-ios.md
Search for optIntoSchematicRecordings and replace with optIntoVideoRecordings.
Step 3: Fix automatic-screen-tagging-swiftui-ios.md
Search for optIntoSchematicRecordings and replace with optIntoVideoRecordings. Also replace UXCamCore.optIntoSchematicRecordings() with UXCamCore.optIntoVideoRecordings() if present.
Step 4: Fix deprecated disableCrashHandling in crashes-anrs-copy-ios.md
In ios/advanced-configuration-and-apis-1/crashes-anrs-copy-ios.md, replace:
UXCam.disableCrashHandling(true)With a note:
// Using UXCamConfiguration (recommended)
let config = UXCamConfiguration(appKey: "YOUR_APP_KEY")
config.enableCrashHandling = false // Disabled (enabled by default)
UXCam.start(with: config)Step 5: Commit
docs(ios): replace deprecated optIntoSchematicRecordings with optIntoVideoRecordings
Task 4: Fix optIntoSchematicRecordings() in React Native docs
optIntoSchematicRecordings() in React Native docsFiles:
- Modify:
docs/Mobile SDK Installation/react-native/index.md - Modify:
docs/Mobile SDK Installation/react-native/set-up-the-sdk-and-start-recording-react-native.md - Modify:
docs/Mobile SDK Installation/react-native/troubleshooting-react-native-uxcam-react-native.md
Step 1: In each file, replace ALL occurrences of:
RNUxcam.optIntoSchematicRecordings();With:
RNUxcam.optIntoVideoRecordings(); // Enable video recording on iOSAnd replace any standalone:
UXCam.optIntoSchematicRecordings();With:
UXCam.optIntoVideoRecordings(); // Enable video recording on iOSStep 2: Also replace any enableImprovedScreenCapture: true in configuration objects
Add a comment noting it's no longer needed:
// enableImprovedScreenCapture is no longer needed — improved capture is always onOr simply remove the line from examples if it won't break the example.
Step 3: Commit
docs(react-native): replace deprecated schematic recording API calls
Task 5: Fix optIntoSchematicRecordings() in Flutter docs
optIntoSchematicRecordings() in Flutter docsFiles:
- Modify:
docs/Mobile SDK Installation/flutter/index.md - Modify:
docs/Mobile SDK Installation/flutter/advanced-configuration-and-apis/index.md - Modify:
docs/Mobile SDK Installation/flutter/advanced-configuration-and-apis/opt-in-opt-out-flutter.md - Modify:
docs/Mobile SDK Installation/flutter/troubleshooting-flutter.md
Step 1: In each file, replace ALL occurrences of:
FlutterUxcam.optIntoSchematicRecordings();With:
FlutterUxcam.optIntoVideoRecordings(); // Enable video recording on iOSStep 2: Commit
docs(flutter): replace deprecated schematic recording API calls
Task 6: Fix deprecated APIs in Cordova, NativeScript, and Xamarin docs
Files:
- Modify:
docs/Mobile SDK Installation/cordova/index.md - Modify:
docs/Mobile SDK Installation/nativescript/index.md - Modify:
docs/Mobile SDK Installation/xamarin-maui/index.md
Step 1: Cordova — replace all optIntoSchematicRecordings() references
In cordova/index.md, replace every:
UXCam.optIntoSchematicRecordings(); // Enable session video recording on iOSWith:
UXCam.optIntoVideoRecordings(); // Enable video recording on iOSAlso remove enableImprovedScreenCapture: true from configuration objects (no longer needed).
Step 2: NativeScript — same replacement
In nativescript/index.md, replace every:
NSUXCam.optIntoSchematicRecordings(); // Enable iOS screen recordingsWith:
NSUXCam.optIntoVideoRecordings(); // Enable video recording on iOSStep 3: Xamarin MAUI — replace and fix typo
In xamarin-maui/index.md:
a) Replace all UXCam.OptIntoSchematicRecordings() with UXCam.OptIntoVideoRecordings()
b) Fix the typo on line 47:
## SDK Installation - Xmarin Deprecated Verdsion
→
## SDK Installation — Xamarin (Deprecated)
c) Remove enableImprovedScreenCapture: true from config examples.
d) Replace the deprecated old help center link at the bottom:
> To stay up to date with the latest SDK improvements, visit [this link](https://help.uxcam.com/hc/en-us/articles/4404509626509--SDK-UPDATES).→
> To stay up to date with the latest SDK improvements, visit [our changelog](https://developer.uxcam.com/docs/xamarin-changelog).Step 4: Commit
docs(cross-platform): fix deprecated APIs in Cordova, NativeScript, Xamarin
Phase 3: Android 3.10.0 — Readable Fragment Screen Tagging Documentation
Task 7: Rewrite Fragment-Based Tagging Page for 3.10.0
Files:
- Modify:
docs/Mobile SDK Installation/android/screen-tagging/fragment-based-tagging-android.md
Step 1: Replace the entire file content (currently 45 thin lines) with comprehensive documentation
The new content should cover (source: Google Doc + SDK analysis):
---
title: Fragment-Based Screen Tagging
excerpt: 'How fragment screens appear in the UXCam timeline'
deprecated: false
hidden: false
metadata:
title: Fragment-Based Screen Tagging
description: >-
How UXCam tags fragment screens in Android apps, including the readable
fragment name feature introduced in SDK v3.10.0.
robots: index
next:
description: ''
---
# Fragment-Based Screen Tagging
Fragment-based tagging automatically tags each visible Fragment in your app so it appears as a named screen in the UXCam timeline. This is enabled from your **dashboard** — no code changes required.
## Enabling Fragment Tagging
Navigate to **App Settings → Data capture & recording → Additional settings** and enable **"Auto tag screen fragments on Android"**.
<Image align="center" width="80%" src="https://files.readme.io/d5659a9-FragmentTagging.png" />
> 📘 **Requires AndroidX.** Fragment-based tagging uses the AndroidX Fragment lifecycle. Classic `android.app.Fragment` is not supported.
---
## Readable Fragment Names (SDK v3.10.0+)
Starting with Android SDK **v3.10.0**, fragment screen tags show **human-readable names** instead of hex hashes.
### Before (SDK ≤ 3.9.x)
→ MainActivity → MainActivity/0x4f3a8b → MainActivity/0xc91e2d
Customers had to manually look up which Fragment a hash referred to.
### After (SDK 3.10.0+, default on)
→ MainActivity → MainActivity/HomeFragment → MainActivity/SettingsFragment
Names match the actual `Fragment` class in your app.
### How the SDK Picks the Fragment Name
The SDK uses a **dominant fragment** rule. When multiple fragments are visible, it picks the one that covers **≥ 50% of the screen**.
| Scenario | Result |
|----------|--------|
| Single fragment full-screen | Tag is that fragment: `MainActivity/HomeFragment` |
| Multi-pane / master-detail (40%/60%) | Tag is the larger fragment: `MainActivity/DetailFragment` |
| Small overlay fragment (< 50% of screen) | Tag is the activity: `MainActivity` |
| Dialog over fragment → dialog dismisses | Tag returns to the underlying fragment |
### Backward Compatibility with Occlusion Rules
Occlusion rules (set via dashboard or `UXCam.applyOcclusion(...)`) match against screen names. **Existing rules using old hex hash names continue to work.** The SDK computes the legacy hash alongside the readable name and matches against both.
- A rule `"occlude MainActivity/0xc91e2d"` still triggers even though the timeline now shows `MainActivity/SettingsFragment`
- You can update rules to readable names at your convenience — no rush, no breakage
### Opting Out (Legacy Behavior)
If your analytics or funnels depend on the old hash names, you can opt out:
```kotlin Kotlin
val config = UXConfig.Builder("YOUR_APP_KEY")
.enableReadableFragmentNames(false)
.build()
UXCam.startWithConfiguration(config)
UXConfig config = new UXConfig.Builder("YOUR_APP_KEY")
.enableReadableFragmentNames(false)
.build();
UXCam.startWithConfiguration(config);With opt-out, the timeline shows MainActivity/0xa1b2c3 as before, matching v3.9.x behavior exactly.
Recommendations
Best PracticeIf you enable fragment tagging, we recommend using only automatic screen name tagging (
enableAutomaticScreenNameTagging = true) to avoid mismatches between manually tagged and automatically tagged screens.
If you use manual tagging alongside fragment tagging, your manual tags will take precedence for the screens you tag, while the SDK will auto-tag the rest. Make sure your manual names are consistent with the automatic ones to avoid confusing analytics.
**Step 2: Commit**
docs(android): rewrite fragment tagging page with 3.10.0 readable names
---
## Phase 4: iOS Documentation Improvements
### Task 8: Expand iOS Configuration Options & Fix Quality Issues
**Files:**
- Modify: `docs/Mobile SDK Installation/ios/index.md`
**Step 1: Expand the configuration options section (after line 171)**
Replace the current 3-option section with comprehensive coverage. After the closing `</p>` of the `enableCrashHandling` option, add:
```markdown
<p style={{ fontSize: "18px" }}>
<code className="language-swift">enableMultiSessionRecord</code>
<br />
<em style={{ fontSize: "13px" }}>Enable or disable recording of multiple sessions. Default is true.</em>
</p>
<p style={{ fontSize: "18px" }}>
<code className="language-swift">enableIntegrationLogging</code>
<br />
<em style={{ fontSize: "13px" }}>Enable verbose integration logs in the console for debugging. Default is false. Recommended to enable only in DEBUG builds.</em>
</p>
<p style={{ fontSize: "18px" }}>
<code className="language-swift">enableNetworkLogging</code>
<br />
<em style={{ fontSize: "13px" }}>Capture per-request network data (URL, method, status code, timing) for timeline correlation. Available since v3.7.9. Default is false.</em>
</p>
<p style={{ fontSize: "18px" }}>
<code className="language-swift">occlusion</code>
<br />
<em style={{ fontSize: "13px" }}>Set a <code>UXCamOcclusion</code> object to pre-configure sensitive data masking at SDK start. See <a href="https://developer.uxcam.com/docs/sensitive-data-occlusion-ios">Sensitive Data Occlusion</a>.</em>
</p>
<p style={{ fontSize: "18px" }}>
<code className="language-swift">environment</code>
<br />
<em style={{ fontSize: "13px" }}>Set the app environment: <code>.alpha</code>, <code>.beta</code>, or <code>.release</code>. Useful for filtering sessions by build type on the dashboard.</em>
</p>
Step 2: Commit
docs(ios): expand configuration options, add network logging and environment
Task 9: Fill iOS Advanced Configuration Index Page
Files:
- Modify:
docs/Mobile SDK Installation/ios/advanced-configuration-and-apis-1/index.md
Step 1: Replace the empty file with an overview page:
---
title: Advanced Configuration and APIs
deprecated: false
hidden: false
metadata:
robots: index
---
# Advanced Configuration & APIs
This section covers advanced UXCam iOS SDK features beyond the basic integration.
<Cards columns={2}>
<Card title="Control Recording" href="control-recording-copy-1-ios" icon="fa-video">
Start, stop, and manage session recording programmatically.
</Card>
<Card title="Crashes & ANRs" href="crashes-anrs-copy-ios" icon="fa-bug">
How UXCam captures crash reports and ANR (App Not Responding) events.
</Card>
<Card title="Opt In / Opt Out" href="opt-in-opt-out-copy-ios" icon="fa-user-shield">
Give users control over session recording and comply with privacy regulations.
</Card>
<Card title="Pause & Resume Recording" href="pause-and-resume-video-recording-copy-ios" icon="fa-pause-circle">
Temporarily pause recording for sensitive flows without stopping the session.
</Card>
<Card title="Crash Symbolication" href="crash-symbolication-ios" icon="fa-code">
Set up dSYM upload for readable crash stack traces on the dashboard.
</Card>
<Card title="Integration Logging" href="integration-logging-guide-for-developers-copy-1-ios" icon="fa-terminal">
Enable verbose SDK logs for debugging your integration.
</Card>
<Card title="Report Handled Exceptions" href="report-handled-exceptions-copy-ios" icon="fa-exclamation-triangle">
Send caught exceptions to UXCam for visibility alongside session replays.
</Card>
</Cards>
---
## Configuration Reference
All options are set on the `UXCamConfiguration` object before calling `UXCam.start(with:)`:
```swift
let config = UXCamConfiguration(appKey: "YOUR_APP_KEY")
// Screen tagging
config.enableAutomaticScreenNameTagging = true // default: true
// Recording behavior
config.enableMultiSessionRecord = true // default: true
config.enableCrashHandling = true // default: true
config.enableAdvancedGestureRecognition = true // default: true
// Debugging
config.enableIntegrationLogging = false // default: false
// Network
config.enableNetworkLogging = false // default: false
// Environment
config.environment = .release // .alpha | .beta | .release
// Privacy (set at init time)
config.occlusion = UXCamOcclusion(/* ... */) // optional
UXCam.start(with: config)
Deprecation Note (v3.8.0+)The
optIntoSchematicRecordings()/optOutOfSchematicRecordings()methods are deprecated. UseoptIntoVideoRecordings()/optOutOfVideoRecordings()instead. Schematic vs video recording is now controlled exclusively from the dashboard.
**Step 2: Commit**
docs(ios): fill advanced configuration index with overview and config reference
---
## Phase 5: Android Documentation Improvements
### Task 10: Fill Android Advanced Configuration Index Page
**Files:**
- Modify: `docs/Mobile SDK Installation/android/advanced-configuration-and-apis/index.md`
**Step 1: Replace the empty file with an overview page (same pattern as iOS Task 9, adapted for Android):**
Include:
- Card navigation to all sub-pages
- Full `UXConfig.Builder` reference with all options including:
- `enableReadableFragmentNames(boolean)` (new in 3.10.0, default true)
- `enableExperimentalForceQuitVideoRecovery()` (experimental)
- `isVerboseLogEnabled(boolean)`
- `isVerboseDebugModeEnabled(boolean)`
- `honorFlagSecure(boolean)`
- `environment(Environment)`
- Deprecation notice for `startWithKey()` methods
**Step 2: Commit**
docs(android): fill advanced configuration index with overview and config reference
---
## Phase 6: React Native Documentation Improvements
### Task 11: Improve React Native Events and User Properties Pages
**Files:**
- Modify: `docs/Mobile SDK Installation/react-native/events.md`
- Modify: `docs/Mobile SDK Installation/react-native/user-properties.md`
**Step 1: Expand events.md**
Add:
- Event naming best practices (max length, allowed characters)
- Event property types and limits
- Complete TypeScript example with proper typing
- Difference between events and session properties
**Step 2: Expand user-properties.md**
Add:
- When to use user properties vs session properties
- Property type constraints
- Example identifying a user after login
- How properties appear on the dashboard
**Step 3: Commit**
docs(react-native): improve events and user properties documentation
---
### Task 12: Improve React Native Expo Installation Guide
**Files:**
- Modify: `docs/Mobile SDK Installation/react-native/expo-installation-react-native.md`
**Step 1: Expand the page**
Add:
- Why Expo Go doesn't work (native modules requirement)
- Full EAS Build setup with `eas.json` example
- Development build instructions
- Common Expo-specific errors and solutions
- Link to main React Native setup for configuration after install
**Step 2: Commit**
docs(react-native): expand Expo installation guide
---
## Phase 7: Flutter Documentation Improvements
### Task 13: Fix Flutter Screen Tagging Contradictions
**Files:**
- Modify: `docs/Mobile SDK Installation/flutter/screen-tagging-flutter/index.md`
- Modify: `docs/Mobile SDK Installation/flutter/screen-tagging-flutter/navigator-route-tracking-flutter.md`
**Step 1: Clarify the relationship between automatic tagging and navigator observer**
The docs currently say both "use automatic tagging" and "disable automatic tagging" in different places. Clarify:
- `enableAutomaticScreenNameTagging: true` → SDK tags based on native view hierarchy (works for UIKit/Activity)
- `FlutterUxcamNavigatorObserver` → tracks Flutter `Navigator` route changes (recommended for Flutter apps)
- Best practice: use the Navigator Observer with `enableAutomaticScreenNameTagging: false` for Flutter apps
**Step 2: Commit**
docs(flutter): clarify screen tagging approach and resolve contradictions
---
### Task 14: Improve Flutter Troubleshooting Page
**Files:**
- Modify: `docs/Mobile SDK Installation/flutter/troubleshooting-flutter.md`
**Step 1: Fix the incorrect Flutter version reference**
The page says "Flutter SDK version 3.10+ is installed" — this refers to the Flutter framework version, but could be confused with UXCam SDK version. Clarify which version is meant.
**Step 2: Add common Flutter-specific issues:**
- Impeller rendering compatibility
- `PlatformView` occlusion behavior
- Hot reload vs hot restart behavior with UXCam
- iOS archive/release build issues
- ProGuard rules for Android release builds
**Step 3: Commit**
docs(flutter): improve troubleshooting with common Flutter-specific issues
---
## Phase 8: Cross-Platform Changelog Stubs
### Task 15: Replace React Native and Flutter Changelog Stubs
**Files:**
- Modify: `docs/Mobile SDK Installation/react-native/react-native-sdk-change-log-react-native.md`
- Modify: `docs/Mobile SDK Installation/flutter/flutter-sdk-changelog-flutter.md`
**Step 1: Replace the empty stub cards with actual content or a proper redirect**
Option A (preferred): Add the 5 most recent versions inline + link to full changelog
Option B: Make the redirect card more useful with latest version info
**Step 2: Commit**
docs(changelog): replace empty changelog stubs with recent version summaries
---
## Phase 9: Cordova / NativeScript / Xamarin Quality Pass
### Task 16: Fix Cordova OkHttp Troubleshooting and Links
**Files:**
- Modify: `docs/Mobile SDK Installation/cordova/index.md`
**Step 1: Update the old help center link**
Replace the outdated `help.uxcam.com` link with the developer docs changelog link.
**Step 2: Verify OkHttp version recommendation is still current**
The doc recommends `okhttp:4.9.3` — update to a more recent version if appropriate (e.g., `4.12.0`).
**Step 3: Commit**
docs(cordova): update links and dependency versions
---
### Task 17: Fix NativeScript Outdated Links
**Files:**
- Modify: `docs/Mobile SDK Installation/nativescript/index.md`
**Step 1: Remove the outdated help center link and emoji usage**
Clean up the page formatting for consistency with other platform pages.
**Step 2: Commit**
docs(nativescript): clean up formatting and outdated links
---
## Execution Order & Dependencies
Phase 1 (Tasks 1-2) → Changelogs — no dependencies, do first Phase 2 (Tasks 3-6) → Deprecated APIs — no dependencies, can parallel Phase 3 (Task 7) → Android 3.10.0 content — depends on Task 1 (changelog) Phase 4 (Tasks 8-9) → iOS improvements — depends on Task 3 (deprecated fix) Phase 5 (Task 10) → Android improvements — no dependency Phase 6 (Tasks 11-12)→ React Native — depends on Task 4 Phase 7 (Tasks 13-14)→ Flutter — depends on Task 5 Phase 8 (Task 15) → Changelog stubs — no dependency Phase 9 (Tasks 16-17)→ Cross-platform — depends on Task 6
**Parallelizable groups:**
- Tasks 1 + 2 (both changelogs)
- Tasks 3 + 4 + 5 + 6 (all deprecated API fixes, different platforms)
- Tasks 7 + 8 + 9 + 10 (new content, different platforms)
- Tasks 11 + 12 + 13 + 14 (quality improvements, different platforms)
- Tasks 15 + 16 + 17 (stubs and cross-platform fixes)
**Total estimated files touched:** ~25-30
**Total commits:** 17Updated about 12 hours ago
