Getting Started

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

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

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

2. 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 lines to your Cartfile:

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

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 is the default behavior with use_frameworks!, Add the following line to your Podfile:

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

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

1. Add the following line to your Podfile:

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

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

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

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

  2. Rerun pod install.

  3. Clean Builder Folder.

  4. Rebuild.

Our SDK can be linked dynamically or statically:

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

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

• ContentsquareModule.xcframework
• SwiftProtobuf.xcframework

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

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

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

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.

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:

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

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.

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

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