iOS SDK

Record pixel-accurate replays, auto-captured taps and gestures, custom events, crashes, and performance vitals — with one call at launch. Requires iOS 15+.

Install

The module you import is always Replay, regardless of installer.

// File → Add Package Dependencies…
// https://github.com/replayfy/ios-sdk  (from 0.0.4)

dependencies: [
    .package(url: "https://github.com/replayfy/ios-sdk.git", from: "0.0.4")
],
targets: [
    .target(
        name: "YourApp",
        dependencies: [
            .product(name: "Replayfy", package: "replay-ios-sdk"),
            // optional SwiftUI modifiers:
            .product(name: "ReplaySwiftUI", package: "replay-ios-sdk"),
        ]
    )
]

pod 'Replayfy', '~> 0.0.4'

Initialize

Import and start at launch

Start Replayfy as early as possible — recording begins immediately.

import Replay

func application(_ application: UIApplication,
                 didFinishLaunchingWithOptions launchOptions:
                 [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    Replay.start(with: ReplayConfig(
        apiKey: "rpl_pk_YOUR_KEY",
        apiHost: "https://us.replayfy.app"  // or your self-hosted API URL
    ))
    return true
}

SwiftUI-only apps

No AppDelegate? Start it from App.init.

@main
struct MyApp: App {
    init() {
        Replay.start(with: ReplayConfig(
            apiKey: "rpl_pk_YOUR_KEY",
            apiHost: "https://us.replayfy.app"  // or your self-hosted API URL
        ))
    }
    var body: some Scene { WindowGroup { ContentView() } }
}

Identify and track (optional)

Attach a known user and record custom events.

Replay.identify("user_123", properties: ["email": "[email protected]", "plan": "pro"])
Replay.track("purchase", properties: ["amount": 4200, "currency": "USD"])

A properties["picture"] (or its alias ["avatar"]) set to a public https image URL becomes the user’s avatar on the recording header and Users list — top-level or nested in customProps; non-URL values are ignored.

Verify

Run the app, interact for a few seconds, then background it. Your first session appears in the Replayfy dashboard within a minute.

Wire up Replay.addVerificationListener { ... } to light up an in-app “Verify integration” state — it fires once after the first successful upload.

Configuration

Only apiKey and apiHost are required. Pass any subset to ReplayConfig(...).

Option	Type	Default	Description
`apiKey`	`String`	required	Your project API key from the dashboard.
`apiHost`	`String`	required	Ingest base URL, e.g. `https://us.replayfy.app` (or your self-hosted API URL).
`projectId`	`String?`	`nil`	Only when one key covers multiple projects.
`distinctId`	`String?`	`nil`	Known user id at start; otherwise an install-stable anonymous id is used.
`flushInterval`	`TimeInterval`	`5`	Seconds between automatic uploads of the in-memory batch.
`maxBufferSize`	`Int`	`500`	Events buffered before an upload is forced.
`captureConsole`	`Bool`	`true`	Capture `print` / `NSLog` / `os_log` output.
`captureNetwork`	`Bool`	`false`	Capture HTTP requests (off by default to avoid PII).
`captureErrors`	`Bool`	`true`	Capture uncaught exceptions and crashes.
`captureHeaders`	`Bool`	`false`	Include request/response headers in network capture.
`captureBodies`	`Bool`	`true`	Include request/response bodies (capped by `maxBodyBytes`).
`maxBodyBytes`	`Int`	`4096`	Max captured body bytes per network event; larger bodies are truncated.
`captureSnapshotPixels`	`Bool`	`true`	Pixel-accurate replay when `true`; lighter wireframe replay when `false`.
`snapshotInterval`	`TimeInterval`	`0.5`	Screen-capture cadence in seconds (floored at 0.2s).
`autoScreenName`	`Bool`	`true`	Auto-detect the current screen from the foreground view controller.
`useRemoteConfig`	`Bool`	`true`	Let dashboard settings override these values at runtime.
`captureTouch`	`Bool`	`true`	Capture taps natively (disable only for host-driven capture such as Flutter).
`excludedScreens`	`[String]`	`[]`	Screen names whose frame capture is paused while they’re foreground (see Screens). Case-insensitive; taps, network, and console still record. Mutable at runtime via `Replay.excludeScreen`/`setExcludedScreens`.

API reference

All methods are static on the Replay type.

Lifecycle

Method	Description
`Replay.start(with: ReplayConfig)`	Boot the SDK and start recording. Call once at launch.
`Replay.stop()`	End the current session and upload immediately; a new session starts on next foreground.
`Replay.isRecording`	`Bool` — whether a session is currently recording.
`Replay.pauseRecording()`	Pause screen capture (other events keep flowing).
`Replay.resumeRecording()`	Resume screen capture.
`Replay.startNewSession()`	Force a new logical session (e.g. after logout → login).
`Replay.stopApplicationAndUploadData(timeoutSeconds:)`	Stop recording and block up to `timeoutSeconds` until the buffer flushes.
`Replay.cancelSession()`	Discard the current session without uploading — clears the in-memory buffer and deletes any on-disk batches still queued, so the server drops whatever already streamed. A fresh session can start afterward. Contrast with `stop()`, which ends the session gracefully and uploads.
`Replay.enableAdvancedGestureRecognizer(_:)`	Additionally capture pinch and rotate gestures, on top of the always-on tap / swipe / long-press. Off by default.
`Replay.allowShortBreakForAnotherApp(_:windowSeconds:)`	Keep the same session across a brief switch to another app — a background gap up to `windowSeconds` (default `30`) resumes the session; a longer gap starts a fresh session on return.
`Replay.setMultiSessionRecord(_:)`	Record multiple sessions per app launch (default `true`), or only one — when `false`, the current/next session records and then no further sessions open this process.

Identify & analytics

Method	Description
`Replay.identify(_:properties:)`	Attach a known user to the session; anonymous history links back to them.
`Replay.track(_:properties:)`	Fire a custom event onto the timeline (drives funnels and filters).
`Replay.setUserProperty(_:value:)`	Sticky property on the end user (persists across sessions).
`Replay.setSessionProperty(_:value:)`	Sticky property on the current session only.
`Replay.addTagWithProperties(_:properties:)`	Session-level tag (with optional properties) for filtering sessions.
`Replay.markSessionAsFavorite()`	Star the current session so it surfaces in the dashboard’s saved filter.
`Replay.reportBugEvent(_:description:)`	Send a manual bug report (wire to a “Report issue” button).

Error monitoring

Method	Description
`Replay.captureException(_:properties:)`	Report a caught error onto the timeline (`handled = true` by default).
`Replay.captureException(_:handled:)`	Report a caught error; pass `handled: false` to mark it fatal.

Uncaught exceptions and crashes are captured automatically when captureErrors is true.

Screens

Method	Description
`Replay.tagScreenName(_:)`	Manually set the current screen name (overrides the auto-tagger).
`Replay.setAutomaticScreenNameTagging(_:)`	Toggle the automatic screen-name tagger at runtime.
`Replay.excludeScreen(_:)`	Exclude a screen from frame capture by name (case-insensitive; matched against the tagged / auto-tagged screen name). While that screen is foreground the periodic screenshot loop pauses — taps, network, console, and performance events keep flowing — and resumes on the next non-excluded screen.
`Replay.unexcludeScreen(_:)`	Stop excluding a screen — frame capture resumes next time it’s shown.
`Replay.setExcludedScreens(_:)`	Replace the entire excluded-screens list in one call.

Exclusion is distinct from occludeSensitiveScreen(_:) — that keeps recording but blanks the frame, whereas an excluded screen captures no frames at all. Seed the list at launch, or manage it at runtime:

// Seed at startup:
Replay.start(with: ReplayConfig(
    apiKey: "rpl_pk_YOUR_KEY",
    apiHost: "https://us.replayfy.app",  // or your self-hosted API URL
    excludedScreens: ["Paywall", "PinEntry"]
))

// …or manage at runtime:
Replay.excludeScreen("Paywall")               // pause frames while "Paywall" is foreground
Replay.unexcludeScreen("Paywall")             // resume
Replay.setExcludedScreens(["PinEntry", "CardScanner"])

Logging

Method	Description
`Replay.log(level:message:stack:)`	Bridge a custom logger into the console tab. `level` ∈ `"log"`, `"info"`, `"warn"`, `"error"`, `"debug"`.

Metadata

Method	Description
`Replay.setAppVersion(_:build:)`	Override the auto-detected app version/build (useful for RN/Flutter shells).
`Replay.setPushNotificationToken(_:platform:)`	Attach the device push token to the session.

Text input

Method	Description
`Replay.addObservedInput(_:)`	Record a text field’s value when editing ends (opt-in per field). Secure fields record as `"***"`.
`Replay.trackInput(label:value:masked:)`	Report a value not backed by a `UITextField`. `masked` → `"***"`.

Network capture

Set captureNetwork: true. URLSession.shared is captured automatically. For a custom configuration, register it before creating the session.

Method	Description
`Replay.captureURLSessionConfiguration(_:)`	Register a custom `URLSessionConfiguration` for capture.

let cfg = URLSessionConfiguration.default
Replay.captureURLSessionConfiguration(cfg)
let session = URLSession(configuration: cfg)

Method	Description
`Replay.optOutOverall(_:)`	Overall opt-out — drops all events and recording. Persists across launches.
`Replay.isOptedOutOverall`	`Bool` — whether the user is currently opted out.
`Replay.optOutOfSchematicRecordings(_:)`	Snapshot-only opt-out — pauses frame capture while every other event type keeps flowing. Persists across launches.
`Replay.isOptedOutOfSchematicRecordings`	`Bool` — whether snapshot recording is currently opted out.

Deep links

Method	Description
`Replay.urlForCurrentSession()`	`String?` — the dashboard URL for the current session (`<app-host>/recordings/<id>`, with the app host derived from `apiHost`), or `nil` when no session is active.
`Replay.urlForCurrentUser()`	`String?` — the dashboard URL for the currently-identified user, or `nil` before `identify()` is called.

Integration verification

Method	Description
`Replay.addVerificationListener(_:)`	Fires once after the first successful upload. Returns a token to remove it later.
`Replay.removeVerificationListener(_:)`	Remove a previously added verification listener by token.

Cross-platform bridges

Entry points for host frameworks (React Native, Flutter) that capture interactions, inputs, and frames themselves. Native iOS apps don’t need them.

Method	Description
`Replay.reportInteraction(kind:label:x:y:)`	Feed a host-captured interaction (tap, gesture) into the timeline.
`Replay.reportFrame(_:rects:styles:)`	Feed a host-captured frame with occlusion rects and styles.

Privacy & masking

Sensitive content never has to leave the device. Secure/password fields (isSecureTextEntry) are masked automatically; everything else is opt-in.

Choose a mask style

Replay.setMaskStyle(.blur)      // Gaussian blur (default)
Replay.setMaskStyle(.overlay)   // solid box — nothing survives
Replay.setMaskStyle(.pixelate)  // coarse mosaic
Replay.setBlurRadius(8)         // blur strength for .blur regions

ReplayMaskStyle values: .blur, .overlay, .pixelate.

UIKit masking

// Mask a single view (marks propagate to subviews).
Replay.addPrivacyView(cardNumberField)
Replay.removePrivacyView(cardNumberField)

// Mask every text field / text view, or every label.
Replay.occludeAllTextFields(true)
Replay.occludeAllTextView(true)

// Mask every instance of a view class, everywhere it appears.
Replay.applyOcclusion(CreditCardView.self)
Replay.removeOcclusion(CreditCardView.self)

// Mask the entire screen (banking PIN pad, health records, …).
Replay.occludeSensitiveScreen(true)

// Mask specific regions on the next frame only (root-relative points).
Replay.occludeRectsOnNextFrame(rects)
Replay.occludeRectsOnNextFrame(rects, style: .overlay)

SwiftUI masking

Import the optional ReplaySwiftUI module:

import ReplaySwiftUI

var body: some View {
    VStack {
        CreditCardForm()
            .replayOcclude()                 // mask this view's region
    }
    .replayTagScreenName("Checkout")         // tag the screen on appear
}

replayOcclude(blockGestures:) also suppresses taps on the masked region when blockGestures is true (the default).

Identify users

Link sessions to known users and their properties.

Track events

Fire custom events to power funnels and filters.

Privacy & masking

Redact sensitive views, fields, and regions.

Get started

Self-hosting

Install the SDK

Products

Platform

Guides

Help

Install

Initialize

Verify

Configuration

API reference

Lifecycle

Identify & analytics

Error monitoring

Screens

Logging

Metadata

Text input

Network capture

Deep links

Integration verification

Cross-platform bridges

Privacy & masking

Choose a mask style

UIKit masking

SwiftUI masking

Identify users

Track events

Privacy & masking

​Install

​Initialize

​Verify

​Configuration

​API reference

​Lifecycle

​Identify & analytics

​Error monitoring

​Screens

​Logging

​Metadata

​Text input

​Network capture

​Consent / opt-out

​Deep links

​Integration verification

​Cross-platform bridges

​Privacy & masking

​Choose a mask style

​UIKit masking

​SwiftUI masking

Identify users

Track events

Privacy & masking

Install

Initialize

Verify

Configuration

API reference

Lifecycle

Identify & analytics

Error monitoring

Screens

Logging

Metadata

Text input

Network capture

Consent / opt-out

Deep links

Integration verification

Cross-platform bridges

Privacy & masking

Choose a mask style

UIKit masking

SwiftUI masking