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 Swift and track the findings in the Acoustic Connect interface. This guide uses the current ConnectSDK API. For Objective-C instructions, see Integrate the Connect SDK into a native iOS app (Objective-C).

Requirements

• Acoustic Connect subscription. You must register your app in Connect and get credentials for it. For instructions, see Connect mobile apps in the user guide.
• Development environment. Xcode 16 or later.
• Deployment target. iOS 15.1 or later.

Limitations

We offer limited support for iPad apps with a multi-window architecture as well as iOS apps using SwiftUI and UIScene. 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

Choose a package manager to add the Connect iOS library to your app.

The easiest way to add the Connect iOS library is with Swift Package Manager.

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

2. Enter the repository URL https://github.com/go-acoustic/ConnectDebug-SP. For the release build, replace ConnectDebug-SP with Connect-SP.

3. Set the dependency rule to Up to Next Major Version from 2.0.0.

4. In the target selection dialog, select your main app target.

Notes

Verification

To verify the installation, add import Connect to any Swift file — or create a new one for this purpose — and build. If it compiles without errors, the SDK is correctly linked.

import Connect
// If this builds, the SDK is installed correctly.

Adding an AppDelegate (SwiftUI)

The integration relies on the AppDelegate file. If your app is built on SwiftUI, AppDelegate is not generated and not required unless you need UIKit-level lifecycle hooks (like SDK initialization). So you must add it manually and register it with @UIApplicationDelegateAdaptor.

1. In Xcode, click File > New > File from template > Cocoa Touch Class.
2. Configure the properties as shown below.

3. Add the file to the primary project target.
4. In the @main App struct, use @UIApplicationDelegateAdaptor to bridge to an AppDelegate:

import SwiftUI

@main
struct YourApp: App {
    @UIApplicationDelegateAdaptor(AppDelegate.self) private var appDelegate

    var body: some Scene {
        WindowGroup {
            ContentView()
        }
    }
}

📘

Note

Always initialize the SDK in didFinishLaunchingWithOptions, not in a SwiftUI .onAppear or .task modifier. The SDK must be initialized at UIKit lifecycle time to ensure data capture starts before any user interaction occurs.

Required configuration

To finalize the integration, add the following code to AppDelegate. Replace YOUR_APP_KEY and YOUR_COLLECTOR_URL with the credentials issued for your organization.

import Connect
import UIKit

class AppDelegate: UIResponder, UIApplicationDelegate {
    func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? = nil
    ) -> Bool {
        ConnectSDK.shared.enable(
            with: ConnectConfig(
                appKey: "YOUR_APP_KEY",
                postURL: "YOUR_COLLECTOR_URL"
            )
        )
        return true
    }
}

If you have installed the debug version of the SDK, add three environment 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:

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

Push notifications

To add push notifications with delivery tracking and rich media images to your app, see Configure push notifications for iOS.

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, open the project target, go to Build Settings, and set User Script Sandboxing to No. This setting may not survive a pod install unless the hook is also in place.

Related instructions

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