iOS RUM SDK Advanced Configuration

Overview

Flashcat Real User Monitoring (RUM) provides various advanced configuration options that allow you to modify collected data and context according to your needs, supporting the following scenarios:

Protect sensitive data: Mask personally identifiable information and other sensitive data

Correlate user sessions: Associate user sessions with internal user identifiers for easier support and troubleshooting

Reduce data volume: Decrease RUM data collection volume through sampling to optimize costs

Enhance context: Add richer contextual information beyond default attributes

The following sections detail how to implement these features.

Enriching User Sessions

Custom Views

By default, the RUM SDK automatically tracks UIViewController or SwiftUI View. If you want to manually track specific views or add custom time and attributes to automatically tracked views, you can use the APIs provided by the RUM iOS SDK.

Manually Starting and Stopping Views

Call RUMMonitor.shared().startView(key:name:attributes:) to start tracking a new RUM view. All views with the same key will be grouped in the RUM Explorer.

When the view is no longer visible, call RUMMonitor.shared().stopView(key:attributes:) to stop tracking.

@import FlashcatObjc;
// in your `UIViewController`:

- (void)viewDidAppear:(BOOL)animated {
    [super viewDidAppear:animated];

    [[RUMMonitor shared] startViewWithKey:@"view-key" name:@"View Name" attributes:@{@"foo": @"bar"}];
}

- (void)viewDidDisappear:(BOOL)animated {
    [super viewDidDisappear:animated];

    [[RUMMonitor shared] stopViewWithKey:@"view-key" attributes:@{@"foo": @"bar"}];
}

Custom Actions

Besides automatically tracking user actions, you can also manually track specific custom actions (such as taps, scrolls, swipes, etc.) using RUMMonitor.shared().addAction(type:name:attributes:):

@import FlashcatObjc;

- (IBAction)didTapDownloadResourceButton:(UIButton *)sender {
    [[RUMMonitor shared] addActionWithType:RUMActionTypeTap name:sender.currentTitle attributes:@{@"resource_id": @"123"}];
}

Note: When using RUMMonitor.shared().addAction(type:name:attributes:), the RUM SDK creates a RUM action and attaches all new resources, errors, and long tasks to this action until the view is considered fully loaded.

Custom Resources

Flashcat iOS SDK automatically tracks network requests initiated through enabled URLSession. If you want to manually track custom resources (such as network requests, third-party provider APIs, GraphQL queries, etc.), you can use the following methods:

Call RUMMonitor.shared().startResource(resourceKey:request:attributes:) to start loading a resource, then call RUMMonitor.shared().stopResource(resourceKey:response:size:attributes:) when loading completes, or call RUMMonitor.shared().stopResourceWithError(resourceKey:error:attributes:) when loading fails:

@import FlashcatObjc;

// in your network client:
[[RUMMonitor shared] startResourceWithResourceKey:@"resource-key" request:request attributes:@{@"foo": @"bar"}];

[[RUMMonitor shared] stopResourceWithResourceKey:@"resource-key" response:response size:size attributes:@{@"foo": @"bar"}];

Note: The resourceKey used in both calls must be unique for the RUM iOS SDK to match the resource start with its completion.

Custom Errors

To track specific errors, notify RUMMonitor when an error occurs:

@import FlashcatObjc;

[[RUMMonitor shared] addErrorWithMessage:@"Error message"
                                    type:@"ErrorType"
                                  source:DDRUMErrorSourceCustom
                                   stack:@"Error stack trace"
                              attributes:@{@"foo": @"bar"}
                                    file:file
                                    line:line];

Tracking Custom Global Attributes

Flashcat iOS SDK automatically captures default RUM attributes. Additionally, you can add extra contextual information to RUM events, such as custom attributes.

Custom attributes enable you to filter and group observed user behavior information based on code-level information (such as shopping cart value, merchant tier, or advertising campaign).

Setting Custom Global Attributes

To set custom global attributes, use RUMMonitor.shared().addAttribute(forKey:value:):

@import FlashcatObjc;

[[RUMMonitor shared] addAttributeForKey:@"user_plan" value:@"premium"];

Note: You cannot use the following key names as they are used internally by the SDK: date, error.kind, error.message, error.stack, error.source_type, view.id, view.url, view.loading_time, view.referrer, application.id.

To remove a custom global attribute, use RUMMonitor.shared().removeAttribute(forKey:):

