# Enable session replay on iOS

## Overview

Follow this guide to enable [Session Replay](https://coralogix.com/docs/user-guides/rum/product-features/session-replay/index.md) for Real User Monitoring (RUM) in your iOS app.

Session Replay captures a visual sequence of user interactions in your app by recording periodic screenshots. This allows you to analyze what the user saw before, during, and after an issue — helping you quickly pinpoint the source of errors, performance slowdowns, or unexpected behavior. Use Session Replay to recreate the user experience and better understand the context behind each session.

## Prerequisites

Before enabling Session Replay, you must install and initialize the [Coralogix iOS RUM SDK](https://coralogix.com/docs/user-guides/rum/sdk-installation/apple/ios/index.md) in your app.

Note

The Session Replay feature extends the iOS RUM SDK, and must be initialized after the base SDK setup. Attempting to initialize Session Replay without the base SDK will result in an initialization error.

## Session Replay by default

- Captures screenshots periodically, every 10 seconds.
- Masks all images, faces, and credit card information.

You can customize these defaults using the [options](#options-reference) below.

## Configure and initialize

Use the `SessionReplayOptions` class to configure capture behavior, privacy masking, and sampling.

### Example

```swift
let options = SessionReplayOptions(
    captureTimeInterval: 5.0,
    maskText: [".*"],           // Mask all visible text
    maskAllImages: true,           // Mask all images
    maskFaces: true,            // Mask detected faces
    autoStartSessionRecording: true
)

SessionReplay.initializeWithOptions(sessionReplayOptions: options)
```

## Options reference

Configuration fields for `SessionReplayOptions`:

| Option                       | Type          | Description                                                                         | Default |
| ---------------------------- | ------------- | ----------------------------------------------------------------------------------- | ------- |
| `autoStartSessionRecording`  | `Bool`        | Start recording automatically                                                       | `false` |
| `captureTimeInterval`        | `Double`      | Seconds between captures. Min: `1.0`                                                | `10.0`  |
| `captureScale`               | `CGFloat`     | Screenshot resolution scale factor. Lower values reduce image size and memory usage | `2.0`   |
| `captureCompressionQuality`  | `CGFloat`     | Image compression (`0.0`-`1.0`). Lower values reduce fidelity and file size         | `1.0`   |
| `sessionRecordingSampleRate` | `Int` (0–100) | % of sessions to capture                                                            | `100`   |
| `maskText`                   | `[String]?`   | Text patterns to redact (strings or regex)                                          | `nil`   |
| `maskImages`                 | `Bool`        | Mask all credit card images                                                         | `false` |
| `maskAllImages`              | `Bool`        | Mask all images                                                                     | `true`  |
| `maskFaces`                  | `Bool`        | Mask detected faces                                                                 | `false` |
| `creditCardPredicate`        | `[String]?`   | Custom patterns to detect credit card-related images                                | `nil`   |

## Image capture triggers

Screenshots are captured during session replay in the following cases:

- Periodically, based on the configured `captureTimeInterval` (default: every 10 seconds).
- When the user taps the screen.
- When the user navigates between screens or views.
- When an error or crash occurs.
- When a screen capture event is triggered via [`SessionReplay.shared.captureEvent()`](#manually-capture-screen).

This hybrid approach ensures that relevant context is captured even between interval windows.

## Start and stop recording

If `autoStartSessionRecording` is `false`, use the following methods to manually control recording:

```swift
SessionReplay.shared.startRecording()
SessionReplay.shared.stopRecording()
```

## Manually capture screen

Use `captureEvent` to manually capture a specific moment in the session.

### Example

```swift
_ = SessionReplay.shared.captureEvent()
```

## Privacy and masking

Coralogix provides flexible masking options to help you meet privacy requirements:

- **Text masking**: Use string or regex patterns in `maskText` to redact on-screen text.
- **Image masking**: Use `maskAllImages` to control whether images are blurred. Use `creditCardPredicate` for custom credit-card detection patterns.
- **Face detection**: Enable `maskFaces` to blur detected faces.
- **Region masking**: Tag a `UIView` with `cxMask = true` or register/unregister regions programmatically using `SessionReplay.shared.registerMaskRegion(_:)` / `unregisterMaskRegion(_:)`. See [Mask specific regions](#mask-specific-regions).

> **Tip**: Session Replay masks all images and redacts common credit card patterns by default. Always verify your masking rules in staging before going live.

## Mask specific regions

Tag any `UIView` instance to be masked in every replay frame. The flag is honored on the next capture.

```swift
sensitiveView.cxMask = true
```

For dynamic regions that don't map to a single view, register a mask by ID:

```swift
let region = MaskRegion(id: "checkout-form", frame: form.bounds)
SessionReplay.shared.registerMaskRegion(region)

// Later, when the region no longer needs masking:
SessionReplay.shared.unregisterMaskRegion("checkout-form")
```

Use this for transient overlays, custom-drawn views, or non-`UIView` content that should not appear in replays.

## Verify Session Replay state

Confirm Session Replay is initialized and currently recording:

```swift
let initialized = SessionReplay.shared.isSRInitialized()
let recording = SessionReplay.shared.isSRRecording()
```