You can integrate the Tealeaf SDK into native iOS applications build on Swift, SwiftUI and Objective-C.

📘

Note

New to Tealeaf? Install our preconfigured sample app and learn the implementation faster.

Requirements

• Acoustic Tealeaf. To use the library, your company must have an active Tealeaf subscription.
• Development environment. You can integrate the Tealeaf SDK into native iOS applications build on Swift, SwiftUI 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. On iPadOS, only single-window applications are currently supported.

🚧

Warning

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

Prerequisites

If your project is built on SwiftUI, make sure it contains AppDelegate.

Beta vs. release version

If you haven't used the Tealeaf SDK before, we highly recommend starting with the beta version (TealeafDebug). It contains debug information.

Here is how to enable debug logs in your Xcode console window:

1. Use the beta version during the initial setup.
2. Update your project scheme by adding two environment variables with the value of 1: EODebug and TLF_DEBUG.

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.

Initial setup

The easiest way to install the Tealeaf SDK is using a dependency manager. A manual option is also available - see Manually integrate the Tealeaf SDK into your iOS app.

• CocoaPods
• Carthage
• Swift package

You can add the Tealeaf SDK 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 12.0 or later. Then uncomment use_frameworks!.
3. In the same Podfile, set pod to either Tealeaf or TealeafDebug, depending on the build you want to use.

Ruby

source 'https://github.com/CocoaPods/Specs.git'
platform :ios, '12.0'

target 'SwiftUIMindBlowing' do
  use_frameworks!
  pod 'TealeafDebug'
end

4. In a terminal emulator, navigate to your project directory.
5. 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

Important notes:

• Sometimes CocoaPods fails to load the latest version. So you may need to pull it using pod update.
• Use the $(inherited) flag in your application target's "Other Linker Settings". This will ensure all the Pods are linked correctly.

You can add the Tealeaf iOS SDK to your 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 release build. To use the beta build, update the file names: instead of Tealeaf.json use TealeafDebug.json and instead of EOCore.json use EOCoreDebug.json.

binary "https://raw.githubusercontent.com/acoustic-analytics/Tealeaf/master/Tealeaf.json"
binary "https://raw.githubusercontent.com/acoustic-analytics/EOCore/master/EOCore.json"

3. From the root 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 two bundles: EOCore.xcframework and Tealeaf.xcframework.

5. Select the primary project target. Drag and drop the bundles to Frameworks, Libraries, and Embedded Content in the target settings. Select Embed & Sign for each bundle.

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

7. Rebuild the project.

You can add the Tealeaf iOS SDK as a Swift Package.

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

2. Search for https://github.com/go-acoustic/Tealeaf-SP. For the beta build, replace Tealeaf-SP with TealeafDebug-SP.

3. Select the target to add the library to.

Required configuration

• Swift/SwiftUI
• Objective-C

1. Open the AppDelegate.swift file and add 2 import statements there.

Swift

import EOCore
import Tealeaf

2. Add the Tealeaf framework to the AppDelegate class. In the example below, app_key is the application key and endoint_url is the endpoint URL assigned to your organization. You must replace these with your own credentials.

Swift

TLFApplicationHelper().enableTealeafFramework(
      "app_key",
      withPostMessageUrl: "endpoint_url")

3. (optional) If you want your application to capture the identifier for advertisers (IDFA) data using the Tealeaf AdvertisingId property, add the following snippet to the AppDelegate class:

Swift

TLFApplicationHelper.sharedInstance().setCXAAdvertisingId(
      ASIdentifierManager.shared().advertisingIdentifier.uuidString)

4. Build and run the application.

1. Open the AppDelegate.m file in your project.
2. Add the Tealeaf import statement to the header.

Objective-C

@import Tealeaf;

3. Add the following code to the didFinishLaunchingWithOptions function. Replace app_key and endpoint_url with your Tealeaf credentials.

Objective-C

[[TLFApplicationHelper sharedInstance] enableTealeafFramework:@"app_key" withPostMessageUrl:@"endpoint_url"];

4. (optional) If you want your application to capture Apple identifier for advertisers (IDFA) data, add an additional snippet to AppDelegate.m.

Swift

TLFApplicationHelper.sharedInstance().setCXAAdvertisingId(
      ASIdentifierManager.shared().advertisingIdentifier.uuidString)

5. Build and run the application.

Further steps

1. To verify the integration, click around in your app and then find the session in Tealeaf. For details, see Session replay in our support center.
2. Make sure the library doesn't capture visitors' personally identifiable information (PII). To learn more, see Enable privacy protection in the Tealeaf iOS SDK.