iOS SDK Installation

SDK Initialization

Important

• The Clarity iOS SDK collects sessions from iOS versions within the supported range specified at Platform/Framework Support Matrix.
• While applications build and run successfully for iOS versions 13 and 14, data isn't sent to Clarity for these versions.
• Due to some SwiftUI limitations, it is strongly advised to review the SwiftUI Modifiers section for guidance.

Install the Clarity SDK in order to track how users interact with your app. The Clarity iOS SDK is available as a Swift package and a CocoaPods pod. It can take up to 2 hours to start seeing data.

Step 1

Swift Package Manager

Option 1: Using XCode

1. "Right click" on your XCode project and select Add Package Dependencies...
2. Paste https://github.com/microsoft/clarity-apps in the search bar, select clarity-apps, and select Add Package.

Option 2: If the Package.swift file is used, add Clarity package as a dependency:

let package = Package(
    // ...
    dependencies: [
        //// Option 1: Fetch latest version available. This allows automatic major version updates that may contain non-backward compatible changes.
        .package(url: "https://github.com/microsoft/clarity-apps", branch: "main")
        //// Option 2: Fetch a specific minor version range (For example, 3.0.0 up to, but not including, 4.0.0).
        // .package(url: "https://github.com/microsoft/clarity-apps", from: "3.0.0")
    ],
    targets: [
        .target(
            name: "<target-name>",
            dependencies: [
                .product(name: "Clarity", package: "clarity-apps")
            ]
        )
    ]
)

CocoaPods

Add Clarity to Podfile:

target '<target-name>' do
  use_frameworks!
  pod 'Clarity'
end

Step 2

Note

Initialization has to run from the main thread.

Swift

Add the following code to AppDelegate.swift file:

import Clarity

@main
class AppDelegate: UIResponder, UIApplicationDelegate {
    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        // Note: Replace `<project-id>` with actual project ID found Clarity Settings -> Overview page.
        // Note: Set `.verbose` value for `logLevel` parameter while testing to debug initialization issues.
        let clarityConfig = ClarityConfig(projectId: "<project-id>")
        ClaritySDK.initialize(config: clarityConfig)
        return true
    }
    // ...
}

For SwiftUI, you can add the initialization code to your App's init() function.

Objective-C

Add the following code to AppDelegate.m file:

#import "AppDelegate.h"

@import Clarity;

@implementation AppDelegate
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    // Note: Replace `<project-id>` with actual project ID found on Clarity Settings -> Overview page.
    ClarityConfig* config = [[ClarityConfig alloc] initWithProjectId:@"<project-id>"];

    // config.logLevel = LogLevelNone; // Note: Set `LogLevelVerbose` value while testing to debug initialization issues.

    [ClaritySDK initializeWithConfig:config];

    // ...
    return YES;
}
@end

Step 3

Once you integrated Clarity with your application, ensure the following if you want to test it on a device or a simulator:

1. Your device or simulator must be connected to the internet.
2. The iOS version on your device or simulator should be within the supported range specified at Platform/Framework Support Matrix.
3. For initial setup, consider setting the log level to Verbose. This provides detailed logs that can help identify any initialization issues.

Allow approximately 2 hours for complete sessions to appear in your Clarity project on the Clarity website. However, in-progress sessions can still be viewed in real time. See Clarity Recordings in Real Time.

Configuration options

class ClarityConfig {
    init(
        projectId: String,
        userId: String? = nil, // DEPRECATED
        logLevel: LogLevel = .none,
        applicationFramework: ApplicationFramework = .native
    ) { }
}

Project ID (projectId)

The unique identifier assigned to your Clarity project. You can find it on the Settings page of Clarity dashboard. This ID is essential for routing data to the correct Clarity project.

User ID (userId)

The unique identifier associated with the application user. This ID persists across multiple sessions on the same device.

• Deprecated: This field is deprecated and would be removed in a future major version. Use setCustomUserId instead.
• If userId isn't provided, a random one is generated automatically.
• Must be a base-36 string smaller than 1Z141Z4.
• If an invalid userId is supplied:
  • If customUserId isn't specified: userId acts as the customUserId, and a new random userId is assigned.
  • If customUserId is specified: the invalid userId is ignored.

Note

For greater flexibility in user identification, use the setCustomUserId API. Ensure that the customUserId length is between 1 and 255 characters.

Log Level (logLevel)

The level of logging to show in the device's or Xcode's console while debugging. By default, the SDK logs nothing.

Allowed log levels are:

• .verbose
• .debug
• .info
• .warning
• .error
• .none

Application framework (applicationFramework)

Signals to the SDK which framework is being used to develop the current application. This parameter is internal to the SDK and shouldn't be set manually.

Note

For Clarity versions 3.0.0 and above, the SDK supports SwiftUI. In earlier versions, the enableSwiftUI_Experimental configuration option is necessary to enable SwiftUI capture.

