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

platform :ios, '15.1'

target 'UIKitCatalog' do
  use_frameworks!
  pod 'AcousticConnectDebug'
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

pod install

Adding configuration files (Carthage and Swift Package)

At runtime, the Connect SDK loads its configuration from two folders that must be present inside your app bundle: EOCoreSettings.bundle (for EOCore settings) and TLFResources.bundle (for Tealeaf settings). Carthage and Swift Package integrations do not create these folders automatically, so you must set them up manually before building. The Connect framework ships its own ConnectResources.bundle internally — you do not need to create or add it.

1. Inside your Xcode project's source folder (for example, next to AppDelegate.m), create two folders: EOCoreSettings.bundle and TLFResources.bundle.

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

2. Open each bundle using the Show package contents option in Finder.
3. Copy the following configuration files from our GitHub repository into the matching bundle. Make sure each file goes into the bundle listed in the Destination column.

🚧

Important

Place each file inside the correct bundle. If the Tealeaf files are placed in EOCoreSettings.bundle (or vice versa), the SDK silently falls back to default settings and the integration may not work as expected. Do not place the files loose in the app bundle root either — the SDK only searches inside the two named bundles.

4. In Xcode, drag both EOCoreSettings.bundle and TLFResources.bundle into the project navigator and add them to the primary target.

5. Open the primary target. On the Build Phases tab, confirm that both bundles appear under Copy Bundle Resources. If they don't, drag them in manually.

6. In TLFResources.bundle, open TealeafBasicConfig.plist. Set KillSwitchEnabled to NO and update the following values:

   • AppKey — your Connect app key.
   • PostMessageUrl — your Connect collector URL.
   • KillSwitchUrl — has the structure https://<collector-host>/collector/switch/<app_key>.

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