@import FlashcatObjc;

[[RUMMonitor shared] removeAttributeForKey:@"user_plan"];

Tracking User Sessions

Adding user information to RUM sessions allows you to:

Track browsing paths of specific users

Understand which users are most affected by errors

Monitor performance for key users

The following attributes are optional, and you should provide at least one:

usr.id (string): Unique user identifier

usr.name (string): User-friendly name, displayed by default in RUM UI

usr.email (string): User email, displayed if no name is provided

To identify user sessions, use Flashcat.setUserInfo(id:name:email:extraInfo:) after SDK initialization:

@import FlashcatObjc;

[Flashcat setUserInfoWithId:@"1234"
                       name:@"John Doe"
                      email:@"john@doe.com"
                  extraInfo:@{@"plan": @"premium", @"signup_date": @"2024-01-15"}];

Tracking Background Events

You can track events when the app is running in the background (such as crashes and network requests).

Add the trackBackgroundEvents setting when configuring RUM:

@import FlashcatObjc;

DDRUMConfiguration *configuration = [[DDRUMConfiguration alloc] initWithApplicationID:@"<RUM_APPLICATION_ID>"];
configuration.trackBackgroundEvents = YES;

[RUM enableWith:configuration];

Initialization Parameters

When creating Flashcat configuration, the following properties can be set:

Flashcat Configuration

Parameter	Type	Required	Description
`clientToken`	String	Yes	Client token
`env`	String	Yes	Environment name
`service`	String	No	Service name, defaults to app bundle identifier
`batchSize`	BatchSize	No	Batch upload data size, options: `.small`, `.medium`, `.large`
`uploadFrequency`	UploadFrequency	No	Data upload frequency, options: `.frequent`, `.average`, `.rare`

RUM Configuration

The following parameters can be set when creating RUM configuration:

Parameter	Type	Required	Description
`applicationID`	String	Yes	RUM application ID
`sessionSampleRate`	Float	No	Session sampling rate (0-100), default 100
`uiKitViewsPredicate`	UIKitRUMViewsPredicate	No	UIKit view tracking strategy
`uiKitActionsPredicate`	UIKitRUMActionsPredicate	No	UIKit action tracking strategy
`swiftUIViewsPredicate`	SwiftUIRUMViewsPredicate	No	SwiftUI view tracking strategy
`swiftUIActionsPredicate`	SwiftUIRUMActionsPredicate	No	SwiftUI action tracking strategy
`urlSessionTracking`	URLSessionTracking	No	URLSession network request tracking configuration
`trackBackgroundEvents`	Bool	No	Whether to track background events, default false
`trackFrustrations`	Bool	No	Whether to track user frustrations (such as error clicks), default true
`trackLongTasks`	Bool	No	Whether to track long tasks, default true
`longTaskThreshold`	TimeInterval	No	Long task threshold (seconds), default 0.1 seconds
`vitalsUpdateFrequency`	VitalsFrequency	No	Performance metrics update frequency, options: `.frequent`, `.average`, `.rare`, `.never`

Automatically Track Views

To enable automatic view tracking, 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 enable automatic user action tracking, set uiKitActionsPredicate or swiftUIActionsPredicate when initializing RUM.

For UIKit:

For SwiftUI:

Automatically Track Network Requests

To enable automatic network request tracking (resources and errors), set urlSessionTracking when initializing RUM and enable URLSessionInstrumentation:

You can also configure firstPartyHostsTracing to enable distributed tracing, associating RUM resources with backend traces:

Automatically Track Errors

All "fatal" and "non-fatal" iOS errors are automatically collected with full error details and metadata for the current RUM view.

Fatal errors include app crashes. Non-fatal errors include:

Swift errors: Errors thrown by Swift throw

Objective-C exceptions: Objective-C exceptions

You can view error details through RUM Explorer and Error Tracking.

Modifying or Dropping RUM Events

Before RUM events are sent to Flashcat, you can modify or completely drop them through Event Mappers.

Event mappers are set when creating RUM configuration:

@import FlashcatObjc;

DDRUMConfiguration *configuration = [[DDRUMConfiguration alloc] initWithApplicationID:@"<RUM_APPLICATION_ID>"];

[configuration setViewEventMapper:^DDRUMViewEvent * _Nonnull(DDRUMViewEvent * _Nonnull RUMViewEvent) {
    return RUMViewEvent;
}];

