The Connect SDK is a library that captures visitors' interactions with mobile applications. You can integrate the library into your native iOS app written in Objective-C and track the findings in the Acoustic Connect interface.

📘

Note

For Swift instructions, see Integrate the Connect SDK into a native iOS app (Swift) .

Requirements

• Acoustic Connect. To use the Connect SDK, your company must have an active Connect subscription. Proper credentials are required for each app. For instructions, see Generate Connect credentials for integration.
• Development environment. Xcode with Command Line Tools.
• Mobile app compatibility. The library can capture user experience data on end users' devices running iOS 15.1 and later. On iPadOS, only single-window applications are fully supported.

Limitations

We offer limited support for iPad apps with a multi-window architecture. The library captures data from such apps and makes it available for analytics, but session replays may not work correctly.

General guidelines

It is important that you assign unique IDs to all UI controls that you want to capture.

Initial setup

• CocoaPods
• Swift Package
• Carthage

You can add the Connect library to your iOS app using the CocoaPods dependency manager. This option requires a recent version of CocoaPods.

Here are steps to follow:

1. If you don't have a Podfile in your Xcode project directory, create one.
2. Update the file as shown below. Set pod to either AcousticConnect or AcousticConnectDebug, depending on the build you want to use.
3. Additionally, disable User Script Sandboxing to prevent a build error (see the Troubleshooting section below).

Ruby

platform :ios, '15.1'

target 'UIKitCatalog' do
  use_frameworks!
  pod 'AcousticConnectDebug', '1.0.108'
end

post_install do |installer|
  installer.generated_projects.each do |project|
    project.targets.each do |target|
      target.build_configurations.each do |config|
        config.build_settings['ENABLE_USER_SCRIPT_SANDBOXING'] = 'NO'
      end
    end
  end
end

4. In a terminal emulator, navigate to the root project directory and install the pods. Make sure the command is completed with no errors. If you get an error, run the same command with the --verbose option and share the error log with our services team.

Shell

pod install

5. Close any current Xcode sessions and start using the new .xcworkspace file for your project from now on.

Important notes:

• Sometimes CocoaPods fails to load the latest version. So you may need to pull it using pod update.
• If you get a warning message after running pod install, see our help article Removing CocoaPods warnings during integration.

You can add the Connect iOS library as a Swift Package.

1. In your Xcode project, go to File > Add Package Dependencies.

2. Search for https://github.com/go-acoustic/Connect-SP . For the debug build, replace Connect-SP with ConnectDebug-SP. Never use both versions in the same project.

3. Select the target to add the library to.

You can add the Connect library to your iOS app using the Carthage dependency manager.

1. Create a Cartfile in your Xcode project directory if you don't have one yet.

Shell

touch Cartfile

2. Open the Cartfile in a text editor and add the following lines for the debug build. To add the release build, remove "Debug" from the file names.

binary "https://raw.githubusercontent.com/go-acoustic/EOCore/master/EOCoreDebug.json"
binary "https://raw.githubusercontent.com/go-acoustic/Tealeaf/master/TealeafDebug.json"
binary "https://raw.githubusercontent.com/go-acoustic/Connect/master/ConnectDebug.json"

🚧

Warning

Never use the release and debug builds together in the same project.

3. From the main project directory, run the command carthage update --use-xcframeworks. Make sure it completes without errors.
4. In a file manager, navigate to /Carthage/Build inside your project directory and select all three bundles.

5. In your Xcode project, select the primary project target. Drag and drop the bundles to Frameworks, Libraries, and Embedded Content. Select Embed & Sign for each bundle.

6. Switch to the Build Phases tab and make sure all three appear under Embed Frameworks. If they don't, you will need to add them as frameworks.

7. Rebuild the project.

Adding configuration files (Carthage and Swift Package)

The Connect SDK (EOCore) locates its configuration at runtime by searching the app bundle for a folder named EOCoreSettings.bundle. Carthage and Swift Package do not create this bundle automatically, so you must set it up manually before building.

1. Create a new folder named EOCoreSettings.bundle inside your Xcode project's source folder (for example, next to AppDelegate.m).

cd /Users/admin/Developer/UIKitCatalog/Main
mkdir EOCoreSettings.bundle

2. Open the bundle using the Show package contents option in Finder.
3. Copy the following configuration files from our Github repository into the bundle.

🚧

Important

Do not place the configuration files loose in the app bundle root. The SDK only searches inside EOCoreSettings.bundle and will not find files at the root level.

4. In Xcode, drag EOCoreSettings.bundle into the project navigator and add it to the primary target as shown in the screenshot.

5. Open the primary target. On the Build Phases tab, confirm the bundle appears under Copy Bundle Resources. If it doesn't, drag it in manually.

6. In EOCoreSettings.bundle, open TealeafBasicConfig.plist. Set KillSwitchEnabled to NO and update the following values in it based on your Connect credentials: AppKey, PostMessageUrl and KillSwitchUrl.

Required configuration

There are some required steps to finalize the integration.

1. Add 2 import statements to the AppDelegate.m header.

@import Tealeaf;
@import Connect;

2. Add the following code to the didFinishLaunchingWithOptions function. Replace app_key and collector_url with your Connect credentials.

[[ConnectApplicationHelper sharedInstance] enableFramework:@"app_key" withPostMessageUrl:@"collector_url"];

3. If you have installed the debug version, add three variables with the value of 1 to the project scheme: EODebug, CONNECT_DEBUG and TLF_DEBUG. This enables the SDK to write debug logs to your Xcode console window.

Important:

• Never use the release and beta builds together in the same project.
• When running on the iOS Simulator, you may see com.apple.commcenter.coretelephony.xpc errors in the console. These are expected — the Simulator has no cellular radio — and do not affect SDK operation.
• When reporting an issue to our support team, always attach your debug log. It speeds up troubleshooting.

Troubleshooting

Build fails at [CP] Embed Pods Frameworks with rsync "Operation not permitted"

Projects using Xcode 15 or later may encounter this error when integrating the Connect SDK through CocoaPods.

Symptom

The build fails at the [CP] Embed Pods Frameworks phase. The full error output in the Xcode build log contains lines similar to the following:

rsync(XXXXX): warning: ...Connect.framework/_CodeSignature: unreadable directory: Operation not permitted
rsync(XXXXX): error: Connect.framework/ConnectResources.bundle/: mkpathat: Operation not permitted
rsync(XXXXX): error: ...Connect.framework/Info.plist: open (2) in <project dir>: Operation not permitted
rsync(XXXXX): warning: child XXXXX exited with status 1

Cause

Xcode 15 and later enables User Script Sandboxing (ENABLE_USER_SCRIPT_SANDBOXING) by default. This restricts what build phase scripts can read and write, and prevents the CocoaPods embed-frameworks script from copying xcframeworks into the app bundle at build time.

Fix

Add a post_install hook to your Podfile:

post_install do |installer|
  installer.generated_projects.each do |project|
    project.targets.each do |target|
      target.build_configurations.each do |config|
        config.build_settings['ENABLE_USER_SCRIPT_SANDBOXING'] = 'NO'
      end
    end
  end
end

After adding the hook, run pod install and rebuild.

This approach persists across future pod install runs. If you prefer to apply the fix manually, go to Xcode → target Build Settings, search for User Script Sandboxing, and set it to No — but note this setting will not survive a pod install unless the hook is also in place.

Related instructions

• iOS SDK privacy manifests
• Connect iOS SDK public API reference