Getting Started

Add Contentsquare to your app

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

How to include it

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

In Xcode, add the following links via File > Add Packages…:
```
https://github.com/ContentSquare/CS_iOS_SDK.git
https://github.com/apple/swift-protobuf.git
```
Specify Dependency Rule to “Range of Versions” with “1.20.0 < 1.27.0” for swift-protobuf.
To ensure the library can start properly you will need to add -ObjC as a linker flag under Build Settings > Linking > Other Linker Flags.

Add the following line to your Cartfile:

binary "https://raw.githubusercontent.com/ContentSquare/CS_iOS_SDK/master/carthage/ContentsquareModule.json"
github "apple/swift-protobuf" ~> 1.0
github "ContentSquare/CS_iOS_CrashReporter" ~> 0.0.3

Then run

carthage update --platform ios --use-xcframeworks

Drag and drop ContentsquareModule.xcframework, SwiftProtobuf.xcframework from the Carthage/Build folder to your targets’ General settings tab, in the Frameworks, Libraries, and Embedded Content section.

Our SDK can be linked dynamically or statically:

Dynamic linking

Dynamic linking is the default behavior with use_frameworks!, Add the following line to your Podfile:

pod 'CS_iOS_SDK'
pod 'SwiftProtobuf', '<= 1.26.0'

Static linking

If you specify static linking in your Podfile with use_frameworks! :linkage => :static, Follow these steps:

Add the following line to your Podfile:

pod 'CS_iOS_SDK_STATIC'
pod 'SwiftProtobuf', '<= 1.26.0'

To ensure the library can start properly you will need to add -ObjC as a linker flag under Build Settings > Linking > Other Linker Flags.

Known Issues

Updating IPHONEOS_DEPLOYMENT_TARGET in your post_install may have the following error.

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.

Update your post_install to:

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

Rerun pod install.
Clean Builder Folder.
Rebuild.

Our SDK can be linked dynamically or statically:

Dynamic linking

Get the manual integration framework

Go to the iOS SDK GitHub repository ↗.
Find the newest version available (unless instructed otherwise by your CS contact).
Under Assets you should be able to find ContentsquareModuleDynamicManually.xcframework.zip, download the file.

Include the framework

Unzip ContentsquareModuleDynamicManually.xcframework.zip and you should see a folder named ContentsquareModule containing 2 items:

ContentsquareModule.xcframework
SwiftProtobuf.xcframework
CSCrashReporter.xcframework

Copy ContentsquareModule to any folder in your project.
In your target -> General -> Frameworks, Libraries and Embedded Content, add ContentsquareModule.xcframework, SwiftProtobuf.xcframework and CSCrashReporter.xcframework by clicking ”+” -> “Add Other…” -> “Add Files…“.
Clean build folder and run.

Static linking

Get the manual integration framework

Go to the iOS SDK GitHub repository ↗.
Find the newest version available (unless instructed otherwise by your CS contact).
Under Assets you should be able to find ContentsquareModuleStaticManually.xcframework.zip, download the file.

Include the framework

Unzip ContentsquareModuleStaticManually.xcframework.zip and you should see a folder named ContentsquareModule containing 3 items:
- ContentsquareModule.xcframework
- Resources/ContentsquareBundle.bundle
- SwiftProtobuf.xcframework
- CSCrashReporter.xcframework
Copy ContentsquareModule to any folder in your project.
In your target -> General -> Frameworks, Libraries and Embedded Content, add ContentsquareModule.xcframework, SwiftProtobuf.xcframework and CSCrashReporter.xcframework by clicking ”+” -> “Add Other…” -> “Add Files…“.
Add ContentsquareBundle.bundle to your target, make sure it has been added to your target -> Build Phases -> Copy Bundle Resources.
To ensure the library can start properly you will need to add -ObjC as a linker flag under Build Settings > Linking > Other Linker Flags.
Clean build folder and run.

Start the SDK

Automatic start (default)

By default, 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.

Manual start

If you prefer to control when the SDK starts, you can disable the autostart feature and programmatically start the SDK when needed.

The first step is to add the required key to your Info.plist. The key is CSDisableAutostart of type boolean. To disable the autostart, you need to set its value to true:

Disable autostart using Xcode:
Disable autostart using a text editor:
Info.plist
```
<key>CSDisableAutostart</key>
<true/>
```

Then just call start in the application:didFinishLaunchingWithOptions: of your UIApplicationDelegate like this:

Contentsquare.start()

When you call the start method, the SDK automatically starts tracking users’ interactions with the app (gestures, lifecycle events and crashes).

Validate SDK integration

When the SDK starts, you should see a log like this one:

// success case
Contentsquare SDK v[SDKVersionNumber] starting in app:: [your.bundle.id]

// fail case
// << No public fail log

If the SDK does not seem to work, it might mean that your app’s bundle id is not tied to any Contentsquare project. In that case, you will have to communicate all variants of your app’s 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, track transactions, and more.

Sample App

For best implementation practices of our library, explore the Contentsquare for iOS sample app ↗.

Use Tealium

Our partner Tealium has developed a remote command module to integrate with the Contentsquare SDK. This solution leverages the convenience of iQ Tag Management to configure a native Contentsquare implementation without having to add Contentsquare-specific code to your app.

Follow instructions on Tealium’s documentation: Remote Command for Contentsquare ↗.