iOS

The Middleware iOS RUM SDK collects user activity, application performance data, and errors from iOS applications. It helps you investigate crashes, slow screens, and failed requests in the context of a user session.

Collected data includes crashes, slow or frozen frames, network requests, and sessions. Session Replay adds visual context; correlation with backend traces helps follow a request beyond the mobile application when backend instrumentation is configured.

Prerequisites#

Before installing the SDK, make sure you have:

• iOS 13 or later.
• Xcode with Swift Package Manager support.
• A Middleware account and RUM application credentials.
• Access to your iOS application source code.
• HTTPS connectivity to your Middleware ingestion endpoint.

The SDK also supports macOS 10.15+ and tvOS 13+.

To check available SDKs in Xcode, run:

xcodebuild -showsdks

Installation#

.package(
    url: "https://github.com/middleware-labs/middleware-ios",
    from: "2.3.2"
)

source 'https://github.com/middleware-labs/cocoapods-specs.git'
source 'https://cdn.cocoapods.org/'

pod 'MiddlewareRum', '~> 2.3'

pod install

import SwiftUI
import MiddlewareRum

@main
struct MyApp: App {

    init() {
        do {
            try MiddlewareRumBuilder()
                .target("https://<MW_UID>.middleware.io")
                .rumAccessToken("<MW_RUM_ACCESS_TOKEN>")
                .serviceName("my-ios-app")
                .projectName("My-iOS-App")
                .deploymentEnvironment("PROD")
                .globalAttributes([
                    "app.version": "1.0.0"
                ])
                .build()
        } catch {
            print("Middleware RUM initialization failed: \(error)")
        }
    }

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

import UIKit
import MiddlewareRum

@main
class AppDelegate: UIResponder, UIApplicationDelegate {

    func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions:
            [UIApplication.LaunchOptionsKey: Any]?
    ) -> Bool {

        do {
            try MiddlewareRumBuilder()
                .target("https://<MW_UID>.middleware.io")
                .rumAccessToken("<MW_RUM_ACCESS_TOKEN>")
                .serviceName("my-ios-app")
                .projectName("My-iOS-App")
                .deploymentEnvironment("PROD")
                .globalAttributes([
                    "app.version": Bundle.main.object(
                        forInfoDictionaryKey: "CFBundleShortVersionString"
                    ) as? String ?? ""
                ])
                .build()
        } catch {
            print("Middleware RUM initialization failed: \(error)")
        }

        return true
    }
}

Enable or disable monitoring features#

Crash reporting, HTTP instrumentation, and slow rendering detection are enabled by default.

To disable specific features, add the corresponding methods during initialization:

try MiddlewareRumBuilder()
    .target("https://<MW_UID>.middleware.io")
    .rumAccessToken("<MW_RUM_ACCESS_TOKEN>")
    .serviceName("my-ios-app")
    .projectName("My-iOS-App")
    .disableCrashReportingInstrumentation()
    .disableNetworkMonitoring()
    .disableSlowRenderingDetection()
    .build()

Only include the disable methods for features you don't want to collect.

Configure Session Replay#

Session Replay is enabled by default and starts automatically when the SDK initializes.

It records user activity and screen changes to help investigate application issues.

Configure recording quality and privacy#

Use RecordingOptions to configure recording frequency, quality, and masking.

try MiddlewareRumBuilder()
    .target("https://<MW_UID>.middleware.io")
    .rumAccessToken("<MW_RUM_ACCESS_TOKEN>")
    .serviceName("my-ios-app")
    .projectName("My-iOS-App")
    .recordingOptions(
        RecordingOptions()
            .setFrequency(.standard)
            .setQuality(.standard)
            .setMaskAllTextInputs(true)
            .setMaskAllImages(true)
    )
    .build()

Disable Session Replay#

To collect RUM telemetry without recording user sessions, add:

.disableRecording()

Session recording limits#

• Maximum session duration: 4 hours.
• Idle timeout: 15 minutes.
• Default: Session Replay enabled.

After the idle timeout, new user activity starts a new session.

Mask sensitive information#

Middleware masks sensitive text inputs and images by default. You can also mask specific UI elements that contain payment details, authentication information, or other sensitive content.

SwiftUI#

Use the .sensitive() modifier:

Text("Sensitive account information")
    .sensitive()

UIKit#

Exclude a view from Session Replay:

MiddlewareRum.addIgnoredView(sensitiveView)

Alternatively, mark a view using its accessibility identifier:

cardNumberField.accessibilityIdentifier = "mw-no-capture"

Supported identifiers:

• mw-no-capture — Always masks the view.
• mw-no-mask — Excludes the view from masking.

Important: Secure text fields and sensitive textContentType fields, such as passwords, credit card details, and one-time codes, remain masked regardless of the configuration.

Masking is applied on the device before session recording data is uploaded.

Configure distributed tracing#

Distributed tracing connects iOS network requests with backend APM traces.

The SDK automatically instruments URLSession and injects W3C traceparent headers into outgoing requests.

No additional HTTP client instrumentation is required.

Prerequisites#

