---
title: From Contentsquare SDK to CSQ SDK - iOS
description: Migrate to the CSQ SDK
lastUpdated: 13 November 2025
source_url:
  html: https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/upgrade-from-cs-sdk/
  md: https://docs.contentsquare.com/en/csq-sdk-ios/experience-analytics/upgrade-from-cs-sdk/index.md
---

This guide provides a step-by-step upgrade process from your current installation of Contentsquare Mobile SDK to the latest version of the CSQ SDK.

![Contentsquare SDK](https://docs.contentsquare.com/cs-logo.png)

**Contentsquare SDK**

→

![CSQ SDK](https://docs.contentsquare.com/csq-logo.png)

**CSQ SDK**

The latest version of our SDK provides a unified set of APIs for Product Analytics, Experience Analytics, and Experience Monitoring, eliminating redundant APIs that perform the same actions.

Upgrading to the latest version ensures you benefit from all our newest features and product enhancements.

## Dependency upgrades

Replace the Contentsquare SDK by the CSQ SDK.

* Swift Package Manager

  1. In your XCode project > `Package Dependencies`, update the repository location:

     ```diff
     https://github.com/ContentSquare/CS_iOS_SDK.git
     https://github.com/ContentSquare/apple-sdk.git
     ```

  2. Set the Dependency Rule to `Exact Version` `1.6.1`.

  3. To ensure the library can start properly, add `-ObjC` as a linker flag under `Build Settings` > `Linking - General` > `Other Linker Flags`.

* Cocoapods

  1. Update your pods:

     ```diff
     pod 'ContentsquareModule', '4.35.1'
     pod 'ContentsquareSDK', '1.6.1'
     ```

  2. Run `pod install` within your project directory.

  3. Build your app target.

## Library imports

Replace the Contentsquare SDK import with a unified CSQ SDK import.

* Swift

  ```diff
  import ContentsquareModule
  import ContentsquareSDK
  ```

* Objective-C

  ```diff
  @import ContentsquareModule;
  @import ContentsquareSDK;
  ```

## SDK start

1. Start the CSQ SDK manually using `CSQ.start()`. Unlike earlier versions, it no longer starts automatically.

   * UIKit

     ```swift
      @UIApplicationMain
      class AppDelegate: UIResponder, UIApplicationDelegate {
        var window: UIWindow?


        func application(
          _ application: UIApplication,
          didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
        ) -> Bool {
          CSQ.start()
          return true
        }
      }
     ```

   * SceneDelegate

     ```swift
      class SceneDelegate: UIResponder, UIWindowSceneDelegate {
          var window: UIWindow?
          func scene(
              _ scene: UIScene, willConnectTo session: UISceneSession,
              options connectionOptions: UIScene.ConnectionOptions
          ) {
              CSQ.start()
          }
      }
     ```

   * SwiftUI

     ```swift
      @main
      struct MyApp: App {
          init() {
              CSQ.start()
          }
          var body: some Scene {
              WindowGroup {
                  ContentView()
              }
          }
      }
     ```

   * SwiftUI (AppDelegate)

     ```swift
      class AppDelegate: NSObject, UIApplicationDelegate {
        func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
            CSQ.start()
            return true
        }
      }


      @main
      struct MyApp: App {
          @UIApplicationDelegateAdaptor(AppDelegate.self) var appDelegate
          var body: some Scene {
          WindowGroup {
              ContentView()
          }
        }
      }
     ```

2. (Optional) If you were relying on the Contentsquare SDK autostart, remove the `CSDisableAutostart` property and calls to `Contentsquare.start()`.

   * Swift

     ```xml
     <key>CSDisableAutostart</key>
     <true/>
     ```

     ```swift
     Contentsquare.start()
     ```

   * Objective-C

     ```xml
     <key>CSDisableAutostart</key>
     <true/>
     ```

     ```objc
     [Contentsquare start];
     ```

## Get user consent

The CSQ SDK treats users as opted-out by default.

Implement the [`optIn()`](../command-reference/#csqoptin) API to forward user consent to the SDK and generate a user ID.

* Swift

  ```swift
  import UIKit
  import ContentsquareSDK


  optinButton.addTarget(self, action: #selector(optInButtonTapped), for: .touchUpInside)


  @objc func optInButtonTapped(_ sender: UIButton) {
      CSQ.start()
      CSQ.optIn()
      ...
  }
  ```

* Objective-C

  ```objective-c
  #import <UIKit/UIKit.h>
  #import <ContentsquareSDK/ContentsquareSDK.h>
  [optinButton addTarget:self action:@selector(optInButtonTapped:) forControlEvents:UIControlEventTouchUpInside];


  - (void)optInButtonTapped:(UIButton *)sender {
      [CSQ start];
      [CSQ optIn];
      // Additional initialization or navigation code...
  }
  ```

## Update APIs

Search and replace all legacy SDK API calls in your app to the latest CSQ APIs using the following mappings. Updating your API calls ensures continued functionality without disruption.

In most cases, this process consists in updating the namespace and method names, with no changes to parameters.

```diff
Contentsquare.start()
CSQ.start()
```

For more information on SDK methods, see the [SDK API reference](../command-reference/).

### GDPR / Identification

| Contentsquare SDK | CSQ SDK |
| - | - |
| `Contentsquare.optIn()` | `CSQ.optIn()` |
| `Contentsquare.optOut()` | `CSQ.optOut()` |
| `Contentsquare.sendUserIdentifier()` | `CSQ.sendUserIdentifier()` |
| `Contentsquare.userID` | `CSQ.metadata.userID` |
| `Contentsquare.projectID` | `CSQ.metadata.projectID` |
| `Contentsquare.sessionNumber` | `CSQ.metadata.sessionID` |

Deprecated

**Contentsquare.forgetMe()**

You can use `CSQ.optOut()` instead to forget user id and stop tracking. If needed call `CSQ.optIn()` when you want to resume tracking.

### Logging

| Contentsquare SDK | CSQ SDK |
| - | - |
| `Contentsquare.logLevel { get set }` | `CSQ.debug.logLevel { get set }` |

### Property tracking

| Contentsquare SDK | CSQ SDK |
| - | - |
| `Contentsquare.send(dynamicVar: DynamicVar(key: String, value: UInt32))` `Contentsquare.send(dynamicVar: DynamicVar(key: String, value: String))` | `CSQ.addDynamicVar(DynamicVar)` |

### View tracking

| Contentsquare SDK | CSQ SDK |
| - | - |
| `UIScrollView.excludeFromExposureMetric()` | `UIScrollView.excludeFromExposureMetrics()` |

### CSInApp

| Contentsquare SDK | CSQ SDK |
| - | - |
| `Contentsquare.handle(url: URL)` | `CSQ.handle(url: URL)` |
| `Contentsquare.csInApp` | `CSQ.csInApp` |

### Interoperability

| Contentsquare SDK | CSQ SDK |
| - | - |
| `Contentsquare.onSessionReplayLinkChange(callback)` | `CSQ.metadata.onChange { metadata in }` |
| `Contentsquare.register(webView: WKWebView)` | `CSQ.registerWebView(WKWebView)` |
| `Contentsquare.unregister(webView: WKWebView)` | `CSQ.unregisterWebView(WKWebView)` |

### Event tracking

| Contentsquare SDK | CSQ SDK |
| - | - |
| `Contentsquare.send(transaction: CustomerTransaction)` | `CSQ.trackTransaction(Transaction)` |
| `Contentsquare.send(screenViewWithName name: String)` / `Contentsquare.send(screenViewWithName name: String, cvars: [CustomVar] = [])` | `CSQ.trackScreenview(String)/CSQ.trackScreenview(String, cvars: [CustomVar])` |

### Error tracking

| Contentsquare SDK | CSQ SDK |
| - | - |
| `ErrorAnalysis.setUrlMaskingPatterns([String])` | `CSQ.setURLMaskingPatterns([String])` |
| `ErrorAnalysis.onCrashReporterStart()` | `CSQ.onCrashReporterStart()` |
| `HTTPMetric` | `NetworkMetric` |
| `HTTPMetric.stop()` | `CSQ.trackNetworkMetric(NetworkMetric)` |
| `ErrorAnalysis.getInstance().newNetworkMetric(url, ErrorAnalysis.HttpMethod.GET)` | `CSQ.trackNetworkMetric(NetworkMetric(id, httpMethod, optionalId))` |

### Personal Data Handling and Masking

| Contentsquare SDK | CSQ SDK |
| - | - |
| `Contentsquare.setDefaultMasking(boolean masked)` | `CSQ.setDefaultMasking(boolean masked)` |
| `Contentsquare.mask(viewsOfType: UIView.Type)` | `CSQ.mask(viewsOfType: UIView.Type)` |
| `Contentsquare.mask(view: UIView)` | `CSQ.mask(UIView)`/ `UIView.csqMaskContents (UIKit)` |
| `View.csMasking(Bool)` | `View.csqMaskContents(enable: Boolean) (SwiftUI)` |
| `Contentsquare.unmask(UIView)` | `CSQ.unmask(UIView)` |
| `Contentsquare.unmask(viewsOfType: UIView.Type)` | `CSQ.unmask(viewsOfType: UIView.Type)` |
| `Contentsquare.maskTexts(mask: Boolean)` | `CSQ.maskTexts(mask: Boolean)` |
| `Contentsquare.maskImages(mask: Boolean)` | `CSQ.maskImages(mask: Boolean)` |
| `Contentsquare.maskTextInputs(mask: Boolean)` | `CSQ.maskTextInputs(mask: Boolean)` |

### SDK initialization and manipulation

| Contentsquare SDK | CSQ SDK |
| - | - |
| `Contentsquare.start()` | `CSQ.start()` |
| `Contentsquare.stopTracking()` | `CSQ.pauseTracking()` |
| `Contentsquare.resumeTracking()` | `CSQ.resumeTracking()` |

## Checklist

Congratulations! You're all set. Use this checklist to ensure everything is correctly updated.

Ensure that your build files no longer reference `https://github.com/ContentSquare/CS_iOS_SDK.git`.

Your `import ContentsquareModule` declarations have been updated to `import ContentsquareSDK`.

You no longer have references to `Contentsquare.` methods in your codebase.

All calls to the CSQ SDK use the `CSQ.`namespace.