iOS session replay installation

  1. Add PostHog to your app

    Required

    PostHog is available through CocoaPods or you can add it as a Swift Package Manager based dependency.

    CocoaPods

    Podfile
    pod "PostHog", "~> 3.0"

    Swift Package Manager

    Add PostHog as a dependency in your Xcode project "Package Dependencies" and select the project target for your app, as appropriate.

    For a Swift Package Manager based project, add PostHog as a dependency in your Package.swift file's Package dependencies section:

    Package.swift
    dependencies: [
      .package(url: "https://github.com/PostHog/posthog-ios.git", from: "3.0.0")
    ],

    and then as a dependency for the Package target utilizing PostHog:

    Package.swift
    .target(
        name: "myApp",
        dependencies: [.product(name: "PostHog", package: "posthog-ios")]),

    Configuration

    Configuration is done through the PostHogConfig object. Here's a basic configuration example to get you started.

    You can find more advanced configuration options in the configuration page.

    Swift
    import Foundation
    import PostHog
    import UIKit
    

    class AppDelegate: NSObject, UIApplicationDelegate {
        func application(_: UIApplication, didFinishLaunchingWithOptions _: [UIApplication.LaunchOptionsKey: Any]? = nil) -> Bool {
            let POSTHOG_API_KEY = "<ph_project_api_key>"
            // usually 'https://us.i.posthog.com' or 'https://eu.i.posthog.com'
            let POSTHOG_HOST = "https://us.i.posthog.com"
    

            let config = PostHogConfig(apiKey: POSTHOG_API_KEY, host: POSTHOG_HOST) 
            PostHogSDK.shared.setup(config)
    

            return true
        }
    }

    • Requires PostHog iOS SDK version >= 3.6.0, and it's recommended to always use the latest version.
    • Session replay is currently only available on iOS. For future macOS support, please follow and upvote this GitHub issue.

  2. Enable session recordings in your project settings

    Required

    Enable session recordings in your PostHog Project Settings.

    Enable session recordings in your PostHog'

  3. Configure replay settings

    Required

    Automatically start session recordings

    Setting config.sessionReplay = true to your PostHog configuration will start session recordings on SDK setup.

    Manually control session recordings

    Setting config.sessionReplay = false to your PostHog configuration will prevent PostHog from automatically starting session recordings on SDK setup.

    You can manually control when to start and stop session recordings using the following two methods:

    • startSessionRecording(resumeCurrent: Bool)
      • Set resumeCurrent to true to resume a previous session recording (Default).
      • Set resumeCurrent to false to start a new session recording.
    • stopSessionRecording()
      • Stops/pauses the current session recording.

    Note: Calling these methods will have no effect if session recordings are disabled in your PostHog Project Settings.

Configuration options

Swift
let config = PostHogConfig(apiKey: "<ph_project_api_key>")
// Enable session recording. Requires enabling in your project settings as well.
// Default is false.
config.sessionReplay = true


// Whether text and text input fields are masked. Default is true.
// Password inputs are always masked regardless
config.sessionReplayConfig.maskAllTextInputs = true


// Whether images are masked. Default is true.
config.sessionReplayConfig.maskAllImages = true


// Enable masking of all sandboxed system views
// These may include UIImagePickerController, PHPickerViewController and CNContactPickerViewController
// Default is true.
config.sessionReplayConfig.maskAllSandboxedViews = true


// Whether network requests are captured in recordings. Default is true
// Only metric-like data like speed, size, and response code are captured.
// No data is captured from the request or response body.
config.sessionReplayConfig.captureNetworkTelemetry = true


// Whether replays are created using high quality screenshots. Default is false.
// Required for SwiftUI.
// If disabled, replays are created using wireframes instead.
// The screenshot may contain sensitive information, so use with caution
config.sessionReplayConfig.screenshotMode = true


// Sets the minimum time interval (in seconds) between session replay snapshots.
// A higher value reduces performance impact but decreases replay smoothness. Default is 1.0s.
// Note: Previously known as `debouncerDelay` before version 3.21.0
config.sessionReplayConfig.throttleDelay = 1.0

Limitations

  • On iOS, minimum deployment target is iOS13
  • SwiftUI is only supported if the screenshotMode option is enabled.
  • Custom views are partly supported, and only fully supported if screenshotMode is enabled.
  • WebView is only supported if screenshotMode is enabled. A placeholder will be shown as a fallback.
  • Currently only available on iOS.

Troubleshooting

  • Update your SDK.
  • If you have enabled session replay using feature flags, the flags are evaluated on the device once the PostHog SDK starts as early as possible. The SDK might be using the cached flags from the previous SDK start. If you have changed the flag or its condition, kill and reopen the app to force a new SDK start at least once.
    • This will also happen in production, and you might experience some delay for the new flag/conditions to take effect on your users. We're tracking this bug in issue #263.
    • Session replay feature flag evaluation does not capture $feature_flag_called events, so the Usage tab on the feature flag page won't show anything. We're tracking this feature request in issue #250.

Community questions

Was this page useful?

Questions about this page? or post a community question.