[configuration setErrorEventMapper:^DDRUMErrorEvent * _Nullable(DDRUMErrorEvent * _Nonnull RUMErrorEvent) {
    return RUMErrorEvent;
}];

[configuration setResourceEventMapper:^DDRUMResourceEvent * _Nullable(DDRUMResourceEvent * _Nonnull RUMResourceEvent) {
    return RUMResourceEvent;
}];

[configuration setActionEventMapper:^DDRUMActionEvent * _Nullable(DDRUMActionEvent * _Nonnull RUMActionEvent) {
    return RUMActionEvent;
}];

[configuration setLongTaskEventMapper:^DDRUMLongTaskEvent * _Nullable(DDRUMLongTaskEvent * _Nonnull RUMLongTaskEvent) {
    return RUMLongTaskEvent;
}];

Each mapper is a Swift closure with signature (T) -> T?, where T is the specific RUM event type. This allows changing parts of events before they're sent.

For example, to mask sensitive information in the url of a RUM Resource, implement a custom redacted(_:) -> String function and use it in resourceEventMapper:

DDRUMConfiguration *configuration = [[DDRUMConfiguration alloc] initWithApplicationID:@"<RUM_APPLICATION_ID>"];

[configuration setResourceEventMapper:^DDRUMResourceEvent * _Nullable(DDRUMResourceEvent * _Nonnull RUMResourceEvent) {
    return RUMResourceEvent;
}];

Returning nil from error, resource, or action mappers will completely drop the event; the event will not be sent to Flashcat. The value returned from view event mappers cannot be nil (to drop views, customize the UIKitRUMViewsPredicate implementation; see Automatic View Tracking).

Based on the event type, only certain specific attributes can be modified:

Event Type	Property Key	Description
RUMActionEvent	`RUMActionEvent.action.target?.name`	Action name
	`RUMActionEvent.view.url`	View URL associated with this action
RUMErrorEvent	`RUMErrorEvent.error.message`	Error message
	`RUMErrorEvent.error.stack`	Error stack trace
	`RUMErrorEvent.error.resource?.url`	Resource URL referenced by the error
	`RUMErrorEvent.view.url`	View URL associated with this error
RUMResourceEvent	`RUMResourceEvent.resource.url`	Resource URL
	`RUMResourceEvent.view.url`	View URL associated with this resource
RUMViewEvent	`RUMViewEvent.view.name`	View name
	`RUMViewEvent.view.url`	View URL
	`RUMViewEvent.view.referrer`	URL linking to initial page view

Getting RUM Session ID

Retrieving the RUM session ID is very useful for troubleshooting. For example, you can attach the session ID to support requests, emails, or error reports so that your support team can later find user sessions in Flashcat.

You can access the RUM session ID at runtime without waiting for the sessionStarted event:

@import FlashcatObjc;

[[RUMMonitor shared] currentSessionIDWithCompletion:^(NSString * _Nullable sessionId) {
    // use session ID
}];

To comply with GDPR regulations, Flashcat iOS SDK requires a tracking consent value at initialization.

The trackingConsent setting can be one of the following values:

.pending: Flashcat iOS SDK starts collecting and batching data but does not send to Flashcat. Flashcat iOS SDK waits for a new tracking consent value to decide how to handle batched data.

.granted: Flashcat iOS SDK starts collecting data and sends to Flashcat.

.notGranted: Flashcat iOS SDK does not collect any data. No logs, traces, or RUM events are sent to Flashcat.

After Flashcat iOS SDK initialization, to change the tracking consent value, use the Flashcat.set(trackingConsent:) API call. Flashcat iOS SDK will change its behavior based on the new value.

For example, if the current tracking consent is .pending:

If you change the value to .granted, Flashcat iOS SDK will send all current and future data to Flashcat;

If you change the value to .notGranted, Flashcat iOS SDK will clear all current data and not collect future data.

@import FlashcatObjc;

[Flashcat setWithTrackingConsent:DDTrackingConsentGranted];

Adding User Attributes

You can use the Flashcat.addUserExtraInfo(_:) API to attach additional user attributes to previously set attributes.

@import FlashcatObjc;

[Flashcat addUserExtraInfo:@{@"company": @"Flashcat"}];

Data Management

Clear All Data

You can optionally delete all unsent data stored by the SDK using the Flashcat.clearAllData() API:

