---
title: Getting Started - iOS (classic)
description: Integrate the Contentsquare SDK into your iOS app in minutes (installation, user consent, screen tracking, and testing)
lastUpdated: 07 April 2026
source_url:
html: https://docs.contentsquare.com/en/ios/
md: https://docs.contentsquare.com/en/ios/index.md
---
> Documentation index: https://docs.contentsquare.com/llms.txt
> Use this file to discover all available pages before exploring further.
The latest CSQ SDK is here! Learn how to [upgrade your app](https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/upgrade-from-cs-sdk/).
Welcome to the SDK implementation guide!
This guide is designed to help you seamlessly integrate our SDK into your application. By following the outlined steps, you'll be able to collect and analyze data from your app, within just a few minutes.
## Install the SDK
Our iOS SDK is shipped as a `.xcframework` which you need to add as a dependency of your project.
See [Compatibility](compatibility/) for more information.
### Include the SDK
The SDK requires Xcode 15 or later, if you are using older versions of Xcode reach out to your Contentsquare contact for more information.
* Swift Package Manager
1. For iOS 13 and later, add the following link via `File > Add Packages…` in XCode:
```plaintext
https://github.com/ContentSquare/apple-sdk.git
```
iOS 12 support
If you are supporting iOS 12, install the SDK using the following package:
```plaintext
https://github.com/ContentSquare/CS_IOS_SDK.git
```
2. Remove `https://github.com/apple/swift-protobuf.git` if you have added it before version 4.35.1.
3. To ensure the library can start properly you will need to add `-ObjC` as a linker flag under `Build Settings` > `Linking` > `Other Linker Flags`.
* CocoaPods
Static linking is the default behavior with `use_frameworks!`.
1. Add the following line to your Podfile:
**Podfile**
```ruby
pod 'ContentsquareSDK'
```
2. Remove `pod 'SwiftProtobuf', '<= 1.26.0'` if you have added it before version 4.35.1.
3. iOS 12 support
If you are supporting iOS 12, install the SDK using the following package:
**Podfile**
```ruby
pod 'CS_iOS_SDK_STATIC'
```
Note
Since we are distributing an XCFramework archive you need to use **CocoaPods 1.14.3** and up (`pod --version`). If you have an older version of `CocoaPods`, do `[sudo] gem install cocoapods`.
### Known Issues
* Updating `IPHONEOS_DEPLOYMENT_TARGET` in your `post_install` may have the following error.
```plaintext
dyld[47592]: Symbol not found: __ZN5swift34swift50override_conformsToProtocolEPKNS_14TargetMetadataINS_9InProcessEEEPKNS_24TargetProtocolDescriptorIS1_EEPFPKNS_18TargetWitnessTableIS1_EES4_S8_E
Referenced from: Xxxx
```
**Workaround:** Skip updating IPHONEOS\_DEPLOYMENT\_TARGET for SwiftProtobuf by following these steps.
1. Update your `post_install` to:
**Podfile**
```ruby
post_install do |installer|
installer.pods_project.targets.each do |target|
# Skip updating IPHONEOS_DEPLOYMENT_TARGET for SwiftProtobuf
next if target.to_s == 'SwiftProtobuf'
target.build_configurations.each do |config|
config.build_settings['IPHONEOS_DEPLOYMENT_TARGET'] = 'XX.X'
end
end
end
```
2. Rerun `pod install`.
3. Clean Builder Folder.
4. Rebuild.
* Manual
Not yet supported.
Note
Before version 4.34.0 we supported including the SDK through Carthage but this is no longer the case. To continue receiving SDK updates you need to switch to one of the other methods listed previously.
The SDK autostarts when your application launches, requiring no manual initialization.
### Validate SDK integration
Start your application, and check logs for this output:
```text
CSLIB ℹ️ Info: Contentsquare SDK v4.46.3 starting in app: com.example.testapp
```
## Check the logs
Contentsquare provides logging capabilities that allow you to inspect the raw event data logged by your app in Xcode, the macOS Console app, or on the Contentsquare platform.
To view all logs, you must [enable in-app features](#enable-in-app-features): logging is linked to in-app features being enabled or disabled.
### Viewing logs in Xcode or the Console app
To view SDK logs:
1. If using an actual device, make sure it is plugged to your Mac or is on the same Wi-Fi network.
2. Start the macOS Console app or Xcode.
If using the Console app, make sure that info messages are included: [Choose Action > Include Info Messages ↗](https://support.apple.com/guide/console/customize-the-log-window-cnsl35710/mac).
3. Filter logs by `CSLIB`
### Implement in-app features
In-app features are essential for your implementation, as it includes key functionalities like screenshot creation and replay configuration.
To allow Contentsquare users to enable in-app features:
1. [Add the custom URL scheme in your app Info](#1-add-the-custom-url-scheme-in-your-app-info)
2. [Call the SDK when the app is launched via a deeplink](#2-call-the-sdk-when-the-app-is-launched-via-a-deeplink)
#### 1. Add the custom URL scheme in your app Info
You have to allow your app to be opened via a custom URL scheme which can be done using one of the following methods:
##### Xcode
1. Open your project settings
2. Select the app target
3. Select the `Info` settings
4. Scroll to `URL Types`
5. Set the URL scheme to `cs-$(PRODUCT_BUNDLE_IDENTIFIER)`
##### Text editor
1. Open the `Info.plist` of your project
2. Add the following snippet:
**Info.plist**
```xml
CFBundleURLTypes
CFBundleURLSchemes
cs-$(PRODUCT_BUNDLE_IDENTIFIER)
```
#### 2. Call the SDK when the app is launched via a deeplink
Depending on the project, there are multiple ways to handle the deeplink opening. Choose the method matching your project structure:
* AppDelegate
In your `AppDelegate` class, complete or implement the function `application(app, open url:, options:)` with: `Contentsquare.handle(url: url)`
* SceneDelegate
In your `WindowSceneDelegate` class, you need to:
1. Update `func scene(_ scene: UIScene, willConnectTo session: UISceneSession, options connectionOptions: UIScene.ConnectionOptions)` with:
```swift
if let url = connectionOptions.urlContexts.first?.url {
Contentsquare.handle(url: url)
}
```
2. Complete or implement `func scene(_ scene: UIScene, openURLContexts URLContexts: Set)` with:
```swift
if let url = URLContexts.first?.url {
Contentsquare.handle(url: url)
}
```
* SwiftUI
In the `body` of your main App struct, add the `onOpenURL` modifier and call the `Contentsquare` SDK to handle the URL:
```swift
@main
struct MyApp: App {
var body: some Scene {
WindowGroup {
MyView()
.onOpenURL { url in
Contentsquare.handle(url: url)
}
}
}
}
```
### Enable in-app features
#### On a device: scan the QR code
In Contentsquare, select the Mobile icon in the menu top bar and scan the QR code with your phone.
#### On a simulator: with the custom link
If you are using a simulator, use the custom link to enable in-app features.
In Contentsquare, select the Mobile icon in the menu top bar then select your Bundle ID, and select "Copy this link". Paste it in Safari on your simulator to trigger the in-app features.
#### On a simulator: with the Terminal
In a Terminal console, open a URL in your current simulator with the following command (replacing `CUSTOM_LINK` with yours):
```shell
xcrun simctl openurl booted "CUSTOM_LINK"
```
### Contentsquare Log Visualizer
Log Visualizer is a feature integrated into the Contentsquare SDK. As you navigate and interact with your app, it provides a live view of events detected by the SDK, visible directly on the [Contentsquare platform ↗](https://app.contentsquare.com/#/analyze/mobile-log).
Prerequisite
To use Log Visualizer, `Activate SDK logs stream` must be toggled on within in-app settings.
1. Start your app.
2. Select the Mobile icon in the menu top bar then select `Log Visualizer`.
3. Select the device to inspect.
At this stage, you should see an 'App start' or 'App show' event being logged.
## Get user consent
Contentsquare collects usage data from your app users. To start tracking, you need your users' consent for being tracked.
### User opt-in
The SDK treats users as **opted-out by default.**
To start tracking, forward user consent with `optIn()`. Calling this method generates a user ID and initiates tracking.
Handle user consent by implementing a UI for privacy preferences.
* Swift
```swift
Contentsquare.optIn()
```
* Objective-C
```objective-c
[Contentsquare optIn];
```
Going further
For advanced configuration regarding user consent or personal data handling, see [Privacy](https://docs.contentsquare.com/en/ios/privacy/).
## Track your first screens
Contentsquare aggregates the user behavior and engagement at the screen level. Start your SDK implementation by tracking key screens like the home screen, product list, product details, or conversion funnel.
### Sending screenview events
Screen tracking is achieved by sending a `screenview` event each time a new screen is displayed on the user's device.
As a general rule of thumb, you should send your screenviews in `viewWillAppear(_ animate: Bool)` when using UIKit, in `.onAppear()` when using SwiftUI.
* Swift
```swift
import ContentsquareModule
Contentsquare.send(screenViewWithName: String, cvars: [CustomVar] = [])
```
* Objective-C
```objective-c
@import ContentsquareModule;
[Contentsquare sendWithScreenViewWithName:(NSString * _Nonnull)];
// or
[Contentsquare sendWithScreenViewWithName:(NSString * _Nonnull) cvars:(NSArray * _Nonnull)]; // To add custom variables to screen tracking
```
### Implementation recommendations
From a functional perspective, a screenview should be triggered in the following cases:
* When the screen appears on the device
* When a modal or pop-up is displayed
* When a modal or pop-up is closed, returning the user to the screen
* When the app is brought back to the foreground (after being minimized)
Specific triggers
Depending on how your app is built (Popups, Webviews, Redirections, etc...), you might need specific implementation use cases for triggering screenview events.
See the [dedicated section in our Guide](https://docs.contentsquare.com/en/ios/track-screens/#implementation-recommendations).
#### Tracking app launch
Most events collected by the SDK require a screenview event to be sent first so they can be associated with that screen; otherwise, they will be discarded. If you need to collect events from the moment the app launches, you should trigger a screenview event immediately after the SDK has started.
Refer to [our guide](https://docs.contentsquare.com/en/ios/track-screens/#when-to-send-your-first-screenview) for implementation examples.
#### Screen name handling
It is necessary to provide a name for each screen when calling the screenview API.
As a general rule, keep distinct screen names under 100. As they are used to map your app in Contentsquare, you will want something comprehensive. The screen name length is not limited on the SDK side. However, the limit is 2083 characters on the server side.
More on [screen name handling](https://docs.contentsquare.com/en/ios/track-screens/#how-to-name-screens).
Tracking plan
To get the most out of your data, it's best to follow a tracking plan. This way, you'll capture every step of the user's journey without missing important interactions, giving you a complete picture of how your app is used.
## Test your setup
Testing your SDK implementation is essential to make sure data is being accurately captured and reported.
To test your setup, simulate user interactions in your app and check that the events are logged correctly in our analytics platform.
You can also use debugging tools such as Xcode, macOS Console App, or Log Visualizer to monitor data transmission and ensure everything is running smoothly.
### Visualize events in Contentsquare
Use [Log Visualizer](#contentsquare-log-visualizer) to view incoming events within the Contentsquare pipeline. This allows you to monitor the stream in real time.
By simulating user activity, you see incoming screenview and gesture events.
### Visualize data in Contentsquare
Data availability
Data must be sessionized (meaning all events for a single session are gathered together) before it can be visualized. This requires the session to have ended, which happens 30 minutes after the last event is received. Therefore, you can expect to see the first replays 30 minutes after the last interaction with the app.
#### In Journey Analysis
[Open Journey Analysis ↗](https://app.contentsquare.com/#/analyze/navigation-path) in Contentsquare and visualize the user journeys main steps across your app, screen by screen.
See how to use Journey Analysis on the [Help Center ↗](https://support.contentsquare.com/hc/en-us/articles/37271761254161).
#### In Session Replay
[Open Session Replay ↗](https://app.contentsquare.com/#/session-replay) in Contentsquare and replay the full user session across your app.
See how to use Session Replay on the [Help Center ↗](https://support.contentsquare.com/hc/en-us/articles/37271667148561)
## Sample app
To explore some of these features in context, check our iOS sample app.
### [iOS-sample-app](https://github.com/ContentSquare/iOS-sample-app)
[A sample app giving an example implementation of the Contentsquare SDK](https://github.com/ContentSquare/iOS-sample-app)
[Swift](https://github.com/ContentSquare/iOS-sample-app)
## Next Steps
While screen tracking gives an overview of user navigation, capturing session, screen, or user metadata provides a deeper understanding of the context behind user behavior.
Our SDK offers a wide range of features to enhance your implementation, including Session Replay, Error Monitoring, extended tracking capabilities, and personal data masking.
Proceed with these how-to's to refine your implementation.
[Custom Variables ](https://docs.contentsquare.com/en/ios/track-custom-variables/)Collect additional details about the screen or the user.
[Dynamic Variables ](https://docs.contentsquare.com/en/ios/track-dynamic-variables/)Collect additional information about the session.
[Transactions tracking ](https://docs.contentsquare.com/en/ios/track-transactions/)Associate user's session with their potential purchases and corresponding revenue.
[WebViews ](https://docs.contentsquare.com/en/ios/track-webviews/)For native apps which embark web applications or pages.
[Session Replay ](https://docs.contentsquare.com/en/ios/session-replay/)Collect data for Session Replay in compliance personal data masking.
[Error Analysis ](https://docs.contentsquare.com/en/ios/error-analysis/)Track API errors and application crashes with automated collection and privacy-safe debugging tools.