Error Analysis
Prerequisites
Section titled PrerequisitesScreen tracking implemented
Section titled Screen tracking implementedTracking will start at the 1st screenview event, it is required to have screen tracking implemented. Make sure to follow the iOS Track screens sections.
Reminder about User consent
Section titled Reminder about User consentIf you are in the process of implementing the SDK for the 1st time (or choose to take this update as an opportunity to review your Privacy related implementation), make sure to follow the iOS Privacy section and use the Opt-in API to get the user consent, otherwise no data will be collected.
API errors
Section titled API errorsAutomatic collection
Section titled Automatic collectionAPI errors automatically collects failed network requests that use URLSession
.
Disable automatic collection
Section titled Disable automatic collectionAutomatic collection can be disabled by setting CSDisableAPIErrorsAutoCollection
to YES
in the Info.plist.
Add custom monitoring for specific network requests
Section titled Add custom monitoring for specific network requestsThe API errors automatically collects most network requests for your app. However, some requests might not be collected or you might use a different library to make network requests. In these cases, you can use the following API HTTPMetric
to manually collect data.
Removing Personal Data in request URL path
Section titled Removing Personal Data in request URL pathBy default, the API Errors feature collects the URL path of the failed API requests. To prevent the collection of Personal Data in the URL path, you can rewrite the request URL path with the setURLMaskingPatterns
SDK API.
Replace a step of the path - meaning between two slashes (/) - containing Personal Data with a variable:
:user_id
becomes CS_ANONYMIZED_USER_ID:address
becomes CS_ANONYMIZED_ADDRESS
Example
Section titled ExampleURL before masking | URL after masking |
---|---|
https://www.contentsquare.com/users/123/address/castle+black | https://www.contentsquare.com/users/CS_ANONYMIZED_USER_ID/address/CS_ANONYMIZED_ADDRESS |
Validate API error integration
Section titled Validate API error integrationValidate API error collection is enabled
Section titled Validate API error collection is enabledIf in-app features are enabled, a log should appear indicating if API errors is enabled or disabled:
Validate API error collection
Section titled Validate API error collectionIf you have logging enabled, you will see API errors:
- Displayed in Contentsquare Log Visualizer.
- As an Info log:
How API errors works
Section titled How API errors worksInitialization
Section titled InitializationThe way our SDK works is by auto-starting with the application launch and automatically collects failed network requests that use URLSession
.
Configuration
Section titled ConfigurationOnce started, our SDK fetches its config from our servers. It will start collecting data from network events if the API errors setting is enabled in the config (this is handled by the Contentsquare team).
API errors collection
Section titled API errors collectionThe SDK monitors only the API errors with response code equal or above 400, and generates analytics data. These events are then locally stored, and eventually sent to our servers in batches.
Sending API errors data
Section titled Sending API errors dataFor each network error, a new event will be sent in analytics and Session Replay data. Check the following sections to learn more about how data is processed and sent:
API Troubleshooting Details
Section titled API Troubleshooting DetailsAPI errors troubleshooting details enables you to collect more information about API errors so you can troubleshoot errors faster.
With this feature you will be able to see three types of additional API error details in the Event Stream of Session Replay.
- The HTTP headers of the request and the response.
- The body (the data sent by the request or received in the response).
- The query parameters of the request endpoint (of the URL of the information you request for).
See API Troubleshooting Details ↗ for more details.
Collected data points
Section titled Collected data pointsOnly network calls with error (response code above 400) will be collected. Here is the list of data collected:
- URL (without query strings)
- HTTP method
- Response code
- Timestamp of the request
- Timestamp of the response
- HTTP headers of the request
- HTTP headers of the response
- HTTP body of the request
- HTTP body of the response
- Query parameters of the request endpoint
Known limitations and recommendations
Section titled Known limitations and recommendationsAutomatic collection limitations
Section titled Automatic collection limitationsThe auto collection doesn’t work for the following methods:
Workaround: For the async
methods, use the corresponding Contentsquare methods:
For other methods, use the custom monitoring APIs.
Conflict with Firebase Performance SDK on auto-collection
Section titled Conflict with Firebase Performance SDK on auto-collectionAPI errors is compatible with Firebase Performance auto-collection, but the HTTP body from the response won’t be collected by the Error Analysis SDK.
Workaround: Disable auto collection and use API HTTPMetric
to manually collect data.
It may also not be compatible with other network auto collection tools.
Crash Reporter
Section titled Crash ReporterSetup Firebase Crashlytics compatibility mode
Section titled Setup Firebase Crashlytics compatibility modeBased on our test, the Contentsquare Crash Reporter is compatible with Firebase Crashlytics as long as the Contentsquare Crash Reporter is initialized first, otherwise some crashes can be missing in Crashlytics.
You can use this API to launch Firebase Crashlytics after Contentsquare Crash Reporter
Upload dSYMs
Section titled Upload dSYMs“When Xcode compiles your source code into machine code, it generates a list of symbols in your app — class names, global variables, and method and function names. These symbols correspond to the file and line numbers where they’re defined; this association creates a debug symbol” See Apple’s documentation for more details ↗.
When an app crashes, the operating system collects diagnostic information about what the app was doing at the time of crash. Some of the most important parts of the crash report are presented as hexadecimal addresses. To translate those addresses into readable function names and line numbers from your source code, a process called symbolication is used. See Apple’s documentation for more details ↗.
In order to symbolicate the crashes reported by a specific version of your app and make them readable, you need to provide the symbol files (dSYMs) that were generated when your app was built.
Build your app with dSYMs
Section titled Build your app with dSYMsMake sure Xcode is generating dSYMs for your app:
- Open your project in Xcode.
- Select the project file in the Xcode Navigator.
- Select your main target.
- Select the
Build Settings
tab and clickAll
to show all the build settings. - Filter by
Debug Information Format
. - Set
Debug Information Format
toDWARF with dSYM File
for all the build types you want to generate dSYMs. - Rebuild your main target.
Locate dSYMs
Section titled Locate dSYMsDownload dSYMs from the App Store
Section titled Download dSYMs from the App StoreIf you build your main target using bitcode (Bitcode Enabled
turned on in build settings) and you uploaded your app’s symbols to the App Store, you need to download the dSYMs from the App Store:
- Log in to App Store Connect ↗, then select
My Apps
. - Select your app from the grid.
- Select the build you want to download a dSYM for.
- Click
Build Details
>Download dSYM
.
In case you use bitcode to build your main target but you didn’t upload your dSYMs to the App Store, you need to find your dSYMs on your local machine and restore hidden symbols using the BCSymbolMaps Xcode generates.
Find dSYMs on your local machine
Section titled Find dSYMs on your local machineYou can find the dSYMs in the .xcarchive
directory on disk:
- In Xcode, open the Organizer window (Window -> Organizer).
- Select your app from the list.
- Control-click an archive and select
Show in Finder
. - A Finder window should appear. Control-click the
xcarchive
package and selectShow Package Contents
. - There should be a dSYMs directory that contains the dSYMs generated in Xcode’s archiving process. If you use the
Download Debug Symbols
option from Xcode’s organizer, the recompiled bitcode dSYMs are also downloaded to this directory.
Restore hidden symbols using BCSymbolMaps
Section titled Restore hidden symbols using BCSymbolMapsRestoring hidden symbols using BCSymbolMaps is only required if you built your main target using bitcode (Bitcode Enabled
turned on in build settings). If you used bitcode but downloaded the dSYMs from the App Store, the dSYMs will be recompiled and you can skip this step.
To restore hidden symbols you can run the following command:
Get project ID
Section titled Get project ID- Login to the Contentsquare platform on https://app.contentsquare.com ↗
- Make sure to be on the right project
- The project ID can be found in the URL query parameter
project
:https://app.contentsquare.com/#/{MODULE_NAME}?project={PROJECT_ID}&hash={HASH}]
Get project credentials
Section titled Get project credentialsFollow the dedicated documentation from the Help Center to get the client ID and client Secret: How to create API credentials ↗.
Use script to upload dSYMs
Section titled Use script to upload dSYMsTo upload dSYMs to Error Analysis you need to use the provided upload-symbols
script. You need to provide the path where the dSYM files are located as a positional argument, and the Project ID, Client ID and Client Secret either as keyword arguments or set them as environment variables.
Additionally, you can use a proxy by specifying the proxy URL. Print more detailed logs by using the --verbose
flag.
Key | Environment Key |
---|---|
—project-id | ERROR_ANALYSIS_PROJECT_ID |
—client-id | ERROR_ANALYSIS_CLIENT_ID |
—client-secret | ERROR_ANALYSIS_CLIENT_SECRET |
—proxy | ERROR_ANALYSIS_PROXY_URL |
If both are provided, the keyword arguments will prevail over the environment variables.
Set up Xcode to automatically upload dSYM files
Section titled Set up Xcode to automatically upload dSYM filesThe following steps describe how to configure Xcode to automatically upload your dSYMs whenever you build your app.
- Open your project’s Xcode workspace, then select its project file in the left Project navigator.
- From the TARGETS list, select your main build target.
- Click the Build Phases tab, then complete the following steps so that Xcode can process your dSYMs and upload the files.
- Click + > New Run Script Phase. Make sure this new Run Script phase is your project’s last build phase; otherwise, dSYMs might not be ready.
- Expand the new Run Script section.
- In the script field (located under the Shell label), add the following run script.
If you are using SPM to integrate the Error Analysis SDK, the upload-symbols
script will be located in the SPM checkout path for the SDK.
Copy the following script.
If you are using CocoaPods or you are manually integrating the Error Analysis SDK, you will need to download the upload-symbols
script from the latest SDK release.
- Go to the CS_iOS_SDK releases page ↗.
- Click on
Show all assets
located at the bottom of the Assets list of the latest release. - Click on
upload-symbols-script.zip
. - Unzip the script.
- Move the script to your project root, same location as xxxx.xcodeproj.
Copy the following script.
In the Input Files section, make sure you have the paths for the locations of the following files:
Make sure User Script Sandboxing is set to NO in Xcode Build Settings. if you don’t want to disabled it, you need to add the paths of all your dSYMs files one by one in Input Files.
Use fastlane to upload dSYMs
Section titled Use fastlane to upload dSYMsThe instructions require fastlane 1.93.0
or later.
- Add fastlane plugin to your project:
- Run
fastlane add_plugin fastlane-plugin-contentsquare
. - Select
Git URL
and input https://github.com/ContentSquare/contentsquare-fastlane-plugin.git ↗. See fastlane Plugins ↗ for more information.
- Run
- Call fastlane plugin in your build process:
upload_symbols_to_error_analysis(project_id: your_project_id, client_id: "your_client_id", client_secret: "your_client_secret")
Validate crash reporter integration
Section titled Validate crash reporter integrationValidate crash collection is activated
Section titled Validate crash collection is activatedEnabling crash reporting will conflict with any attached debuggers, so make sure a debugger isn’t attached when you crash the app. In case a debugger is attached to the device, Crash Reporter won’t be initialized and a log will be printed in the console:
To test if Crash Reporter is working properly, you first need to disconnect your test device or simulator from Xcode debugger:
- Tap on the Edit scheme… option of your current scheme
- Disable the Debug executable option in your scheme configuration.
- Build and run your current scheme.
If Crash Reporter is successfully initialized when you launch your application, you should see a log printed in the console:
Alternatively, you can detach your application from Xcode debugger by stopping it after is launched. This way Crash Reporter will be initialized and will start reporting crashes, but you won’t be able to see the logs printed in the console:
- Build and run your current scheme.
- Wait until the app is up and running.
- Click on Stop running the scheme.
- Open the app directly from your test device or simulator.
Validate crash reporting
Section titled Validate crash reportingRun your application and force a crash (you can do it by adding a fatalError()
in your code). Launch the application again using Xcode and you should see a log printed in the console that indicates that a crash has been detected and sent:
How Crash Reporter works
Section titled How Crash Reporter worksInitialization
Section titled InitializationCrash Reporter is started automatically and begins to report crashes when your application is launched.
Configuration
Section titled ConfigurationOnce started, our SDK fetches its configuration from our servers. It will start reporting crashes if the Crash Reporter setting is enabled (this is handled by the Contentsquare team).
Reporting
Section titled ReportingWhen a crash occurs, a report is created and stored locally in the device. Once the app is launched again, the report is sent to our servers and then removed from the local storage.
Sending crash data
Section titled Sending crash dataFor each crash, a new event will be sent to analytics and Session Replay data when the app is launched again after the crash occurred and the network conditions allow for the server to be reached.
Our requests use lowPriority
↗.
Collected data points
Section titled Collected data pointsCrash Reporter handles multiple types of crashes, including:
- Mach kernel exceptions
- Fatal signals
- C++ exceptions
- Objective-C exceptions
For each crash we collect information of the application, system, process, threads, stack traces and some other events metadata you can find in collected data points.
Known limitations and recommendations
Section titled Known limitations and recommendationsCompatibility with other crash reporters
Section titled Compatibility with other crash reportersBeyond Firebase Crashlytics (see Setup Firebase Crashlytics compatibility mode), the Contentsquare Crash Reporter is not compatible with other crash reporters. For more details, reach out to your Contentsquare contact.
WebView errors
Section titled WebView errorsErrors occurring in web pages loaded in WebViews can be collected if Webview tracking is setup in your app.
See 📚 Webview Tracking implementation.
Once WebView tracking is implemented, errors collection can be set up.
See 📚 Errors (in WebView)
Impact on Performance
Section titled Impact on PerformanceWe always strive to be non-intrusive, and transparent to the developers of the client app. We apply this rule on the performance as well. These are the technical specifics we can share on performance, if you have any questions feel free to reach out to us.
The following performance results were obtained under the following conditions:
Condition | Value |
---|---|
Device model | iPhone 11 Pro 64GB |
iOS version | 16.5 |
Test App built using Xcode version | 15.3 |
Test App built with Swift version | 5.8 |
Property | Value |
---|---|
Max RAM usage | <2MB |
Max SDK CPU peak on event | <2% |
Migrating from <= 4.28.0
Section titled Migrating from <= 4.28.0Until version 4.28.0 of the Contentsquare SDK, the Error Analysis add-on was provided as a distinct artifact. To integrate it into your application, a dedicated XCFramework dependency was required and could be installed through SPM/Cocoapods/Carthage or manually. Starting from version 4.29.0, this is no longer the case as Error Analysis is included in main package.
If you had previously integrated the Error Analysis module into your application, you will need to remove it from your dependencies. Depending on how you integrated Error Analysis you can follow the instructions below:
In the app’s targets General settings tab, in the Frameworks, Libraries, and Embedded Content
section remove ContentsquareErrorAnalysisModule
.
run command pod update
Update the reference in your Cartfile:
- Remove
ContentsquareErrorAnalysisModule.xcframework
stored in the project folder - Select the target of your project in Xcode and go to tab
General
->Frameworks, Libraries and Embedded Content
and removeContentsquareErrorAnalysisModule.xcframework
by selecting it and clicking on-
- Select the target of your project in Xcode and go to tab
General
->Frameworks, Libraries and Embedded Content
and addCSCrashReporter.xcframework
by clicking on+
thenAdd Other...
->Add Files...
- Clean build folder (in Xcode
Product
>Clean Build Folder...
) and build/run your app
Once done you can remove all the import ContentsquareErrorAnalysisModule
in the source code of your app.