Skip to main content
This page covers advanced use of the iOS RUM SDK. Topics include manual tracking of views, actions, resources, and errors, global attributes and user information, and modifying or discarding events. It also covers sampling, remote configuration, and distributed tracing.
The SDK is compatible with the Datadog open-source protocol. Dependencies added through Swift Package Manager or CocoaPods use names like FlashcatCore and FlashcatRUM, while code imports modules like DatadogCore and DatadogRUM, so Datadog ecosystem docs and examples apply directly.

Enrich user sessions

Custom views

By default, the RUM SDK automatically tracks UIViewController and SwiftUI View. You can also track specific views manually, or add custom attributes to automatically tracked views.
Call RUMMonitor.shared().startView() to start tracking a new RUM view. All views with the same key are grouped together in the RUM Explorer.
Parameters:
  • key (String) - Unique identifier for the view; use the same key for startView and stopView
  • name (String) - Name of the view
  • attributes (Dictionary) - Attributes attached to the view (optional)

Custom Actions

In addition to automatically tracked user actions, you can manually track specific custom actions (taps, scrolls, swipes, and so on).
When you call addAction(), the RUM SDK creates a RUM action and attaches all new resources, errors, and long tasks to it until the view is considered fully loaded.

Custom resources

The Flashduty iOS SDK automatically tracks network requests made through an instrumented URLSession. You can also track custom resources manually (third-party APIs, GraphQL queries, and so on).
The resourceKey must be unique per call so the RUM iOS SDK can match a resource’s start with its completion.

Custom errors

To track a specific error, notify RUMMonitor when it happens:
For more on error reporting, see iOS Error Reporting.

Track custom global attributes

Besides the default attributes the SDK captures, you can add custom global attributes to every RUM event. Use them to filter and group by business information (cart value, user tier, ad campaign) and to compare performance and error distribution across user groups.
Reserved keys: the following keys are used internally by the SDK and cannot be used: date, error.kind, error.message, error.stack, error.source_type, view.id, view.url, view.loading_time, view.referrer, application.id

Track user sessions

Adding user information to RUM sessions lets you follow a specific user’s journey and see which users are most affected by errors.
Only standard user fields are supported: id, name, email, and anonymous_id. Other user attributes are not supported. If needed, configure them under context.
Parameters:
  • usr.id (String) - Unique user identifier
  • usr.name (String) - User-friendly name, displayed by default in the RUM UI
  • usr.email (String) - User email, displayed when no name is set
  • All attributes are optional; provide at least one

Track background events

You can track events that happen while the app runs in the background (such as crashes and network requests).
Tracking background events may create additional sessions, which can affect billing. If you have questions, contact Flashduty support.

Initialization parameters

You can set the following properties when creating the SDK configuration:

App Hang Detection

An App Hang is a period during which the main thread is blocked and the UI cannot respond to user input. On iOS it is the only data source behind the Unresponsive Time Rate metric in the analytics dashboard.
appHangThreshold defaults to nil, which means App Hang detection is off. Unless you set it explicitly, your iOS app reports no App Hang data and the “Unresponsive Time Rate” card stays empty.
Notes:
  • The minimum allowed value is 0.1 seconds; lower values are raised to 0.1 automatically. For production, 0.25–0.5 seconds is recommended, as a lower threshold produces a lot of noise.
  • The SDK detects hangs with a 2.5% tolerance, so hangs lasting very close to the threshold may not be reported.
  • Enable crash reporting as well, otherwise App Hang errors are reported without a stack trace.
  • An App Hang that never recovers, and ends with the system terminating the app, is recorded as a fatal error; non-fatal hangs are recorded as errors with error.category = App Hang. Both count toward the ANR rate, not the crash count or the crash rate.
  • Android has no equivalent option: its main-thread freeze threshold is fixed at 5 seconds.

Automatically track views

To track views automatically, set uiKitViewsPredicate or swiftUIViewsPredicate when initializing RUM. For UIKit, use the DefaultUIKitRUMViewsPredicate class:
For SwiftUI, use the DefaultSwiftUIRUMViewsPredicate class:
You can also implement a custom predicate to customize tracking behavior.

Automatically track User Actions

To track user actions automatically, set uiKitActionsPredicate or swiftUIActionsPredicate when initializing RUM. For UIKit:
For SwiftUI:

Automatically track network requests

To track network requests (resources and errors) automatically, set urlSessionTracking when initializing RUM and enable URLSessionInstrumentation:
To correlate RUM resources with backend traces, configure firstPartyHostsTracing; see Integrate RUM with Distributed Tracing.

Automatically track errors

All fatal and non-fatal iOS errors are collected automatically, with full error details and the metadata of the current RUM view attached. Fatal errors include app crashes. Non-fatal errors include:
  • Swift errors: errors thrown with Swift throw
  • Objective-C exceptions: Objective-C exceptions
