SDKs
Help centerCommunityDevelopersAcademyStatus

Integrate the Connect library into a native iOS app

Suggest Edits

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

📘

Note

New to Connect? Install our preconfigured sample app and explore the implementation faster.

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. You can integrate the Connect library into native iOS applications build on Swift and Objective-C. You will need Xcode 15 with Command Line Tools.
  • Mobile app compatibility. The library can capture user experience data on end users' devices running iOS 13 and later.

Limitations

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

Initial setup

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. Open the Podfile in a text editor and make sure the iOS version is 13.0 or later. Then uncomment use_frameworks!.
  3. In the same Podfile, set pod to either AcousticConnect or AcousticConnectDebug, depending on the build you want to use.
source 'https://github.com/CocoaPods/Specs.git'
platform :ios, '13.0'

target 'SwiftUIMindBlowing' do
  use_frameworks!
  pod 'AcousticConnect'
end
  1. In a terminal emulator, navigate to your project directory.
  2. 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.
pod install

Important notes:

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

  1. In your Xcode project, go to File > Add Package Dependencies.
Add package dependencies
  1. 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.
Adding Connect Swift Package
  1. Select the target to add the library to.
Target selection for Connect

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.
touch Cartfile
  1. Open the Cartfile in a text editor and add the following lines for the release build. To add the debug build, update the file names: instead of EOCore.json use EOCoreDebug.json, instead of Tealeaf.json use TealeafDebug.json and instead of Connect.json use ConnectDebug.json.
binary "https://raw.githubusercontent.com/go-acoustic/EOCore/master/EOCore.json"
binary "https://raw.githubusercontent.com/go-acoustic/Tealeaf/master/Tealeaf.json"
binary "https://raw.githubusercontent.com/go-acoustic/Connect/master/Connect.json"

🚧

Warning

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

  1. From the main project directory, run the command carthage update --use-xcframeworks. Make sure it completes without errors.
  2. In a file manager, navigate to /Carthage/Build inside your project directory and select all three bundles.
Connect bundles to copy
  1. 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.
Connect libraries copied to frameworks
  1. 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.
New Copy Files Phase
  1. Rebuild the project.

Required configuration

There are some required steps to finalize the integration.

  1. If your project is built on SwiftUI, make sure it contains the AppDelegate file.
  2. Add the following code to AppDelegate. Replace app_key and endoint_url with the credentials issued for your organization.
import Connect
import EOCore
import Tealeaf
import UIKit

class AppDelegate: UIResponder, UIApplicationDelegate {
  func application(
    _ application: UIApplication,
    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
  ) -> Bool {
    let connectApplicationHelperObj = ConnectApplicationHelper()

    // Enable library to load configuration settings
    let appKey: String = "app_key"
    let postMessageURL: String = "endpoint_url"
    connectApplicationHelperObj.enableFramework(appKey, withPostMessageUrl: postMessageURL)

    return true
  }

  func applicationWillTerminate(_ application: UIApplication) {
    // Called when the application is about to terminate. Save data if appropriate. See also applicationDidEnterBackground:.
  }

  // MARK: UISceneSession Lifecycle

  func application(
    _ application: UIApplication, configurationForConnecting connectingSceneSession: UISceneSession,
    options: UIScene.ConnectionOptions
  ) -> UISceneConfiguration {
    // Called when a new scene session is being created.
    // Use this method to select a configuration to create the new scene with.
    return UISceneConfiguration(
      name: "Default Configuration", sessionRole: connectingSceneSession.role)
  }

  func application(
    _ application: UIApplication, didDiscardSceneSessions sceneSessions: Set<UISceneSession>
  ) {
    // Called when the user discards a scene session.
    // If any sessions were discarded while the application was not running, this will be called shortly after application:didFinishLaunchingWithOptions.
    // Use this method to release any resources that were specific to the discarded scenes, as they will not return.
  }
}
  1. If you have installed the debug version, update your project scheme by adding three environment variables with the value of 1: EODebug, CONNECT_DEBUG and TLF_DEBUG.
Environment variables for debug version

Important:

  • Never use the release and beta builds together in the same project.
  • When reporting an issue to our support team, always attach your debug log. It speeds up troubleshooting.
  1. Open the AppDelegate.m file in your project.
  2. Add 2 import statements to the header.
@import Tealeaf;
@import Connect;
  1. Add the following code to the didFinishLaunchingWithOptions function. Replace app_key and endpoint_url with your Connect credentials.
[[TLFApplicationHelper sharedInstance] enableTealeafFramework:@"app_key" withPostMessageUrl:@"endpoint_url"];
Customized AppDelegate.m
  1. 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.
Environment variables

👍

What's next?

Now you can build and run your app.

Related instructions

Updated 3 days ago