SessionReplaySDK

KO | EN

gitlite — search

#javascript #python #hacktoberfest #react #ai #typescript #llm #go #golang #android #machine-learning #rust #deep-learning #linux

SessionReplaySDK

★ 9 Open GitHub ↗

📹 Lightweight iOS SDK for recording user sessions with video, touch events, console logs & network requests. Privacy-first with automatic PII masking. Pure Swift, zero dependencies.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# SessionReplaySDK

A powerful, privacy-focused session replay SDK for iOS applications.

Capture user sessions with video recording, touch visualization, console logs, and network requests—all synchronized for powerful debugging and UX analysis.

A complete demo application <a href="https://github.com/AlmoutasemNabil/SessionReplayDemo">SessionReplayDemo</a>

---

## Features

| Feature | Description |
|---------|-------------|
| **Video Recording** | H.264 encoded screen capture with configurable quality and frame rate |
| **Touch Visualization** | Record and overlay touch events with visual indicators |
| **Console Log Capture** | Automatically intercept `print()`, `NSLog()`, and stderr |
| **Network Tracking** | Monitor all HTTP/HTTPS requests (works with Alamofire SSL pinning) |
| **User Identification** | Attach user info (userId, email, custom data) to sessions |
| **Auto Start/Stop** | Configurable automatic session lifecycle management |
| **Crash Recovery** | Periodic checkpoints to recover sessions after crashes |
| **App Groups** | Share session data between app and extensions |
| **Screen Transitions** | Track navigation flow between screens |
| **Synchronized Timeline** | All events timestamped for video sync playback |
| **Local Storage** | Save sessions locally with JSON metadata |
| **Cloud Upload** | Multipart form data upload to your backend |
| **Privacy Controls** | Redact headers, exclude URLs, sanitize logs |
| **SwiftUI & UIKit** | Full support with view modifiers and components |

## Installation

### Swift Package Manager

**Xcode:**
1. Go to **File > Add Package Dependencies**
2. Enter: `https://github.com/AlmoutasemNabil/SessionReplaySDK`
3. Select version and add to your target

**Package.swift:**
```swift
dependencies: [
    .package(url: "https://github.com/AlmoutasemNabil/SessionReplaySDK", from: "0.2.0")
]
```

## Quick Start

### 1. Configure on App Launch

```swift
import SessionReplaySDK

@main
struct MyApp: App {
    init() {
        var config = SessionReplayConfig()
        config.captureFrameRate = 10
        config.jpegCompressionQuality = 0.7
        config.autoStartOnLaunch = false    // Manual control
        config.enableCrashRecovery = true   // Save on crash
        config.debugLogging = false         // Disable in production

SessionReplaySDK.configure(
            videoConfig: config,
            logConfig: SessionLoggerConfig()
        )
    }

var body: some Scene {
        WindowGroup {
            ContentView()
        }
    }
}
```

### 2. Logs-Only Mode (No Video)

For lightweight logging without video recording:

```swift
var config = SessionReplayConfig()
config.enableVideoRecording = false  // Disable video, capture logs only

SessionReplaySDK.configure(
    videoConfig: config,
    logConfig: SessionLoggerConfig()
)

// Start/stop works the same way
SessionReplaySDK.start()
// ... session captures console logs and network requests only
SessionReplaySDK.stop()
```

### 3. Identify Users

```swift
// After user logs in
SessionReplaySDK.identifyUser(
    userId: "user_123",
    email: "user@example.com",
    name: "John Doe",
    additionalInfo: ["plan": "premium", "branchId": "branch_456"]
)

// Or set custom info directly
SessionReplaySDK.setUserInfo([
    "userId": "123",
    "email": "user@example.com",
    "customField": "value"
])
```

### 3. Start/Stop Recording

```swift
// Start recording
SessionReplaySDK.startSession()

// Stop recording
SessionReplaySDK.stopSession()

// Check status
if SessionReplaySDK.isRecording {
    print("Recording in progress...")
}
```

### 4. Track Screens (SwiftUI)

```swift
struct HomeView: View {
    var body: some View {
        NavigationView {
            // Your content
        }
        .trackScreen("HomeScreen")
    }
}
```

### 5. Custom Logging