For Clarity versions 3.0.0 and above, the following configuration options are no longer configurable from code and can now be adjusted dynamically from the Clarity dashboard:

• Allow Metered Network Usage (allowMeteredNetworkUsage): Allows uploading session data to the servers on device's metered networks. By default, the SDK only uploads sessions on unmetered networks.
• Enable WebView Capture (enableWebViewCapture): Allows Clarity to capture the web views DOM content for recording and heatmap reconstruction.
• Disable on Low-End Devices (disableOnLowEndDevices): When enabled, Clarity doesn't capture any data for the low-end devices.

API

initialize()

static func initialize(config: ClarityConfig) -> Bool

Initializes Clarity to start capturing the current session data.

Parameters

config ClarityConfig

Configuration of Clarity that tunes the SDK behavior (for example, which project to send to, which log level to use, and so on).

Returns

Bool

true if Clarity initialization is possible; otherwise false.

Remarks

• The initialization function is asynchronous and returns before Clarity is fully initialized.
• For actions that require Clarity to be fully initialized, it's recommended to use the setOnSessionStartedCallback function.
• This function should only be called on the main thread.

pause()

static func pause()

Pauses the Clarity session capturing until a call to the resume function is made.

Remarks

This function should only be called on the main thread.

resume()

static func resume()

Resumes the Clarity session capturing only if it was previously paused by a call to the pause function.

Remarks

This function should only be called on the main thread.

isPaused()

static func isPaused() -> Bool

Checks if Clarity session capturing is currently paused based on an earlier call to the pause function.

Returns

Bool

true if Clarity session capturing is currently in the paused state based on an earlier call to the pause function; otherwise false.

startNewSession()