@import FlashcatObjc;

[Flashcat clearAllData];

Stop Data Collection

You can use the Flashcat.stopInstance() API to stop a named SDK instance (or default instance if name is nil) from further collecting and uploading data.

@import FlashcatObjc;

[Flashcat stopInstance];

Calling this method disables the SDK and all active features like RUM. To resume data collection, you must reinitialize the SDK. If you want to dynamically change configuration, you can use this API.

Sampling

By default, Flashcat RUM collects data for all sessions. You can reduce the number of sessions collected by setting a sampling rate (percentage) through the sessionSampleRate parameter. For example, to collect 90% of sessions:

@import FlashcatObjc;

DDRUMConfiguration *configuration = [[DDRUMConfiguration alloc] initWithApplicationID:@"<RUM_APPLICATION_ID>"];
configuration.sessionSampleRate = 90;

[RUM enableWith:configuration];

Sampled sessions will not collect any views and their associated telemetry data.

Integrating RUM with Distributed Tracing

Integrating RUM with distributed tracing allows you to correlate requests from your iOS application with their corresponding backend traces. This combination enables you to see complete frontend and backend data at a glance.

Use frontend data from RUM along with backend, infrastructure, and log information from trace ID injection to locate issues anywhere in the stack and understand user experience.

Configuration Method

Initialize the RUM SDK, using firstPartyHostsTracing to configure your current app's API service domains:

@import FlashcatObjc;

DDRUMConfiguration *configuration = [[DDRUMConfiguration alloc] initWithApplicationID:@"<RUM_APPLICATION_ID>"];

DDURLSessionTracking *urlSessionTracking = [DDURLSessionTracking new];
[urlSessionTracking setFirstPartyHostsTracing:[DDRUMFirstPartyHostsTracing alloc] initWithHosts:@[@"api.example.com", @"example.com"] sampleRate:20];

configuration.urlSessionTracking = urlSessionTracking;

[RUM enableWith:configuration];

[DDURLSessionInstrumentation enableWithConfiguration:[DDURLSessionInstrumentationConfiguration alloc] initWithDelegateClass:[SessionDelegate class]]];

Parameter descriptions:

hosts: List of domains to trace

sampleRate: Percentage of requests to trace (0-100), default 100

How Correlation Works

The distributed tracing protocol is implemented by adding corresponding header fields (traceparent, tracestate) to HTTP headers. Here's an explanation of the corresponding headers:

traceparent: [version]-[trace id]-[parent id]-[trace flags]

version: Currently 00

trace id: 128-bit trace ID converted to 32 characters after hex processing

parent id: 64-bit span ID, 16 characters after hex processing

trace flags: Indicates whether sampled, 01 means sampled, 00 means not sampled

tracestate: dd=s:[sampling priority];o:[origin]

sampling priority: 1 means trace is sampled

origin: Always rum, indicating collection through RUM SDK

Example:

traceparent: 00-00000000000000008448eb211c80319c-b7ad6b7169203331-01
tracestate: dd=s:1;o:rum

How to Verify

After adding configuration, you can view requests sent from the app in Xcode's network debugging tools or proxy tools (such as Charles, Proxyman). If they correctly carry the corresponding headers, the configuration is correct.

Notes

Ensure applicationID and clientToken are configured correctly to avoid data upload failures

Adjust sampling rate and privacy settings according to app requirements, balancing data volume and compliance

Attributes modified in event mappers should follow the allowed modification attributes list

For complex view tracking scenarios, implementing custom ViewsPredicate is recommended

Advanced Configuration

Overview#

Enriching User Sessions#

Custom Views#

Manually Starting and Stopping Views#

Custom Actions#

Custom Resources#

Custom Errors#

Tracking Custom Global Attributes#

Setting Custom Global Attributes#

Tracking User Sessions#

Tracking Background Events#

Initialization Parameters#

Flashcat Configuration#

RUM Configuration#

Automatically Track Views#

Automatically Track User Actions#

Automatically Track Network Requests#

Automatically Track Errors#

Modifying or Dropping RUM Events#

Getting RUM Session ID#

Setting Tracking Consent (GDPR Compliance)#

Adding User Attributes#

Data Management#

Clear All Data#

Stop Data Collection#

Sampling#

Integrating RUM with Distributed Tracing#

Configuration Method#

How Correlation Works#

How to Verify#

Notes#

Further Reading#