iOS
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.
CocoaPods
Integrating your app with the LogRocket SDK currently requires CocoaPods to handle dependencies and versioning. If you already use CocoaPods in your app, skip to the next step.
- Follow the instructions to install CocoaPods and use
pod init
in your app's Xcode project directory to create aPodfile
- 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
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.3.3).
platform :ios, '12.0'
target 'app' do
pod 'LogRocket', '1.3.3'
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
Component | Value | Note |
---|---|---|
|
| |
|
| |
|
| Only non-zero tags are captured |
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 anyButton
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 viewb
that is a direct child of the viewa
.
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.
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
Updated 2 days ago