Getting Started

Welcome to the SDK implementation guide!

This guide is designed to help you quickly and seamlessly integrate our SDK into your application. By following the steps outlined here, you’ll be able to start collecting and analyzing data from your app, within a few minutes.

Before implementing the SDK, make sure your app is technically compatible. This helps prevent potential issues with integration and ensures optimal performance.

Provide the value of the Bundle identifier property to Contentsquare.
The bundle ID is required to generate your project configuration.

<key>CFBundleIdentifier</key>
<string>com.example.testapp</string>

Once Contentsquare has created your project, make sure you have been provided with access to a Contentsquare account and a valid project ID. Each project ID corresponds to a specific data collection setup. Without a project ID, you won’t be able to send data to your project.

If you don’t have access to a dedicated project, reach our to your Implementation Manager.

Our iOS SDK is shipped as a .xcframework which you need to add as a dependency of your project.

The SDK requires Xcode 15 or later, if you are using older versions of Xcode reach out to your Contentsquare contact for more information.

You do not need to do anything to start the SDK. Now that the SDK is a dependency of your app, it will autostart itself when your application starts.

Start your application, you should see the SDK print a log like this one:

CSLIB ℹ️ Info: Contentsquare SDK v4.39.0 starting in app: com.example.testapp

If the SDK does not seem to work, it might mean that your app’s bundle identifier is not tied to any Contentsquare project. In that case, you will have to communicate all variants of your app’s bundle identifier to your Contentsquare contact to be added as a project.

Now that the SDK runs in your app, you will want to implement calls to our SDK to track screenviews, transactions, and more. Keep following along this guide to know how.

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: logging is linked to in-app features being enabled or disabled.

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 ↗.

3. Filter logs by CSLIB

In order to allow Contentsquare users to enable in-app features, you must perform 2 implementation tasks:

1. Add the custom URL scheme in your app Info
2. Call the SDK when the app is launched via a deeplink

You have to allow your app to be opened via a custom URL scheme which can be done using one of the following methods:

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)

1. Open the Info.plist of your project

2. Add the following snippet:

   <key>CFBundleURLTypes</key>
   <array>
       <dict>
           <key>CFBundleURLSchemes</key>
           <array>
               <string>cs-$(PRODUCT_BUNDLE_IDENTIFIER)</string>
           </array>
       </dict>
   </array>

Depending of the project, there are multiple ways to handle the deeplink opening. Choose the method matching your project structure:

@main
struct MyApp: App {
  var body: some Scene {
    WindowGroup {
      MyView()
        .onOpenURL { url in
          Contentsquare.handle(url: url)
        }
    }
  }
}

In-app features are essential for your implementation, as it includes key functionalities like snapshot creation and replay configuration.

If you have access to the Contentsquare platform, you can open the in-app features modal from the menu and scan the QR code with your phone.

If you are using an simulator, you can use the custom link to enable in-app features.

If you have access to the Contentsquare platform, you can open the in-app features modal from the menu and select “Copy this link”. Paste it in Safari on your simulator to trigger the in-app features.

In a Terminal console, open a URL in your current simulator with the following command (replacing CUSTOM_LINK with yours):

xcrun simctl openurl booted "CUSTOM_LINK"

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 ↗.

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.

Contentsquare collects usage data from your app users. To start tracking, you need your users’ consent for being tracked.

The SDK will consider every new user to be opted-out by default. To start tracking, the SDK Opt-in API must be called.

Forward user consent with optIn(). Calling this method generates a user ID and initiates tracking.

Contentsquare.optIn()

[Contentsquare optIn];

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, conversion funnel…

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.

import ContentsquareModule

Contentsquare.send(screenViewWithName: String, cvars: [CustomVar] = [])

@import ContentsquareModule;

[Contentsquare sendWithScreenViewWithName:(NSString * _Nonnull)];
// or
[Contentsquare sendWithScreenViewWithName:(NSString * _Nonnull) cvars:(NSArray<CustomVar *> * _Nonnull)]; // To add custom variables to screen tracking

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)

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 for implementation examples.

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.

Testing your SDK implementation is essential to make sure data is being accurately captured and reported.

To test your setup, you should 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, the macOS Console app or Log Visualizer to monitor data transmission and ensure everything is running smoothly.

As described previously, you can use 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.

Open Journey Analysis ↗ 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 ↗.

Open Session Replay ↗ in Contentsquare and replay the full user session across your app.

See how to use Session Replay on the Help Center ↗

To explore some of these features in context, check our iOS sample app.

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.