```swift
SessionReplaySDK.debug("Debug: User opened settings")
SessionReplaySDK.info("Info: Purchase completed")
SessionReplaySDK.warning("Warning: Low storage")
SessionReplaySDK.error("Error: Network timeout")
```

### 6. Upload Sessions

```swift
// Configure endpoint
SessionReplaySDK.configureUpload(
    baseURL: URL(string: "https://api.yourserver.com/sessions")!,
    apiKey: "your-api-key"
)

// Upload specific session
SessionReplaySDK.uploadSession(sessionId: "abc-123") { result in
    switch result {
    case .success(let response):
        print("Uploaded: \(response.sessionId)")
    case .failure(let error):
        print("Failed: \(error)")
    }
}

// Upload all sessions
SessionReplaySDK.uploadAllSessions { results in
    let successful = results.filter { $0.1.isSuccess }.count
    print("Uploaded \(successful)/\(results.count) sessions")
}
```

## Configuration

### Video (SessionReplayConfig)

| Option | Default | Description |
|--------|---------|-------------|
| `enableVideoRecording` | `true` | Enable video recording (false for logs-only mode) |
| `captureFrameRate` | `1` | Frames per second (1-30) |
| `jpegCompressionQuality` | `0.3` | JPEG quality (0.0-1.0) |
| `captureScale` | `1.0` | Resolution scale (0.25-1.0) |
| `videoBitrate` | `75,000` | H.264 bitrate in bps |
| `captureTouches` | `true` | Record touch events |
| `showTouchIndicators` | `true` | Draw touch dots on video |
| `maskSensitiveViews` | `true` | Mask marked sensitive views |
| `sensitiveViewMaskColor` | `.gray` | Color for masked areas |
| `autoMaskTextFields` | `true` | Auto-mask text inputs |
| `autoMaskSecureTextFields` | `true` | Auto-mask password fields |
| `autoMaskViewClasses` | `[]` | Custom classes to auto-mask |
| `maxStorageSize` | `50MB` | Max local storage |
| `storageDirectory` | Documents | Custom storage location |

### Auto Start/Stop (SessionReplayConfig)

| Option | Default | Description |
|--------|---------|-------------|
| `autoStartOnLaunch` | `false` | Start recording on app launch |
| `autoStopOnBackground` | `true` | Stop when app enters background |
| `autoStopOnTerminate` | `true` | Emergency save on terminate |
| `enableCrashRecovery` | `true` | Save checkpoints periodically |
| `crashRecoveryInterval` | `5.0` | Seconds between checkpoints |
| `debugLogging` | `true` | Print debug logs to console |

### Logging (SessionLoggerConfig)

| Option | Default | Description |
|--------|---------|-------------|
| `captureConsoleLogs` | `true` | Capture stdout/stderr |
| `captureNetworkRequests` | `true` | Intercept URLSession |
| `minimumLogLevel` | `.debug` | Minimum capture level |
| `maxLogMessageLength` | `2000` | Truncate long messages |
| `maxBodySize` | `100KB` | Max request/response body |
| `redactedHeaders` | `[auth, cookie...]` | Headers to redact |
| `excludedURLPatterns` | `[]` | URL regex patterns to skip |
| `logSanitizer` | `nil` | Custom sanitization closure |
| `excludeSDKLogs` | `true` | Exclude SDK internal logs from session data |

### Upload (SessionUploadConfig)

| Option | Default | Description |
|--------|---------|-------------|
| `baseURL` | Required | Your upload endpoint |
| `apiKey` | `nil` | Bearer token auth |
| `additionalHeaders` | `[:]` | Custom headers |
| `maxRetries` | `3` | Retry on failure |
| `timeoutInterval` | `120s` | Request timeout |
| `deleteAfterUpload` | `false` | Remove local files |

## App Group Support

Share session data between your main app and extensions:

```swift
// Configure with App Group
SessionReplaySDK.configureWithAppGroup(
    "group.com.yourcompany.yourapp",
    videoConfig: config,
    logConfig: logConfig
)

// Or manually set storage directory
var config = SessionReplayConfig()
if let containerURL = FileManager.default.containerURL(forSecurityApplicationGroupIdentifier: "group.com.yourapp") {
    config.storageDirectory = containerURL.appendingPathComponent("SessionReplays", isDirectory: true)
}
SessionReplaySDK.configure(videoConfig: config)
```

