iOS RUM SDK Integration Guide

Overview

Flashcat iOS RUM SDK supports iOS 12.0, iPadOS 12.0, tvOS 12.0 and above. By integrating the SDK, you can monitor your iOS application's performance, errors, and user behavior in real-time.

Integration Steps

Step 1: Add SDK Dependencies

Flashcat iOS SDK supports installation via Swift Package Manager.

In Xcode, open your project and select File > Add Package Dependencies

Enter the Flashcat SDK Git repository URL in the search bar:

https://github.com/flashcat-cloud/fc-ios-sdk

Select the desired version or branch

In Add to Target, select your application target

Add the following package dependencies:

FlashcatCore: Core SDK

FlashcatRUM: RUM functionality module

Step 2: Retrieve Application Information from the Console

In the RUM Application Management page of the Flashcat console:

Create or select an iOS application

Obtain the following information:

Application ID: Application unique identifier

Client Token: Client access token

Step 3: Initialize SDK

Initialize the Flashcat SDK in the application(_:didFinishLaunchingWithOptions:) method of your AppDelegate.swift:

Initialization Parameters

clientToken: Client token retrieved from the Flashcat console (required)

env: Environment name, such as production, staging (required)

site: Data reporting site, options: .us1, .us3, .us5, .eu1, .ap1 (required)

trackingConsent: User tracking consent status, options:

.pending: SDK starts collecting and batching data but does not send to Flashcat, waiting for new tracking consent value

.granted: SDK starts collecting data and sending to Flashcat

.notGranted: SDK does not collect any data

You can dynamically modify the tracking consent status after initialization through Flashcat.set(trackingConsent:).

Step 4: Enable RUM Features and Start Sending Data

Configure and enable RUM features. It is recommended to enable them as early as possible in AppDelegate:

RUM Configuration Parameters

applicationID: RUM application ID retrieved from the console

uiKitViewsPredicate: UIKit view tracking strategy

uiKitActionsPredicate: UIKit user action tracking strategy

swiftUIViewsPredicate: SwiftUI view tracking strategy

swiftUIActionsPredicate: SwiftUI user action tracking strategy

urlSessionTracking: URLSession network request tracking configuration

Step 5: Track Network Events

Enable URLSession Tracking

To monitor network requests sent from URLSession instances, you need to enable URLSessionInstrumentation and pass in your delegate class type:

After configuration, the SDK automatically tracks all network requests, including:

Request URL, method, status code

Request and response header information

Request duration and data size

Network error information

Note: Only network requests initiated when a view is active will be tracked.

View Tracking

Flashcat iOS SDK supports automatic tracking of UIKit and SwiftUI views.

UIKit View Automatic Tracking

UIKit views are automatically tracked through the default DefaultUIKitRUMViewsPredicate. The SDK tracks the lifecycle of UIViewController, automatically recording view display and hiding.

SwiftUI View Tracking

For SwiftUI applications, you need to manually add tracking code to the view:

The trackRUMView(name:) method automatically starts and stops view tracking when the SwiftUI view appears and disappears.

Custom View Tracking

If you need more fine-grained control, you can manually track views:

User Action Tracking

UIKit Action Automatic Tracking

User actions in UIKit (such as button clicks, switch toggles, etc.) are automatically tracked through DefaultUIKitRUMActionsPredicate.

SwiftUI Action Tracking

For SwiftUI controls, you can add the .trackRUMTapAction(name:) modifier:

Note: Using .trackRUMTapAction(name:) inside List may affect default gestures (for example, disabling Button actions or breaking NavigationLink). For List elements, it is recommended to use the custom action API.

Custom Action Tracking

Manually track user actions:

Track iOS Errors

Flashcat iOS SDK automatically captures application crashes and uncaught exceptions. You can also manually record errors:

All error information will be displayed in the RUM Explorer of the Flashcat console, including error stack, attributes, and JSON details.

Track Background Events

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

Add the following code when configuring RUM:

Track User Information

You can set user information for the current session:

Send Data When Device is Offline

The iOS SDK ensures data availability when the user's device is offline. In cases of weak network signals or low device battery, all events are first stored in batches on the local device.

Batches are sent as soon as the network becomes available and the battery is sufficient, ensuring the Flashcat SDK doesn't affect the end-user experience. If the network is unavailable while the app is running in the foreground, or if data upload fails, the batch is retained until it is successfully sent.

This means that even if users open your app while offline, no data is lost. To ensure the SDK doesn't use too much disk space, old data on disk is automatically discarded.

WebView Integration

If your iOS application includes WKWebView, you can enable WebView tracking in the following way:

Add WebView Dependencies

Swift Package Manager

When adding package dependencies, also add the FlashcatWebView module.

Enable WebView Tracking

Enable WebView tracking in your ViewController:

Parameter Description:

webView: The WKWebView instance to track

hosts: List of allowed domains for tracking, supports wildcards

This way, web pages in your WebView can be associated with native app RUM data.

Disable Automatic User Data Collection

To comply with privacy regulations or organizational data governance policies, you may need to disable automatic user data collection.

To disable automatic collection of client IP or geographic location data:

After creating the application, navigate to the Application Management page and click on your application

Click User Data Collection

Use the switches to control these settings

Verify Integration

After integration is complete, you can verify successful integration through the following steps:

Check Console Logs: Search for the Flashcat keyword in the Xcode console to view SDK initialization and data reporting logs

Access Console: Log in to the Flashcat console and navigate to the corresponding RUM application to check if data is being reported

Trigger Test Events:

Open different pages of the app to verify page view events

Perform user operations (clicks, swipes, etc.) to verify interaction events

Trigger network requests to verify resource loading events

Manually trigger an error to verify error tracking

Supported Versions

Flashcat iOS SDK supports the following platforms and versions:

iOS: 12.0 and above

iPadOS: 12.0 and above

tvOS: 12.0 and above

macOS: 10.14 and above (Mac Catalyst)

Language Support:

Swift 5.0 and above

Objective-C

SDK Integration

Overview#

Integration Steps#

Step 1: Add SDK Dependencies#

Step 2: Retrieve Application Information from the Console#

Step 3: Initialize SDK#

Initialization Parameters#

Step 4: Enable RUM Features and Start Sending Data#

RUM Configuration Parameters#

Step 5: Track Network Events#

Enable URLSession Tracking#

View Tracking#

UIKit View Automatic Tracking#

SwiftUI View Tracking#

Custom View Tracking#

User Action Tracking#

UIKit Action Automatic Tracking#

SwiftUI Action Tracking#

Custom Action Tracking#

Track iOS Errors#

Track Background Events#

Track User Information#

Send Data When Device is Offline#

WebView Integration#

Add WebView Dependencies#

Swift Package Manager#

Enable WebView Tracking#

Disable Automatic User Data Collection#

Verify Integration#

Supported Versions#

Further Reading#