• Middleware APM instrumentation must be enabled on your backend.
• Backend services must support W3C Trace Context.
• Network monitoring must be enabled in the iOS SDK.

Restrict trace propagation targets#

By default, trace headers are added to outgoing requests, excluding Middleware ingestion endpoints.

To restrict propagation to your backend domains:

try MiddlewareRumBuilder()
    .target("https://<MW_UID>.middleware.io")
    .rumAccessToken("<MW_RUM_ACCESS_TOKEN>")
    .serviceName("my-ios-app")
    .projectName("My-iOS-App")
    .tracePropagationTargets([
        "api\\.example\\.com",
        "checkout\\.example\\.com"
    ])
    .build()

Requests to other domains are still monitored but do not receive tracing headers.

Passing an empty array disables trace propagation.

Verify trace correlation#

1. Open your application and trigger a backend API request.
2. Go to RUM → Session Explorer.
3. Open the session and select the network request.
4. Follow the associated backend trace.

If the request has a trace ID but no backend spans, verify that your backend is instrumented and accepts W3C Trace Context.

Add custom logs and errors#

Custom logs#

Use the SDK to capture application-specific logs:

MiddlewareRum.info("User opened checkout")
MiddlewareRum.debug("Loading payment details")
MiddlewareRum.warning("API response delayed")
MiddlewareRum.error("Payment request failed")
MiddlewareRum.critical("Unexpected application failure")

Report custom errors#

Record application errors for investigation:

MiddlewareRum.addError("Unable to process payment")

Report handled exceptions#

Application crashes are captured automatically. You can report handled exceptions manually:

MiddlewareRum.addException(
    e: NSException(
        name: NSExceptionName(rawValue: "RuntimeException"),
        reason: "Payment processing failed"
    )
)

Add custom attributes#

Use global attributes to filter sessions by application version, environment, or user group.

MiddlewareRum.setGlobalAttributes([
    "app.version": "1.0.0",
    "user.type": "premium"
])

Prefer stable, non-sensitive values. Avoid sending passwords, tokens, or personal information.

Set a custom screen name#

To identify screens using application-specific names:

MiddlewareRum.setScreenName("checkout")

This is useful when investigating navigation or grouping events by screen.

Instrument WebView content#

If your application uses a WKWebView, you can connect Browser RUM with Mobile RUM to investigate hybrid user journeys.

MiddlewareRum.integrateWebViewWithBrowserRum(view: webView)

Use this on the active WebView instance.

The embedded web application should also have the Middleware Browser RUM SDK installed for browser-side telemetry.

Configuration reference#

All methods accepted by MiddlewareRumBuilder():

Troubleshooting#

No RUM data appears#

If your application is running but telemetry does not appear:

• Verify that the SDK is installed and imported correctly.
• Confirm that MiddlewareRumBuilder().build() runs during application startup.
• Check the RUM access token and target URL.
• Verify that the device can connect to Middleware over HTTPS.
• Review the Xcode console for initialization or export errors.

Network requests are missing#

If sessions appear but HTTP requests are not collected:

• Confirm that disableNetworkMonitoring() is not enabled.
• Verify that requests use URLSession or a networking library built on it.
• Check whether the requests are sent to excluded Middleware ingestion endpoints.

Backend traces are not correlated#

If network requests appear but backend traces are missing:

• Verify that backend APM instrumentation is enabled.
• Confirm that the backend accepts W3C Trace Context.
• Check that tracePropagationTargets() matches your backend domains.
• Ensure that proxies or gateways do not remove the traceparent header.

Session Replay is missing#

If sessions appear without recordings:

• Verify that disableRecording() is not enabled.
• Check that SDK initialization completes successfully.
• Confirm that recording is permitted by your application's consent settings.
• Review SDK logs for recording or upload errors.

Sensitive information appears in recordings#

• Verify that text and image masking is enabled.
• Use .sensitive() for SwiftUI views.
• Use MiddlewareRum.addIgnoredView() for UIKit views.
• Mark sensitive fields with mw-no-capture.
• Review masking whenever the application UI changes.

High slow or frozen frame counts#

The SDK reports:

• Slow frames: Rendering time above 16.7 ms.
• Frozen frames: Rendering time above 700 ms.

Use Xcode Instruments, including Time Profiler and Core Animation, to identify expensive main-thread work or rendering operations.

HTTPS requests are blocked#

iOS App Transport Security (ATS) blocks cleartext HTTP connections by default.

Use HTTPS for your Middleware ingestion endpoint and backend APIs. For development environments requiring HTTP, configure scoped ATS exceptions in Info.plist.

Build errors#

• If Xcode can't resolve the package, go to File → Packages → Reset Package Caches and resolve again.
• For CocoaPods, run pod install and open the .xcworkspace file, not the .xcodeproj.
• If CocoaPods can't find or upgrade MiddlewareRum, check both sources are in your Podfile and run pod update MiddlewareRum.
• If your Podfile uses use_frameworks!, link MiddlewareRum statically.
• Verify that the deployment target is iOS 13 or later.

If the issue persists, contact Middleware Support at support@middleware.io.