## User Identification

Attach user info to sessions for easier debugging:

```swift
// Simple identification
SessionReplaySDK.identifyUser(
    userId: "user_123",
    email: "user@example.com",
    name: "John Doe"
)

// With additional custom data
SessionReplaySDK.identifyUser(
    userId: "cashier_456",
    email: "cashier@foodics.com",
    additionalInfo: [
        "branchId": "branch_123",
        "role": "cashier",
        "shiftId": "shift_789"
    ]
)

// Set individual values
SessionReplaySDK.setUserInfo(key: "subscriptionTier", value: "premium")

// Clear on logout
SessionReplaySDK.clearUserInfo()

// Access current info
let currentUser = SessionReplaySDK.userInfo
```

User info is saved in both `metadata.userInfo` and root `userInfo` in the session JSON.

## Crash Recovery

The SDK automatically saves session checkpoints:

```swift
var config = SessionReplayConfig()
config.enableCrashRecovery = true      // Enable checkpoints
config.crashRecoveryInterval = 3.0     // Save every 3 seconds

SessionReplaySDK.configure(videoConfig: config)

// Check for incomplete sessions after app restart
let incompleteSessions = SessionReplaySDK.recoverIncompleteSessions()
for sessionId in incompleteSessions {
    print("Found incomplete session: \(sessionId)")
    // Video segments may be available even if session didn't complete
}
```

## Session Data Format

```json
{
  "sessionId": "550e8400-e29b-41d4-a716-446655440000",
  "startTime": "2025-01-27T10:30:00Z",
  "endTime": "2025-01-27T10:35:00Z",
  "durationMs": 300000,
  "frameCount": 3000,
  "videoSegments": ["session_segment0.mp4"],
  "userInfo": {
    "userId": "user_123",
    "email": "user@example.com",
    "branchId": "branch_456"
  },
  "touches": [
    {"timestamp": 1500, "location": {"x": 200, "y": 400}, "phase": 0}
  ],
  "logs": [
    {"timestamp": 2000, "level": "info", "message": "Button tapped", "source": "stdout"}
  ],
  "networkRequests": [
    {"timestamp": 3000, "method": "GET", "url": "https://api.example.com/data", "statusCode": 200, "duration": 150}
  ],
  "screenTransitions": [
    {"timestamp": 0, "screenName": "HomeScreen"}
  ],
  "metadata": {
    "appVersion": "1.0.0",
    "osVersion": "17.0",
    "deviceModel": "iPhone15,2",
    "locale": "en_US",
    "userInfo": {
      "userId": "user_123",
      "email": "user@example.com"
    }
  }
}
```

## Built-in Components

### SwiftUI

```swift
// Recording controls
RecordingControlView()

// Sessions list with upload
SessionsListView()

// Activity timeline (live during recording)
LiveActivityView()

// Activity timeline (for completed sessions)
ActivityTimelineView(session: selectedSession)

// Session player
SessionReplayViewer(session: selectedSession)

// Screen tracking modifier
.trackScreen("ScreenName")

// Touch indicators overlay
.withTouchIndicators()

// Mark sensitive content
.sensitiveContent()
```

### UIKit

```swift
// Base view controller with tracking
class MyVC: SessionReplayViewController {
    override var screenName: String { "MyScreen" }
}

// Debug view controller
let debugVC = SessionReplayDebugViewController()
present(debugVC, animated: true)

// Mark sensitive views
passwordField.markAsSensitive()
```

## Network Capture

The SDK captures all URLSession-based network requests, including:

- Direct URLSession usage
- Alamofire (including custom sessions with SSL pinning)
- FNetwork and other URLSession-based libraries

No additional configuration needed—network capture works automatically.

## Upload API

The SDK sends multipart form data:

| Field | Type | Description |
|-------|------|-------------|
| `sessionId` | String | Session identifier |
| `video` | File | MP4 video file |
| `metadata` | File | JSON metadata file |

**Expected Response:**
```json
{
  "sessionId": "...",
  "videoURL": "https://...",
  "metadataURL": "https://...",
  "message": "Success"
}
```

