iOS Configuration Options

This page covers what you can change after iOS Monitoring Setup is working. Configuration is split in two: Atatus.Configuration labels your data and controls the transport, and RUM.Configuration controls what RUM collects.

Nothing here is required. Each option has a default, so add only what you need.

Identity and transport

These options are passed to Atatus.initialize() and apply to every product:

Tune batching

Batch size and upload frequency trade data latency against radio use. Larger, less frequent batches amortize each radio wake-up across more events:

Atatus.initialize(
    with: Atatus.Configuration(
        licenseKey: "<LICENSE_KEY>",
        env: "<ENV_NAME>",
        service: "<APP_NAME>",
        batchSize: .large,
        uploadFrequency: .rare
    ),
    trackingConsent: .granted
)

Use .large with .rare when battery consumption is the constraint, and .small with .frequent during development, where fast feedback matters more than efficiency.

Encrypt data at rest

Events waiting to be uploaded are stored in the application's cache directory. To encrypt them, pass an object that implements DataEncryption:

struct Encryptor: DataEncryption {
    func encrypt(data: Data) throws -> Data { /* your implementation */ }
    func decrypt(data: Data) throws -> Data { /* your implementation */ }
}

Atatus.initialize(
    with: Atatus.Configuration(
        licenseKey: "<LICENSE_KEY>",
        env: "<ENV_NAME>",
        encryption: Encryptor()
    ),
    trackingConsent: .granted
)

RUM options

Every option on RUM.Configuration, with the value it takes when you leave it out:

The performance options are covered in Mobile Vitals, and the network options in Network Tracking.

Track views automatically

A views predicate decides which screens become RUM views and what they are called. Without one, no views are tracked at all.

UIKit

DefaultUIKitRUMViewsPredicate tracks each view controller as a screen, named after its class, such as MyApp.CheckoutViewController. It skips UIKit's own container controllers, so UINavigationController and UITabBarController do not appear as screens, and it skips SwiftUI hosting controllers, which the SwiftUI predicate handles instead. A subclass of your own is always tracked, including a subclass of a container controller.

Class names make poor screen names in a dashboard. Write a predicate to name them yourself:

import UIKit
import AtatusRUM

struct AppViewsPredicate: UIKitRUMViewsPredicate {
    func rumView(for viewController: UIViewController) -> RUMView? {
        switch viewController {
        case is HomeViewController:
            var view = RUMView(name: "Home", attributes: ["screen.tier": "free"])
            view.path = "app/home"
            return view
        case is CheckoutViewController:
            return RUMView(name: "Checkout")
        case is UIAlertController:
            return RUMView(name: "Alert", isUntrackedModal: true)
        default:
            return nil
        }
    }
}

RUM.enable(with: RUM.Configuration(uiKitViewsPredicate: AppViewsPredicate()))

Returning nil leaves a screen untracked. isUntrackedModal: true is for an overlay you do not want recorded as a screen: the view underneath stops while it is up, and restarts when it is dismissed, so its time is not counted as time on the screen behind it.

SwiftUI

DefaultSwiftUIRUMViewsPredicate detects SwiftUI screens by inspecting the hosting controller, and names them after the view type it finds:

RUM.enable(
    with: RUM.Configuration(
        swiftUIViewsPredicate: DefaultSwiftUIRUMViewsPredicate()
    )
)

To rename what the predicate finds, implement it yourself:

struct AppSwiftUIViewsPredicate: SwiftUIRUMViewsPredicate {
    func rumView(for extractedViewName: String) -> RUMView? {
        switch extractedViewName {
        case "ProductDetailView": return RUMView(name: "Product")
        case "CartView": return RUMView(name: "Cart")
        default: return nil
        }
    }
}

Track a view manually

Manual tracking is the most reliable option when the predicates do not fit your navigation:

// From a view controller
RUMMonitor.shared().startView(viewController: self, name: "Checkout")
RUMMonitor.shared().stopView(viewController: self)

// Or with a key of your own
RUMMonitor.shared().startView(key: "checkout", name: "Checkout")
RUMMonitor.shared().stopView(key: "checkout")

Track user actions automatically

DefaultUIKitRUMActionsPredicate reports taps. It reports a tap only when it lands on a control, a table view cell, a collection view cell, or an alert action, so taps on plain views and labels are not reported. Taps on the system keyboard are dropped for privacy.

Action names come from the view: if it has an accessibilityIdentifier, the name is the class plus that identifier, such as UIButton(checkout-button). Otherwise it is the class name alone.

A custom predicate can rename an action or return nil to drop it. It cannot widen what is captured, because the filtering above happens before the predicate is asked:

struct AppActionsPredicate: UITouchRUMActionsPredicate {
    func rumAction(targetView: UIView) -> RUMAction? {
        guard let identifier = targetView.accessibilityIdentifier else {
            return nil
        }
        return RUMAction(name: identifier)
    }
}

On tvOS the predicate is press based rather than touch based, and reports select, menu, and play or pause presses as click actions.

Scroll and swipe

Scroll and swipe actions are reported for UIScrollView, UITableView, and UICollectionView whenever a UIKit actions predicate is set. The SDK decides which of the two it was from how fast the finger was moving when it left the screen, and records the direction. Turn it off with the feature flag:

RUM.enable(
    with: RUM.Configuration(
        uiKitActionsPredicate: DefaultUIKitRUMActionsPredicate(),
        featureFlags: [.trackScrollAndSwipeActions: false]
    )
)

This is available on iOS and iPadOS.

Frustration signals

With trackFrustrations on, which is the default, a tap followed by an error is reported as an error tap. That is the one frustration signal the iOS SDK detects, and it rolls up into a frustration count per view.