View error details in the RUM Explorer and Error Tracking.

Modify or discard RUM events

Before RUM events are sent to Flashduty, you can modify them or drop them entirely with event mappers, which you set when creating the RUM configuration:
Each mapper is a Swift closure with the signature (T) -> T?, where T is the concrete RUM event type. This lets you change parts of an event before it is sent. For example, to redact sensitive information in a RUM resource’s url, implement a custom redacted(_:) -> String function and use it in resourceEventMapper:
Returning nil from the error, resource, or action mapper drops the event entirely; it is not sent to Flashduty. The view event mapper must not return nil (to drop a view, customize your UIKitRUMViewsPredicate implementation; see Automatically Track Views). For example, to drop actions whose target name contains “password”:
Depending on the event type, only certain attributes can be modified:

Get the RUM session ID

The RUM session ID is useful for troubleshooting. For example, attach it to support requests, emails, or bug reports so your support team can find the user’s session in Flashduty later. You can read the session ID at runtime without waiting for the sessionStarted event:
To comply with GDPR, the Flashduty iOS SDK requires a tracking consent value at initialization. trackingConsent can be one of: To change the consent value after initialization, call Datadog.set(trackingConsent:). The SDK changes its behavior accordingly. For example, if the current consent is .pending:
  • changing it to .granted sends all current and future data to Flashduty;
  • changing it to .notGranted wipes all current data and stops collecting future data.

Data management

Clear all data

Delete all unsent data stored by the SDK with the Datadog.clearAllData() API:

Stop data collection

Use the Datadog.stopInstance() API to stop a named SDK instance (or the default instance if the name is nil) from collecting and uploading further data.
Calling this disables the SDK and all active features such as RUM. To resume collection, you must initialize the SDK again. Use this API if you want to change the configuration dynamically.

Sampling

By default, RUM collects data for all sessions. Set a sample rate (percentage) with sessionSampleRate to reduce the number of sessions collected. For example, to collect 90% of sessions:
Sampled-out sessions collect no views or related telemetry.

Remote configuration

Starting with SDK 0.6.0, the session sample rate can be adjusted online from the console under Application Management → Remote Configuration, with no code change or new release. The feature is off by default and has to be enabled at initialization:
Once enabled:
  • The SDK requests the configuration from the RUM intake when RUM.enable() is called, and again each time a new session is created. A rate published in the console applies to the next new session; a session already under way is not affected.
  • The delivered values are persisted locally, so the first session after a cold start is already drawn under the last delivered rate.
  • A failed, timed-out or unreadable response leaves the values in force untouched; they are never cleared. When remote configuration is disabled in the console, the SDK falls back to the sessionSampleRate passed at initialization.
  • The iOS SDK reads only the session sample rate and custom configuration keys; the other settings have no effect. Read the custom keys with RUMMonitor.shared().getRemoteConfig(), which returns nil when remote configuration is off or the console set none.
To decide sampling by your own business rules, use the beforeSampling callback. Before each new session is sampled, the callback receives the rate that would apply (sessionSampleRate) and the console’s custom keys (custom). Return a rate to override it, or nil to keep it. It runs synchronously inside session creation, so keep it fast and non-blocking; a value outside 0–100 is ignored.
To collect the current user regardless of the sample rate, for example while investigating one user’s issue, call RUMMonitor.shared().setForcedSession(). Every later session in the process is collected. A session already in progress keeps its sampling decision. For the console side (settings, publishing and when a version takes effect), see Application Management · Remote Configuration.

Integrate RUM with distributed tracing

Correlate requests from your iOS app with their backend traces to see frontend, backend, infrastructure, and log data in one place. This helps you pinpoint where a problem is.

Configuration

Initialize the RUM SDK and use firstPartyHostsTracing to list your app’s API domains:
Parameters:
  • hosts: list of domains to trace
  • sampleRate: percentage of requests to trace (0–100), default 100
For the format and an example of the traceparent and tracestate headers, see Tracing header information.

Verification

After adding the configuration, inspect requests sent from your app in Xcode’s network debugging tools or a proxy (such as Charles or Proxyman). If they carry these headers, the configuration is correct.

Best practices

  • Make sure applicationID and clientToken are configured correctly, or data cannot be uploaded.
  • Tune the sample rate and privacy settings to your app’s needs to balance data volume and compliance.
  • In event mappers, only modify the attributes listed as modifiable above.
  • For complex view tracking scenarios, implement a custom ViewsPredicate.

SDK Integration

Learn how to integrate the iOS SDK

Data Collection

Learn about the data types the SDK collects

Compatibility

Learn about SDK compatibility requirements