# iOS Copy as Markdown[Open in ChatGPT](https://chatgpt.com/?q=Read%20https%3A%2F%2Fcoralogix.com%2Fdocs%2Fuser-guides%2Frum%2Fsdk-installation%2Fapple%2Fios.md%20and%20help%20me%20with%20my%20question%20about%20this%20Coralogix%20documentation%20page.)[Open in Claude](https://claude.ai/new?q=Read%20https%3A%2F%2Fcoralogix.com%2Fdocs%2Fuser-guides%2Frum%2Fsdk-installation%2Fapple%2Fios.md%20and%20help%20me%20with%20my%20question%20about%20this%20Coralogix%20documentation%20page.) This guide provides instructions for integrating the Coralogix RUM SDK into iOS applications for UIKit and SwiftUI projects. It also details the configuration options, logging functionalities, and best practices for using method swizzling and SwiftUI modifiers to monitor and analyze app performance and user interactions. ## Prerequisites[​](#prerequisites "Direct link to Prerequisites") * **iOS**: ver. 14 or above * **Swift**: ver. 5.9 or above * **Xcode**: ver. 14 or above ## Features[​](#features "Direct link to Features") In addition to capturing HTTP requests (instrumentation using `URLSession`), this SDK can intercept the following telemetry data: * Unhandled exceptions, including `NSException`, `NSError`, and `Error`. * Custom logs. * Crashes, using `PLCrashReporter`. * Page navigation, using method swizzling for UIKit and modifiers for SwiftUI. ## Installation[​](#installation "Direct link to Installation") The Coralogix iOS SDK can be installed via Swift Package Manager or CocoaPods. ### Swift Package Manager[​](#swift-package-manager "Direct link to Swift Package Manager") 1. Open **File > Add Package Dependencies**. 2. Search for: `git@github.com:coralogix/cx-ios-sdk` 3. Select the **Up to Next Major Version** option. ### CocoaPods[​](#cocoapods "Direct link to CocoaPods") Add the Coralogix pod to your `Podfile`: ``` pod 'Coralogix' pod 'SessionReplay' # Only if you use Session Replay ``` Then run `pod install` from your project root. ## Initialization[​](#initialization "Direct link to Initialization") Call the SDK as early in your application lifecycle as possible, ideally in `applicationDidFinishLaunching` in `AppDelegate`. ### UIKit (AppDelegate)[​](#uikit-appdelegate "Direct link to UIKit (AppDelegate)") 1. Use the following code. ``` import UIKit import Coralogix @main class AppDelegate: UIResponder, UIApplicationDelegate { var coralogixRum: CoralogixRum? func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool { let domain = CoralogixDomain.US2 let options = CoralogixExporterOptions( coralogixDomain: domain, userContext: nil, environment: "ENVIRONMENT", application: "APP-NAME", version: "APP-VERSION", publicKey: "API-KEY", ignoreUrls: [], ignoreErrors: [], customDomainUrl: nil, labels: ["item": "playstation 5", "itemPrice": 1000], debug: false ) self.coralogixRum = CoralogixRum(options: options) return true } } ``` ### SwiftUI[​](#swiftui "Direct link to SwiftUI") Create a SwiftUI project to use Coralogix in your app. It's required if the Swift UI doesn't include `AppDelegate` or `SceneDelegate` files. 1. Use the following code. ``` import SwiftUI import Coralogix @main struct DemoAppApp: App { @State private var coralogixRum: CoralogixRum init() { let domain = CoralogixDomain.US2 let options = CoralogixExporterOptions( coralogixDomain: domain, userContext: nil, environment: "ENVIRONMENT", application: "APP-NAME", version: "APP-VERSION", publicKey: "TOKEN", ignoreUrls: [], ignoreErrors: [], customDomainUrl: nil, labels: ["item": "playstation 5", "itemPrice": 1000], debug: false ) self.coralogixRum = CoralogixRum(options: options) } var body: some Scene { WindowGroup { ContentView(coralogixRum: $coralogixRum) } } } ``` Refer to the following fields for `CoralogixExporterOptions`. | Property | Type | Description | Required | | ------------------- | ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | | userContext | UserContext? | Configuration for user context. | No | | debug | Bool | Turns on/off internal debug logging. | No | | ignoreUrls | \[String]? | URLs that partially match any regex in ignoreUrls will not be traced. | No | | ignoreErrors | \[String]? | A pattern for error messages which should not be sent to Coralogix. | No | | coralogixDomain | CoralogixDomain | [Coralogix domain](https://coralogix.com/docs/docs/user-guides/account-management/account-settings/coralogix-domain/.md) | Yes | | publicKey | String | Coralogix token, publicly-visible public\_key value. This is a required property. | Yes | | environment | String | Specifies the environment, such as development, staging, or production. | Yes | | application | String | Name of the application | Yes | | version | String | Version of the application | Yes | | customDomainUrl | String? | Ignores CoralogixDomain URL and routes all data calls to a specific URL. | No | | labels | \[String: Any]? | Sets labels that are added to every span. | No | | beforeSend | `((Event) -> Event?)?` | Callback to inspect, modify, or discard each event before it reaches Coralogix. Return `nil` to drop. See [Modify events with beforeSend](#modify-events-with-beforesend). | No | | tracesExporter | `((CoralogixTraceExporterData) -> Void)?` | Callback invoked for every span batch. See [Trace exporter](#trace-exporter). | No | | networkExtraConfig | `[NetworkCaptureRule]?` | Per-URL rules for capturing request and response headers and payloads. See [Network capture rules](#network-capture-rules). | No | | proxyUrl | String? | Routes all RUM data through a proxy URL. | No | | traceParentInHeader | \[String: Any]? | Configures W3C `traceparent` header propagation for distributed tracing. | No | | collectIPData | Bool | Send the client IP for region detection. Defaults to `true`. | No | | sessionSampleRate | Int | Percentage of overall sessions tracked, 0–100. Defaults to `100`. | No | | enableSwizzling | Bool | Method swizzling for `URLSession` instrumentation. Defaults to `true`. | No | ## Instrumentation[​](#instrumentation "Direct link to Instrumentation") Enable or disable specific instrumentation (see the list below), with the default set to all trues. Each instrumentation controls the data the SDK will track and collect. * **mobileVitals** – Automatically collects key performance metrics that reflect app responsiveness and rendering quality. The SDK gathers these metrics every 15 seconds. Metrics include CPU, memory, FPS, cold start, warm start, and ANR events. Learn more in [Mobile Vitals](https://coralogix.com/docs/docs/user-guides/rum/product-features/mobile-performance/.md). * **ANR** – Automatically detects Application Not Responsive (ANR) metric. * **navigation** – Identifies user movement between pages (ViewController call) while extracting the view name. * **custom** – Allows developers to define and track custom events, giving insights into specific actions or behaviors in the application that are critical to the business. * **errors** – Captures network errors and other issues in the application. This data helps diagnose and resolve bugs or failures that affect the user experience. * **network** – Monitors all network calls. * **userActions** – Catches user actions, such as button taps, tab activations, and other navigation controllers. It creates a span with a severity level of `info` and an event type of `user-interaction`, incorporating details about the element, including the text displayed on it. * **appLifeCycle** – Captures app lifecycle events that occur during runtime, providing insights into the application's behavior and performance. * **application(\_:didFinishLaunchingWithOptions:)** – Called after the app has launched, this is where you establish the initial app state, including setting up the user interface and restoring previous sessions. * **applicationDidBecomeActive(\_:)** – Called when the app becomes active and is ready for user interaction, this is the ideal moment to restart any tasks that were paused or not yet initiated. * **applicationDidEnterBackground(\_:)** – Called when the app is about to move from the foreground to the background. This is where you should release shared resources, save user data, and store enough app state to restore the app to its current state if it's terminated later. * **applicationWillTerminate(\_:)** – Called when the app is about to terminate, this is your final opportunity to save data and release any resources. * **applicationDidReceiveMemoryWarning(\_:)** – Called when the app receives a memory warning from the system, this is the time to release any non-essential memory to ensure your app continues to run smoothly. * **application(\_:open:options:)** – Called when the app is requested to open a URL, typically from another app, this allows you to manage deep linking and facilitate inter-app communication. * **application(\_:didReceiveRemoteNotification:fetchCompletionHandler:)** – Called when a remote notification is received, this provides your app an opportunity to fetch new content in the background. This function cannot be called automatically. Use the custom log API to initiate it. All events will arrive to the Coralogix as an `info` log type and the message field will be the event itself (`appDidBecomeActiveNotification`). For example, ``` public func log(severity: CoralogixLogSeverity, message: String, data: [String: Any]? = nil) { if CoralogixRum.isInitialized { self.logWith(severity: severity, message: message, data: data) } } ``` ### Mobile Vitals[​](#mobile-vitals "Direct link to Mobile Vitals") Set which Mobile Vitals you want to track on iOS. By default, all detectors are enabled. You can selectively enable or disable specific detectors (for example, CPU or memory) using the `mobileVitals` property in `CoralogixExporterOptions`. ``` let config = CoralogixExporterOptions( // ... mobileVitals: [ .cpuDetector: true, .memoryDetector: false // disables memory detector ] ) ``` You can configure the following Mobile Vital detectors: | Detector key | Description | | --------------------------- | ------------------------------------ | | `.cpuDetector` | CPU utilization and main-thread time | | `.memoryDetector` | Memory footprint and utilization | | `.renderingDetector` | Frame rate (FPS) | | `.coldDetector` | App cold start duration | | `.warmDetector` | App warm start duration | | `.slowFrozenFramesDetector` | Slow and frozen frame counts | ### Example[​](#example "Direct link to Example") ``` let options = CoralogixExporterOptions(coralogixDomain: CoralogixDomain.US2, userContext: nil, environment: "ENVIRONMENT", application: "APP-NAME", version: "APP-VERSION", publicKey: "TOKEN", ignoreUrls: [], //[".*\\.il$", "https://www.coralogix.com/academy"], ignoreErrors: [], //[".*errorcode=.*", "Im cusom Error"], customDomainUrl: nil, labels: [:], instrumentations: [.navigation: false, .mobileVitals: false, .custom: true, .errors: true, .userActions: true, .network: true, .lifeCycle: true], mobileVitals: [.cpuDetector: true, .warmDetector: true, .coldDetector: true, .slowFrozenFramesDetector: true, .memoryDetector: true, .renderingDetector: true], debug: false) ``` ## Configuration[​](#configuration "Direct link to Configuration") ### Network capture rules[​](#network-capture-rules "Direct link to Network capture rules") By default, the SDK captures request URLs, status codes, and timings. Use `networkExtraConfig` to capture specific request and response headers or payloads on a per-URL basis. ``` let options = CoralogixExporterOptions( // ... networkExtraConfig: [ NetworkCaptureRule( urlPattern: "https://api.example.com/.*", reqHeaders: ["X-Request-Id"], resHeaders: ["X-Response-Time"], collectReqPayload: true, collectResPayload: false ) ] ) ``` | `NetworkCaptureRule` field | Description | | -------------------------- | ------------------------------------------------------------ | | `urlPattern` | Regex pattern that matches request URLs the rule applies to. | | `reqHeaders` | List of request header names to capture. | | `resHeaders` | List of response header names to capture. | | `collectReqPayload` | When `true`, capture the request body. | | `collectResPayload` | When `true`, capture the response body. | Captured headers and payloads are visible on each request span in the Coralogix RUM UI. ### Trace exporter[​](#trace-exporter "Direct link to Trace exporter") Forward span data to your own collector or backend by configuring a trace exporter callback. The callback receives every span batch the SDK produces, in OTLP-compatible shape. Spans continue to flow to Coralogix when this callback is set. ``` let options = CoralogixExporterOptions( // ... tracesExporter: { data in // data.tracesData.resourceSpans[].scopeSpans[].spans[] // data.jsonString — JSON-encoded OTLP payload forwardToCustomCollector(data.jsonString) } ) ``` ### Modify events with beforeSend[​](#modify-events-with-beforesend "Direct link to Modify events with beforeSend") Use `beforeSend` to inspect, transform, or discard events before they reach Coralogix. Return `nil` to drop the event. ``` let options = CoralogixExporterOptions( // ... beforeSend: { event in // Drop events from internal users. if event.userContext?.userEmail.contains("@coralogix.com") == true { return nil } return event } ) ``` ## Custom Spans[​](#custom-spans "Direct link to Custom Spans") Use Custom Spans to instrument business-critical operations in your iOS app. Spans appear in Coralogix as standalone records or grouped under a parent global span. ### Prerequisites[​](#prerequisites-1 "Direct link to Prerequisites") Set `traceParentInHeader: ["enable": true]` in `CoralogixExporterOptions` to enable the custom tracer. ### Get the tracer[​](#get-the-tracer "Direct link to Get the tracer") Acquire a tracer from your `CoralogixRum` instance. Optionally scope which auto-instruments are ignored within the span context: ``` let tracer = coralogixRum.getCustomTracer( ignoredInstruments: [.networkRequests, .errors] ) ``` ### Start a global span[​](#start-a-global-span "Direct link to Start a global span") A global span is a top-level operation. Add labels to enrich it: ``` let global = tracer.startGlobalSpan( name: "checkout-flow", labels: ["cart_size": 3, "currency": "USD"] ) ``` ### Add child spans[​](#add-child-spans "Direct link to Add child spans") Within a global span's context, create child spans for sub-operations: ``` global.withContext { let child = global.startCustomSpan(name: "fetch-prices") child.setAttribute(key: "endpoint", value: "/api/v1/prices") child.addEvent(name: "request-sent") // ... do work ... child.setStatus(.ok) child.endSpan() } global.endSpan() ``` Use `setStatus(.error)` on a span when the underlying operation fails. ## Integration functions[​](#integration-functions "Direct link to Integration functions") This section lists public functions used to interact with the Coralogix exporter. ### Set user context[​](#set-user-context "Direct link to Set user context") #### Example[​](#example-1 "Direct link to Example") ``` public func setUserContext(userContext: UserContext) ``` ### Set labels[​](#set-labels "Direct link to Set labels") #### Example[​](#example-2 "Direct link to Example") ``` public func set(labels: [String: Any]) ``` ### Report errors[​](#report-errors "Direct link to Report errors") #### Example[​](#example-3 "Direct link to Example") ``` public func reportError(exception: NSException) public func reportError(error: NSError) public func reportError(error: Error) public func reportError(message: String, data: [String: Any]?) ``` ### Log messages[​](#log-messages "Direct link to Log messages") Send log messages with customized severity levels. #### Example[​](#example-4 "Direct link to Example") ``` public func log(severity: CoralogixLogSeverity, message: String, data: [String: Any]?) ``` The `CoralogixLogSeverity` defines severity levels for logs in the Coralogix system. | Case | Raw Value | Severity | | -------- | --------- | -------------- | | debug | 1 | Debug-level | | verbose | 2 | Verbose-level | | info | 3 | Informational | | warn | 4 | Warning-level | | error | 5 | Error-level | | critical | 6 | Critical-level | #### Example[​](#example-5 "Direct link to Example") ``` coralogixRUM.log(severity: .error, message: "An error occurred in the application.", data: nil) ``` ### Utility methods[​](#utility-methods "Direct link to Utility methods") Inspect SDK state or update context at runtime. ``` // Confirm the SDK is initialized. let initialized = CoralogixRum.isInitialized // Read the current session ID, for example to attach to a support ticket. let sessionId = coralogixRum.getSessionId() // Update the application context after init. coralogixRum.setApplicationContext(name: "my-app", version: "1.2.0") ``` ### Shut down the exporter[​](#shut-down-the-exporter "Direct link to Shut down the exporter") Shut down the Coralogix exporter and mark it as uninitialized. #### Example[​](#example-6 "Direct link to Example") ``` public func shutdown() ``` ## Method swizzling and SwiftUI modifiers[​](#method-swizzling-and-swiftui-modifiers "Direct link to Method swizzling and SwiftUI modifiers") Use these best practices to dynamically alter the behavior of existing methods at runtime in Swift and Objective-C. * **Method Swizzling**: A technique used in Objective-C and Swift to change the implementation of an existing selector at runtime. Use it for injecting custom behavior without altering the original code. * **SwiftUI Modifiers**: A declarative and safe approach to modifying views through view modifiers, providing better readability and maintainability. In addition, using `CXViewModifier` and `trackCXView` method, you can add custom behavior to views in a SwiftUI-friendly way. ### Example[​](#example-7 "Direct link to Example") ``` import SwiftUI struct ContentView: View { var body: some View { Text("Hello, World!") .trackCXView(name: "ContentView") } } ```