This article covers installation of Session Replay using the Session Replay iOS Segment plugin. Use this option if your app uses Segment's Analytics-Swift library and Amplitude (Actions) destination.

If your app uses an [Amplitude iOS SDK](/docs/sdks/analytics/ios/ios-swift-sdk), use the [Session Replay iOS SDK Plugin](/docs/sdks/session-replay/session-replay-ios-plugin).

If you use Segment with other options, choose the [standalone implementation](/docs/sdks/session-replay/session-replay-ios-standalone-sdk).

{% partial file="session-replay/sr-ios-performance.md" /%}

Session Replay captures changes to an app's view tree: the main view and all its child views recursively. Session Replay then replays these changes to build a video-like replay. At the start of a session, Session Replay captures a full snapshot of the app's view tree. As the user interacts with the app, Session Replay captures each change as a diff. When you watch the replay, Session Replay applies each diff back to the original view tree in sequential order. Session replays have no maximum length.

{% callout type="tip" heading="Report issues" %}
To report issues with Session Replay for iOS, go to the [AmplitudeSessionReplay-ios GitHub repository](https://github.com/amplitude/AmplitudeSessionReplay-ios).
{% /callout %}

## Before you begin

The Session Replay iOS Segment Plugin requires that:

1. Your application runs on iOS or iPadOS.
2. You use Segment's Analytics-Swift library for ingestion.
3. You use Segment's Amplitude (Actions) destination.
4. You use Segment's [Amplitude Plugin](https://segment.com/docs/connections/sources/catalog/libraries/mobile/apple/destination-plugins/amplitude-swift/).

{% partial file="session-replay/sr-ios-supported-versions.md" /%}

## Quickstart

Add the [latest version](https://github.com/amplitude/AmplitudeSessionReplay-iOS) of the plugin to your project dependencies.

The Segment plugin is available through Swift Package Manager only. Add Session Replay as a dependency in your Package.swift file or the Package list in Xcode.

```swift
dependencies: [
    .package(url: "https://github.com/amplitude/AmplitudeSessionReplay-iOS", from: "0.11.1")
]
```

To integrate with `Analytics-Swift`, use the `AmplitudeSegmentSessionReplayPlugin` target.

```swift
.product(name: "AmplitudeSegmentSessionReplayPlugin", package: "AmplitudeSessionReplay")
```

Configure your application code:

```swift
import AmplitudeSegmentSessionReplayPlugin
import Segment
import SegmentAmplitude

// Initialize Segment
let analytics = Analytics(configuration: config)

// Ensure Segment's AmplitudeSession plugin is added before AmplitudeSegmentSessionReplayPlugin
analytics.add(plugin: AmplitudeSession())

// Initialize AmplitudeSegmentSessionReplayPlugin with your Amplitude API key
analytics.add(plugin: AmplitudeSegmentSessionReplayPlugin(amplitudeApiKey: API_KEY,
                                                              sampleRate: 0.1))
```

## Configuration

Pass the following option when you initialize the Session Replay plugin:

{% partial file="session-replay/sr-ios-config.md" /%}

{% partial file="session-replay/sr-ios-mask-data.md" /%}

### User opt-out

Set `optOut` on the plugin to indicate that a user opted out of session replay.

```swift
// Pass a boolean value to indicate a users opt-out status
amplitudeSegmentSessionReplayPlugin.optOut = true
```

{% partial file="session-replay/sr-eu-data-residency.md" /%}

```swift
// Set serverZone on the AmplitudeSegmentSessionReplayPlugin
let plugin = AmplitudeSegmentSessionReplayPlugin(amplitudeApiKey: API_KEY,
                                                     sampleRate: 0.1,
                                                     serverZone: .EU)
```

{% partial file="session-replay/sr-sampling-rate.md" /%}

```swift
// This configuration samples 1% of all sessions
analytics.add(plugin: AmplitudeSegmentSessionReplayPlugin(amplitudeApiKey: API_KEY,
                                                              sampleRate: 0.01))
```

### Recording quality

Choose a quality profile to balance replay fidelity with performance and storage. Lower profiles use a lower capture frame rate and lower image resolution. Higher profiles use a higher frame rate and higher resolution. Use `QualityProfile.automatic` to let the SDK select a profile based on the device. For example, the SDK selects high on newer devices and lower on older ones.

```swift
// Use automatic profile selection based on device
analytics.add(plugin: AmplitudeSegmentSessionReplayPlugin(amplitudeApiKey: API_KEY,
                                                              sampleRate: 0.1,
                                                              quality: .automatic))

// Or set a fixed profile (low, medium, or high)
analytics.add(plugin: AmplitudeSegmentSessionReplayPlugin(amplitudeApiKey: API_KEY,
                                                              sampleRate: 0.1,
                                                              quality: .medium))
```

### Disable uploads on metered networks

Avoid using the user's cellular data by pausing Session Replay uploads while the device uses a metered network. Session Replay still records data locally. Uploads resume when the device reconnects to Wi‑Fi or another non-metered connection.

```swift
analytics.add(plugin: AmplitudeSegmentSessionReplayPlugin(amplitudeApiKey: API_KEY,
                                                              sampleRate: 0.1,
                                                              uploadConfig: UploadConfig(disableMeteredUploads: true)))
```

### Disable replay collection

After you enable Session Replay, it runs on your app until either:

- The user leaves your app.
- You call `amplitudeSegmentSessionReplayPlugin.stop()`.
- You remove the plugin from Segment with `analytics.remove(plugin: amplitudeSegmentSessionReplayPlugin)`.

Call `amplitudeSegmentSessionReplayPlugin.stop()` before a user navigates to a restricted area of your app to disable replay collection while the user is in that area.

{% callout type="note" heading="Keep a reference" %}
Keep a reference to the SessionReplayPlugin instance: `let amplitudeSegmentSessionReplayPlugin = AmplitudeSegmentSessionReplayPlugin(/* session replay options */)`.
{% /callout %}

Call `amplitudeSegmentSessionReplayPlugin.start()` to re-enable replay collection when the user returns to an unrestricted area of your app.

To capture only specific screens, initialize the plugin with `autoStart: false` so it doesn't start on launch, then call `start()` and `stop()` as the user enters and leaves those screens:

```swift
// Add the plugin once, without starting capture
let amplitudeSegmentSessionReplayPlugin = AmplitudeSegmentSessionReplayPlugin(amplitudeApiKey: API_KEY,
                                                                              sampleRate: 1.0,
                                                                              autoStart: false)
analytics.add(plugin: amplitudeSegmentSessionReplayPlugin)

// Start capture when the user enters a screen you want to record
amplitudeSegmentSessionReplayPlugin.start()

// Stop capture when the user leaves that screen
amplitudeSegmentSessionReplayPlugin.stop()
```

You can also use a feature flag product like [Amplitude Experiment](/docs/feature-experiment/overview) to create logic that enables or disables replay collection based on criteria like location. For example, create a feature flag that targets a specific user group, then add that flag to your initialization logic:

```swift
import AmplitudeSegmentSessionReplayPlugin
import Segment
import SegmentAmplitude

// Your existing initialization logic with Segment
let analytics = Analytics(configuration: config)
analytics.add(plugin: AmplitudeSession())

if (nonEUCountryFlagEnabled) {
  // Create and Install Session Replay Plugin
  let amplitudeSegmentSessionReplayPlugin = AmplitudeSegmentSessionReplayPlugin(amplitudeApiKey: API_KEY, sampleRate: 0.1)
  analytics.add(plugin: amplitudeSegmentSessionReplayPlugin)
}
```

{% partial file="session-replay/sr-ios-webview.md" /%}

{% partial file="session-replay/sr-ios-mapview-support.md" /%}

{% partial file="session-replay/sr-ios-log-recording.md" /%}

{% partial file="session-replay/sr-data-retention.md" /%}

{% partial file="session-replay/sr-ios-storage.md" /%}

{% partial file="session-replay/sr-ios-known-limitations.md" /%}