static func startNewSession(callback: OnSessionStartedCallback?) -> Bool {

Forces Clarity to start a new session asynchronously.

Parameters

callback OnSessionStartedCallback?

A callback that is invoked when the new session starts. The callback receives the new session ID as a string parameter.

Returns

Bool

true if a new session can start asynchronously; otherwise false.

Remarks

• This function is asynchronous and returns before the new session is started.
• Use the callback parameter to execute logic that needs to run after the new session begins.
• Events that occur before invoking the callback are associated with the previous session.
• To ensure proper association of custom tags, user ID, or session ID with the new session, set them within the callback.
• This function should only be called on the main thread.

maskView()

static func maskView(_ view: UIView)

Masks a specific UIView to prevent Clarity from capturing its content (text or images). Masked content is replaced with placeholders.

Parameters

view UIView

The UIView instance to mask its content.

Remarks

This function should only be called on the main thread.

unmaskView()

static func unmaskView(_ view: UIView)

Unmasks a specific UIView to allow Clarity to capture its content, even if it's a child of a masked view or within a masked screen.

Parameters

view UIView

The UIView instance to unmask its content.

Remarks

This function should only be called on the main thread.

setCustomUserId()

static func setCustomUserId(_ customUserId: String) -> Bool

Sets a custom user ID for the current session. This ID can be used to filter sessions on the Clarity dashboard.

Parameters

customUserId String

The custom user ID to associate with the current session. The value must be a nonempty string with a maximum length of 255 characters and can't consist only of whitespace.

Returns

Bool

true if the custom user ID was set successfully; otherwise false.

Remarks

• To ensure that the custom user ID is associated with the correct session, it's recommended to call this function within the callbacks of setOnSessionStartedCallback or startNewSession.
• Unlike the userID, the customUserId value has fewer restrictions.
• We recommend not to set any Personally Identifiable Information (PII) values inside this field.
• This function should only be called on the main thread.

setCustomSessionId()

static func setCustomSessionId(_ customSessionId: String) -> Bool

Sets a custom session ID for the current session. This ID can be used to filter sessions on the Clarity dashboard.

Parameters

customSessionId String

The custom session ID to associate with the current session. The value must be a nonempty string, with a maximum length of 255 characters, and can't consist only of whitespace.

Returns

Bool

true if the custom session ID was set successfully; otherwise false.

Remarks

• To ensure that the custom session ID is associated with the correct session, it's recommended to call this function within the callbacks of setOnSessionStartedCallback or startNewSession.
• This function should only be called on the main thread.

getCurrentSessionId()

static func getCurrentSessionId() -> String?

Returns the ID of the currently active Clarity session if a session has already started; otherwise nil.

Returns

String?

A string representing the ID of the currently active Clarity session if a session has already started; otherwise nil.

Remarks

• Deprecated: This API is deprecated and would be removed in a future major version. Use getcurrentsessionurl instead.
• The session ID can be used to correlate Clarity sessions with other telemetry services.
• Initially, this function might return nil until a Clarity session begins.
• To ensure a valid session ID, use this method within the callbacks of setOnSessionStartedCallback or startNewSession.
• This function should only be called on the main thread.

getCurrentSessionUrl()

static func getCurrentSessionUrl() -> String?

Returns the URL of the current Clarity session recording on the Clarity dashboard if a session has already started; otherwise nil.

Returns

String?

A string representing the URL of the current Clarity session recording on the Clarity dashboard if a session has already started; otherwise nil.

Remarks

• Initially, this function might return nil until a Clarity session begins.
• To ensure a valid session URL, use this method within the callbacks of setOnSessionStartedCallback or startNewSession.
• This function should only be called on the main thread.

setCustomTag()

static func setCustomTag(key: String, value: String) -> Bool

Sets a custom tag for the current session. This tag can be used to filter sessions on the Clarity dashboard.

Parameters

key String

The key for the custom tag. The value must be a nonempty string, with a maximum length of 255 characters, and can't consist only of whitespace.

value String

The value for the custom tag. The value must be a nonempty string, with a maximum length of 255 characters, and can't consist only of whitespace.

Returns

Bool

true if the custom tag was set successfully; otherwise false.

Remarks

• To ensure that the custom tag is associated with the correct session, it's recommended to call this function within the callbacks of setOnSessionStartedCallback or startNewSession.
• This function should only be called on the main thread.

sendCustomEvent()

static func sendCustomEvent(value: String) -> Bool

Sends a custom event to the current Clarity session. These custom events can be used to track specific user interactions or actions that Clarity's built-in event tracking doesn't capture.

Parameters

value String

The name of the custom event. The value must be a nonempty string, with a maximum length of 254 characters, and can't consist only of whitespace.

Returns

Bool

true if the custom event was sent successfully; otherwise false.

Remarks

• This API can be called multiple times per page to track various user actions.
• Each custom event is logged individually and can be filtered, viewed, and analyzed on the Clarity dashboard.

setCurrentScreenName()

static func setCurrentScreenName(name: String?) -> Bool

This function allows you to provide a custom screen name that replaces the default screen name. The default name is automatically generated based on the currently presented view controller's title or type.

Parameters

name String?

The desired screen name. The value must be a nonempty string with a maximum length of 255 characters and can't consists of only whitespace. Set to nil to reset.

Returns

Bool

true if the specified screen name was set successfully; otherwise false.

Examples

• If the presented view controller is a TabBarController with the title property set to "Main Tab Bar" and setCurrentScreenName("Settings") is called, the screen name is tracked as "Settings".
• If setCurrentScreenName(nil) is called on the same view controller, the screen name is tracked as "Main Tab Bar" (or "TabBarController" in the next major release).

Remarks

• Clarity starts a new page whenever the screen name changes.
• To mask or disallow a screen, specify the view controller type shown as "ViewController" custom tag of the page visit on the Clarity dashboard's recordings. For example, to mask the view controller in the earlier example, mask the &TabBarController screen instead of &Settings.
• The custom screen name is set globally and persists across all subsequent view controllers until explicitly reset.
• For accurate tracking, call this function immediately after adding the relevant views to the view controller's view hierarchy and within the same CATransaction (for example, inside viewIsAppearing).
• The view controller's title is no longer used to generate the default screen name in the next major release.
• This function should only be called on the main thread.

setOnSessionStartedCallback()

func setOnSessionStartedCallback(_ callback: @escaping (String) -> Void) -> Bool

Sets a callback function that's invoked whenever a new Clarity session starts or an existing session is resumed at app startup.

Parameters

callback (String) -> Void

The callback to be invoked whenever a Clarity session starts. The callback receives the new or resumed session ID as a string parameter.

Returns

Bool

true if the callback was set successfully; otherwise false.

Remarks

• If the callback is set after a session has already started, the callback is invoked right away with the current session ID.
• The specified callback is guaranteed to run on the main thread.

SwiftUI modifiers

Important

• Force masking of input fields is not currently supported. Apply the clarityMask modifier to each input field individually.
• Clarity might not capture text content when using custom fonts. In such case, use the clarityFontNameHint modifier.

clarityMask()

func clarityMask()

Marks a view's content to be masked by Clarity. Masked content is replaced with placeholders.

clarityUnmask()

func clarityUnmask()

Marks a view's content to be unmasked by Clarity. This is useful for capturing specific parts of a masked view.

clarityFontNameHint()

func clarityFontNameHint(name: String)

Provides a hint to Clarity about the font name used in a view. This is helpful for capturing text content when custom fonts are used.

Parameters

name String

The face name of the view's custom font (for example, "HelveticaBold" or customUIFont.fontName).

Implementation notes

• The invocation of View masking APIs should occur in the viewDidLoad() of the view controller that hosts the targeted view.

Important

Remember to update your terms & conditions (if any) for your app users after integrating Clarity with your mobile app.

Additionally, since force masking of input fields isn't supported yet, apply masking to each input field instance individually.

FAQ

For more answers, refer to FAQ.

Next steps

IP blocking

Masking

Data capture rules

Explore more

Heatmaps overview

Recordings overview

Insights overview

Visit Clarity

Demo

Sign in

Blog