**Testing Upload:**
- Use [webhook.site](https://webhook.site) for instant testing
- Use [requestbin.com](https://requestbin.com) as alternative
- Or `https://postman-echo.com/post` for echo testing

## Privacy & Security

### Sensitive Data Masking

The SDK automatically masks sensitive content in screen recordings:

**Automatic Masking (enabled by default):**
- Secure text fields (password inputs)
- Regular text fields and text views
- Views marked with `markAsSensitive()` or `.sensitiveContent()`

**Configuration Options:**
```swift
var config = SessionReplayConfig()
config.maskSensitiveViews = true          // Enable/disable masking
config.sensitiveViewMaskColor = .gray     // Mask color
config.autoMaskTextFields = true          // Auto-mask UITextField/UITextView
config.autoMaskSecureTextFields = true    // Auto-mask password fields
config.autoMaskViewClasses = ["CreditCardView"]  // Custom classes to mask
```

**Manual Masking - UIKit:**
```swift
// Mark any UIView as sensitive
passwordField.markAsSensitive()
creditCardView.markAsSensitive()

// Check if view is marked
if myView.isSensitive { ... }
```

**Manual Masking - SwiftUI:**
```swift
// Mark any SwiftUI view as sensitive
SecretDataView()
    .sensitiveContent()

// With custom mask color
PaymentForm()
    .sensitiveContent(maskColor: .black)
```

### Additional Privacy Features

- **Header Redaction**: Authorization, Cookie, API keys auto-redacted from network logs
- **URL Exclusion**: Regex patterns to exclude specific endpoints
- **Log Sanitization**: Custom closure for PII removal
- **Local-First**: All data stored locally, upload is opt-in
- **No Dependencies**: Pure Swift, no third-party tracking code

## Architecture

```
SessionReplaySDK/
├── Core/
│   ├── Models.swift              # Data structures
│   ├── SessionReplayManager.swift # Main controller
│   └── VideoWriter.swift         # H.264 encoding
├── Logging/
│   ├── SessionLogger.swift       # Console capture
│   └── NetworkInterceptor.swift  # URL monitoring
├── Upload/
│   └── SessionUploader.swift     # Cloud upload
├── Integration/
│   ├── SwiftUIIntegration.swift  # SwiftUI support
│   └── UIKitIntegration.swift    # UIKit support
└── SessionReplaySDK.swift        # Public facade
```

## Changelog

### Version 0.2.0
- **User Identification**: New `identifyUser()` and `setUserInfo()` APIs to attach user data to sessions
- **App Group Support**: Configure custom storage directory for sharing data between app and extensions
- **Auto Start/Stop**: New config options for automatic session lifecycle management
- **Crash Recovery**: Periodic checkpoints to recover sessions after crashes
- **Network Capture Improvements**: Works with all URLSession-based networking including Alamofire with SSL pinning
- **Activity Timeline Views**: New `LiveActivityView` and `ActivityTimelineView` SwiftUI components
- **Debug Logging Control**: New `debugLogging` config to reduce console noise in production
- **Removed Verbose Touch Logging**: Touch began/ended events no longer spam the console

### Version 0.1.0
- Initial release
- Video recording with H.264 encoding
- Touch event capture and visualization
- Console log interception
- Network request monitoring
- SwiftUI and UIKit integration
- Cloud upload support

## Contributing

We welcome contributions!

1. Fork the repository
2. Create feature branch: `git checkout -b feature/amazing`
3. Commit changes: `git commit -m 'Add amazing feature'`
4. Push: `git push origin feature/amazing`
5. Open Pull Request

Please include tests and update documentation.

## Requirements

- iOS 15.0+
- Swift 5.9+
- Xcode 15.0+

## Support

- **Issues**: [GitHub Issues](https://github.com/AlmoutasemNabil/SessionReplaySDK/issues)
- **Discussions**: [GitHub Discussions](https://github.com/AlmoutasemNabil/SessionReplaySDK/discussions)

---

## 📄 License

This project is licensed under the **MIT License** - see the [LICENSE](LICENSE) file for details.

---

**Made with ❤️ by [AlmoutasemNabil](https://github.com/AlmoutasemNabil)**

⭐ **Star this repo if you find it helpful!**

</div>

SessionReplaySDK

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README