The LogRocket SDK for iOS allows you to capture session replays, network requests and logs from iOS applications.

Quick Start

Register with LogRocket

Go to https://logrocket.com/signup to create a free trial account. If you already have a LogRocket account, you can use your existing account. All LogRocket accounts include 1,000 free mobile sessions.

Swift Package Manager

The LogRocket iOS SDK is available as a Swift Package. To install the SDK as a Swift Package go to File -> Add Packages... in XCode and enter https://github.com/LogRocket/logrocket-ios-swift-package into the "Search or Enter Package URL" field.

Once the package has been added continue on to Initializing the SDK.

CocoaPods

The LogRocket iOS SDK can be installed with CocoaPods. If you already use CocoaPods in your app, skip to the next step.

1. Follow the instructions to install CocoaPods and use pod init in your app's Xcode project directory to create a Podfile
2. Update your Podfile to use the correct iOS version, e.g., platform :ios, '12.0' or greater.

From now on, make sure you use the CocoaPods generated XCode workspace (if you didn't already have a workspace) so that any installed pods are available to your application.

Adding the SDK with CocoaPods

Add the LogRocket pod in the app target of your Podfile and then run pod install to add our framework to your application. New releases of the LogRocket Native SDKs are catalogued on our Mobile SDK Changelog (the current release is 1.6.1).

platform :ios, '12.0'

target 'app' do
  pod 'LogRocket', '1.6.1'
end

Initializing the SDK

The LogRocket iOS SDK must be initialized from your app delegate's application handler.

Replace <APP_SLUG> with your LogRocket application slug, located in our dashboard's quick start guides.

import LogRocket

class AppDelegate: UIResponder, UIApplicationDelegate {
  func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    // Configuration options listed below can be provided to the Configuration constructor.
    SDK.initialize(configuration: Configuration(appID: "<APP_SLUG>"))
    return true
  }
}

#import <LogRocket/LogRocket-Swift.h>
  
@implementation AppDelegate

- (BOOL) application:(UIApplication*)application didFinishLaunchingWithOptions:(NSDictionary*)launchOptions
{
    LROConfiguration *configuration = [[LROConfiguration alloc] initWithAppID:@"<APP_SLUG>"];
    // Configuration options listed below can be assigned to the configuration object.
    [LROSDK initializeWithConfiguration:configuration];

    return YES;
}

@end

Supported iOS Versions

The LogRocket iOS SDK supports iOS 12.0 and up.

Identifying Users

Associate a user identifier with the active user. You can use any string that uniquely identifies the user of your application such as a database ID, an email, or a username.

SDK.identify(userID: "28dvm2jfa")

[LROSDK identifyWithUserID:@"28dvm2jfa" userInfo:@{}]

User traits can be added with a map as the second argument to SDK.identify.

SDK.identify(userID: "28dvm2jfa", [
  "name": "Jane Smith",
  "email": "[email protected]",
  "subscriptionPlan": "premium",
])

[LROSDK identifyWithUserID:@"28dvm2jfa", userInfo:@{
  "name": "Jane Smith",
  "email": "[email protected]",
  "subscriptionPlan": "premium",
}]

Visual Capture & Replay

The LogRocket iOS SDK captures what your Application is displaying to the user for our Session Replay system.

Performance

Limiting potential user experience impact when using the LogRocket iOS SDK is a high priority for us at LogRocket. The system that captures the Application's current screen must run in the UI Thread and could potentially block the UI from updating. This process is highly optimized to limit the work our SDK does in the UI Thread and our average time spent in this thread is well under 16ms, the target "frame time" to keep a User Interface updating at 60FPS. This process runs, on average, once every second to provide a reasonably paced video without "stealing" more than one frame per second from the UI.

Privacy

Redacting a view prevents that portion of the application screen from being recorded.

To redact a view, assign that view an accessibility identifier, either through the storyboard or manually by setting View.accessibilityIdentifier. Next, add that accessibility identifier to the redactionTags SDK configuration option. The view will be hidden during the capture process so that it does not show up in the final recording.

Selectors

Mobile sessions can be filtered on touch events through the Clicked filter. Currently only the "on selector" form of this filter is supported. Selectors are generated from hierarchical view details and support a subset of the CSS specification syntax.

Components of a View Selector

For example, a text field with an accessibility ID of "user_email" and tag of 1 the following Selector would be generated:

UITextField.1#user_email

Querying Selectors

For each touch event, a hierarchy of views is computed from the touched view to the top view of the Activity. The following forms of querying are supported:

• Single element: Button -- will match any Button element.
• Specific ID: #signin -- will match the view with this accessibility ID
• Specific Tag: .tag -- will match any view with that tag number
• Combined selectors: an element may be followed by either or both of a Specific ID and Specific Tag.
• Nesting: multiple selectors may be separated by a space, and will enforce a matching hierarchy.
• Child Of: a selector in the form of a > b matches any view b that is a direct child of the view a.

Accessing the Session URL

Integration with third party services can be accomplished by retrieving the Session URL and adding it as context to the third party library. In the iOS SDK, the session URL can be accessed with the SDK.getSessionURL method. Session URLs are only made available when our backend has accepted the session, which can take 1-5 seconds from when the SDK is initialized.

SDK.getSessionURL { sessionURL in
  // Use the accepted Session URL
}

void (^completion)(NSString*) = ^(NSString* sessionURL) {
  // Use the accepted Session URL
}

[LROSDK getSessionURL:completion]

Network Requests

Network requests in iOS are automatically captured by default.

Disable Network Capture

To disable the automatic network capture initialize the SDK with the networkCaptureEnabled set to false.

let configuration = Configuration(appID: "<APP_SLUG>", networkCaptureEnabled: false)
SDK.initialize(configuration: configuration)

