Getting Started
Add Contentsquare to your app
Section titled Add Contentsquare to your appOur iOS SDK is shipped as a .xcframework
which you need to add as a dependency of your project.
How to include it
Section titled How to include itThe 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.githttps://github.com/apple/swift-protobuf.gitSpecify 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 underBuild 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.0github "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
Section titled Dynamic linkingDynamic 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
Section titled Static linkingIf you specify static linking in your Podfile with use_frameworks! :linkage => :static
,
Follow these steps:
-
Add the following line to your Podfile:
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 underBuild Settings
>Linking
>Other Linker Flags
.
Known Issues
Section titled Known Issues-
Updating
IPHONEOS_DEPLOYMENT_TARGET
in yourpost_install
may have the following error.dyld[47592]: Symbol not found: __ZN5swift34swift50override_conformsToProtocolEPKNS_14TargetMetadataINS_9InProcessEEEPKNS_24TargetProtocolDescriptorIS1_EEPFPKNS_18TargetWitnessTableIS1_EES4_S8_EReferenced from: XxxxWorkaround: Skip updating IPHONEOS_DEPLOYMENT_TARGET for SwiftProtobuf by following these steps.
-
Update your
post_install
to:Podfile post_install do |installer|installer.pods_project.targets.each do |target|# Skip updating IPHONEOS_DEPLOYMENT_TARGET for SwiftProtobufnext if target.to_s == 'SwiftProtobuf'target.build_configurations.each do |config|config.build_settings['IPHONEOS_DEPLOYMENT_TARGET'] = 'XX.X'endendend -
Rerun
pod install
. -
Clean Builder Folder.
-
Rebuild.
-
Our SDK can be linked dynamically or statically:
Dynamic linking
Section titled Dynamic linkingGet the manual integration framework
Section titled 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 findContentsquareModuleDynamicManually.xcframework.zip
, download the file.
Include the framework
Section titled Include the framework- Unzip
ContentsquareModuleDynamicManually.xcframework.zip
and you should see a folder namedContentsquareModule
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
, addContentsquareModule.xcframework
,SwiftProtobuf.xcframework
andCSCrashReporter.xcframework
by clicking ”+” -> “Add Other…” -> “Add Files…“. - Clean build folder and run.
Static linking
Section titled Static linkingGet the manual integration framework
Section titled 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 findContentsquareModuleStaticManually.xcframework.zip
, download the file.
Include the framework
Section titled Include the framework- Unzip
ContentsquareModuleStaticManually.xcframework.zip
and you should see a folder namedContentsquareModule
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
, addContentsquareModule.xcframework
,SwiftProtobuf.xcframework
andCSCrashReporter.xcframework
by clicking ”+” -> “Add Other…” -> “Add Files…“. - Add
ContentsquareBundle.bundle
to your target, make sure it has been added to yourtarget
->Build Phases
->Copy Bundle Resources
. - To ensure the library can start properly you will need to add
-ObjC
as a linker flag underBuild Settings
>Linking
>Other Linker Flags
. - Clean build folder and run.
Start the SDK
Section titled Start the SDKAutomatic start (default)
Section titled 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
Section titled Manual startIf 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
Section titled Validate SDK integrationWhen the SDK starts, you should see a log like this one:
// success caseContentsquare 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
Section titled Sample AppFor best implementation practices of our library, explore the Contentsquare for iOS sample app.
Use Tealium
Section titled Use TealiumOur 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.