Identify your users

Attaching a user to the session lets you find every session, error, and request belonging to one person:

Atatus.setUserInfo(
    id: "1234",
    name: "Priya R",
    email: "priya@example.com",
    extraInfo: ["plan": "enterprise"]
)

Only id is required. Add fields you learn later without repeating the rest:

Atatus.addUserExtraInfo(["trial_days_left": 7])

Clear the user on sign-out, so the next session is not attributed to the person who signed out:

Atatus.clearUserInfo()

For business-to-business applications, the account APIs record the organization a user belongs to, alongside the user:

Atatus.setAccountInfo(id: "acme", name: "Acme Inc", extraInfo: ["tier": "gold"])
Atatus.addAccountExtraInfo(["seats": 250])
Atatus.clearAccountInfo()

trackAnonymousUser is on by default and keeps a random per-install identifier, so sessions from the same device are counted as one user even before sign-in. Turn it off if you do not want that identifier stored:

RUM.enable(with: RUM.Configuration(trackAnonymousUser: false))

Attach your own attributes

Global attributes are attached to every RUM event from the point you add them:

import AtatusRUM

RUMMonitor.shared().addAttribute(forKey: "tenant", value: "acme")
RUMMonitor.shared().addAttributes(["feature.new_checkout": true, "cart.items": 3])

RUMMonitor.shared().removeAttribute(forKey: "tenant")
RUMMonitor.shared().removeAttributes(forKeys: ["cart.items"])

View attributes apply to the active view only, which is the right scope for something that describes one screen:

RUMMonitor.shared().addViewAttribute(forKey: "product.id", value: "SKU-42")
RUMMonitor.shared().removeViewAttribute(forKey: "product.id")

Send custom events

Views

Track a screen yourself when the automatic predicates cannot name it correctly, for example a screen rendered by a single container controller:

RUMMonitor.shared().startView(key: "checkout", name: "Checkout")
RUMMonitor.shared().stopView(key: "checkout")

A view started with a key must be stopped with the same key. Starting a new view stops the previous one, so you do not need to pair them when you navigate forward.

Actions

Report an action the SDK cannot see, such as a gesture handled by your own recognizer:

RUMMonitor.shared().addAction(type: .tap, name: "Apply coupon")

addAction is for an instantaneous action. For one with a duration, bracket it:

RUMMonitor.shared().startAction(type: .custom, name: "Import photos")
// work
RUMMonitor.shared().stopAction(type: .custom, name: "Import photos")

The action types are .tap, .click, .scroll, .swipe, and .custom.

Errors

Report a handled error, so a failure your code recovers from is still visible:

do {
    try importPhotos()
} catch {
    RUMMonitor.shared().addError(error: error, source: .source)
}

See Error Tracking for error sources, fingerprints, and crash reporting.

Resources

Report a request made by a client the SDK cannot instrument. See Network Tracking.

Feature flag evaluations

Record which variant a user received, so you can compare errors and performance between variants:

RUMMonitor.shared().addFeatureFlagEvaluation(name: "new-checkout", value: true)

Report the evaluation wherever your flag library resolves it, whichever library that is. Evaluations are attached to the active view and to the errors recorded in it, and are cleared when the view stops, so report them on each screen that depends on the flag rather than once at launch.

Modify or drop events

An event mapper runs on every event of its type before it is uploaded. Use it to redact a URL, rename a view, or drop an event you do not want:

RUM.enable(
    with: RUM.Configuration(
        viewEventMapper: { event in
            var event = event
            event.view.url = redact(event.view.url)
            return event
        },
        resourceEventMapper: { event in
            if event.resource.url.contains("/health") {
                return nil
            }
            return event
        }
    )
)

Control the session

Read the current session ID to attach it to a support ticket or your own logs:

RUMMonitor.shared().currentSessionID { sessionID in
    guard let sessionID = sessionID else { return }
    print("Atatus session: \(sessionID)")
}

End the session yourself, for example on sign-out, so the next user's activity starts a new one:

RUMMonitor.shared().stopSession()

To react to each new session, pass onSessionStart:

RUM.enable(
    with: RUM.Configuration(
        onSessionStart: { sessionID, isDiscarded in
            print("session \(sessionID), discarded by sampling: \(isDiscarded)")
        }
    )
)

Manage stored data

These apply to data the SDK has collected but not yet uploaded:

// Delete everything waiting on disk, for example after the user withdraws consent
Atatus.clearAllData()

// Stop the SDK instance; nothing is collected afterwards
Atatus.stopInstance()

Atatus.isInitialized() reports whether an instance is running, which is useful in a shared framework that must not initialize twice.

Run more than one instance

A single instance covers almost every application. If you need to send data to two accounts or two regions, name each instance and pass it to each product:

let core = Atatus.initialize(
    with: Atatus.Configuration(licenseKey: "<LICENSE_KEY>", env: "<ENV_NAME>"),
    trackingConsent: .granted,
    instanceName: "secondary"
)

RUM.enable(with: RUM.Configuration(), in: core)
RUMMonitor.shared(in: core).startView(key: "checkout", name: "Checkout")

Every API that touches the SDK takes an in core: parameter, which defaults to the unnamed instance.

Debugging

Print what the SDK is doing, in debug builds only:

#if DEBUG
Atatus.verbosityLevel = .debug
#endif

To see view and action boundaries on the device while you work, turn on the RUM debug overlay:

RUMMonitor.shared().debug = true

Next steps

• Report API calls as resources with Network Tracking.
• Measure launch time, frame rate, and hangs with Mobile Vitals.
• Report crashes and custom errors with Error Tracking.