Manual Network Capture

If you have disabled automatic network capture and would like to only capture specific requests, you can use our RequestBuilder object.

let requestBuilder = SDK.newRequestBuilder()
requestBuilder.headers = ["Header": "Value"]
requestBuilder.method = "GET"
requestBuilder.url = "https://www.example.com"
let responseBuilder = requestBuilder.capture()
responseBuilder.status = 200
responseBuilder.capture()

For the request builder, the headers, method and URL are required fields. For the response builder, only the headers are required.

Redacting Sensitive Information

The SDK accepts a requestSanitizer and responseSanitizer at initialization. The values provided must conform to the RequestSanitizer protocol (LRORequestSanitizer in Objective-C) and the ResponseSanitizer protocol (LROResponseSanitizer in Objective-C) respectively.

import Foundation
import LogRocket

class ExampleSanitizer: RequestSanitizer, ResponseSanitizer {
  public func sanitize(request: Request) -> Request? {
    if let url = request.url, url.contains("privateInformation") {
      // This will redact the entirety of the request
      // The matching response will be ignored as well
      return nil
    }
    
    // This will remove only privateHeader, but leave the rest of the headers in the recording
    request.headers?.removeValue(forKey: "privateHeader")

    return request
  }

  public func sanitize(response: Response) -> Response? {
    if response.status == 404 {
      // This will redact only the response body for responses with a 404 status code
      response.body = nil
    }

    return response
  }
}

// Add to configuration
let sanitizer = ExampleSanitizer()
let configuration = Configuration(appID: "<APP_SLUG>", requestSanitizer: sanitizer, responseSanitizer: sanitizer)
SDK.initialize(configuration: configuration)

Application Logs

Application logs on iOS are automatically captured.

Disable Log Capture

To disable the automatic network capture initialize the SDK with the logCaptureEnabled set to false.

let configuration = Configuration(appID: "<APP_SLUG>", logCaptureEnabled: false)
SDK.initialize(configuration: configuration)

Manual Log Capture

Our iOS SDK includes a Logger interface for capturing logs manually:

import LogRocket

Logger.debug("Debug level message")
Logger.info("Info level message")
Logger.warning("Warning level message")
Logger.error("Error level message")

Custom Events

If you use an analytics tool, you likely track custom events to measure your users' in-app behavior. Use the Custom Events API to make these events accessible in LogRocket.

SDK.track(CustomEventBuilder("Registered"));

LROCustomEventBuilder *builder = [[LROCustomEventBuilder alloc] init:@"Registered"];
[LROSDK track:builder];

You can then search for sessions containing these events using a Custom Event filter in the LogRocket Dashboard:

You can optionally provide additional properties that will be associated with the event:

let builder = CustomEventBuilder("PurchaseComplete")
builder.put("revenue", 24.99)
builder.put("productCategory", "Clothing")
builder.put("productSku", 488736929)
builder.put("couponApplied", true)
builder.put("customerSegments", ["aef34b", "97cb20"]) // Register multiple values with one call

SDK.track(builder) // Capture the event

LROCustomEventBuilder *builder = [[LROCustomEventBuilder alloc] init:@"PurchaseComplete"];

[builder putDouble:@"revenue" value:24.99];
[builder putString:@"productCategory" value:@"Clothing"];
[builder putDouble:@"productSku" value:488736929];
[builder putBool:@"couponApplied" value:true];
[builder putStringArray:@"customerSegments" value:[NSArray arrayWithObjects:@"aef34b", @"97cb20",nil]];

[LROSDK track:builder];

Properties may be of type boolean, double, or string. Arrays of primitives (boolean, double, or string) are also supported.

There are a few limits to keep in mind when providing properties to Custom Events:

• Property names must be under 100 characters.
• A maximum of 500 properties may be uploaded per session. Properties over this limit will not be recorded.

📘

'Revenue' property

The 'revenue' property is a special property that you can use to pass data into our funnels. For more information, see here.

Configuring a Network Proxy

If a network proxy is required a configuration builder can be provided when initializing the SDK.

let proxyConfig = ProxyConfigurationBuilder()
proxyConfig.httpEnable(true);
proxyConfig.httpProxy("127.0.0.1");
proxyConfig.httpPort(8888);
proxyConfig.proxyUsername("username");
proxyConfig.proxyPassword("password");

SDK.initialize(configuration: Configuration(
  appID: "<APP_SLUG>",
  proxyConfiguration: proxyConfig,
))

LROProxyConfigurationBuilder *proxyConfig = [[LROProxyConfigurationBuilder alloc] init];

[proxyConfig httpEnable:true]
[proxyConfig httpProxy:@"127.0.0.1"]
[proxyConfig httpPort:8888]
[proxyConfig proxyUsername:@"username"]
[proxyConfig proxyPassword:@"password"]

LROConfiguration *configuration = [[LROConfiguration alloc] initWithAppID:@"<APP_ID>"];
configuration.proxyConfiguration = proxyConfig;
[LROSDK initializeWithConfiguration:configuration];

Configuration Options

The following options are available.

// Required. Set your LogRocket appID. e.g. "organization/application"
appID: String

// Optional. Redacts views with accessibility identifiers that match these tags
redactionTags: Set<String> = []

// Optional. Enable (default) or disable automatic view capture
viewScanningEnabled: Bool = true

// Optional. Enable (default) or disable automatic network capture
networkCaptureEnabled: Bool = true

// Optional. The request/response sanitizers are explained in the network capture section
requestSanitizer: RequestSanitizer? = nil
responseSanitizer: ResponseSanitizer? = nil

// Optional. See documentation above about configuring the network proxy.
proxyConfigurationBuilder: ProxyConfigurationBuilder? = nil