Before you start integrating the Tealeaf SDK into your app, we recommend installing our sample app with the SDK.

Requirements

• Acoustic Tealeaf. To view captured sessions and playback from the sample app, you need an active Tealeaf subscription.
• Development environment. To build and run the sample app, you need Xcode 15 with Command Line Tools and a recent CocoaPods version.
• Mobile app compatibility. You can run the sample app on simulators and real devices. iOS 13 or later is required.

Before you begin

During the setup, you will need to register the sample app with your Acoustic Tealeaf credentials. You can generate them yourself through the Tealeaf interface.

1. Log in to Acoustic Tealeaf as an administrator.
2. In the menu bar, click on your user profile and select Admin.

3. On the Admin page, open the Applications tab.

4. If a new app is required, click to add an app and fill out required settings.
5. Click the SDK link for your app. Copy access credentials from the code snippet on the iOS tab: application code and post message URL. Keep them handy for the setup.

Initial setup

1. Clone the sample app code from GitHub.

git clone https://github.com/acoustic-analytics/SwiftUIMindBlowing.git

2. Go to the sample app directory.

cd /Users/admin/SwiftUIMindBlowing

3. Install the pods and 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

4. Open the SwiftUIMindBlowing.xcworkspace file (not SwiftUIMindBlowing.xcodeproj).

5. Confirm that you trust the workspace and want to open it.

6. In Xcode, open a basic configuration file SwiftUIMindBlowing-main/Pods/TealeafDebug/SDKs/iOS/Debug/TLFResources.bundle/TealeafBasicConfig.plist and update 2 keys in it using your Tealeaf credentials: AppKey and PostMessageUrl.

7. Use the SwiftUIMindBlowing target to build and run the app.

Exercises

Exercise 1: Test session replay

Now you can check how user behavior data is captured.

1. Click around in the sample app.
2. In the Xcode debug area, search for SERVER SESSION ID. You will find the ID that Tealeaf has assigned to the current session. In our example, it's FA695124CCA445034996E52DE7C94A82.

Tealeaf - NSURLSession:SERVER SESSION ID for ACOUSTIC EXPERIENCE ANALYTICS (TEALEAF): FA695124CCA445034996E52DE7C94A82

3. In Tealeaf, find the session by the ID and click to play it back. To learn more about the Sessions module, see Session replay Session replay in our help centre.

📘

Note

User sessions in Tealeaf time out after 30 minutes of inactivity.

Exercise 2: Enable privacy protection

When capturing user behavior data, you must take measures to prevent personally identifiable information (PII) from leaving the app. That is why we recommend going back to the Xcode project and making yourself familiar with masking and blocking PII in Tealeaf.

We recommend using accessibility labels or IDs to identify the UI elements that require privacy protection. Keep in mind that accessibilty labels are audible while accessibility IDs are inaccessible for end users, which makes them useful for internal purposes.

📘

Note

Using the same accessibility labels across the iOS and Android versions of an app creates consistency and is considered an industry standard. For more information, see Mobile Accessibility at W3C.

Assign an accessibility label to a text field

Try assigning an accessibility label or ID to a text field in the sample app. You can do it programmatically or with the help of the Attribute Inspector in Xcode.

📘

Note

If a UI element in an app isn't assigned an accessibility label (ID) or a static ID, Tealeaf uses its XPath. You can enable privacy masking for the XPath, but it will be necessary to convert it to a regular expression first.

Create a privacy rule for Tealeaf

The easiest way to ensure PII isn't captured is to create a rule for the related input field. As a result, the text that users enter to this field will not be captured. In replays, the input will be masked or simply blank (depends on your settings).

1. In a Tealeaf session, find the text field to enable privacy protection for.

2. Open the Raw data tab. In the accessibility object, find the accessibility tags you have assigned to the text field.

{
  "target": {
    "visitedCount": 1,
    "id": "[w,0],[v,0],[v,0],[v,0],[v,0],[v,0],[v,0],[v,0],[v,0],[v,0],[v,0],[v,0],[v,0],[v,0],[v,1],[t,0]",
    "tlType": "textBox",
    "idType": -4,
    "accessibility": {
      "id": "tll-05-28",
      "label": "privacyTest"
    }
  }
}

3. In the Xcode project, navigate to /SwiftUIMindBlowing/PatchTealeafSDK/TealeafLayoutConfig.json.
4. In the masking object, set HasMasking to true and enter the accessibility label or ID for masking. You can add as many labels or IDs as needed.

{
  "Masking": {
    "HasMasking": true,
    "HasCustomMask": true,
    "Sensitive": {
      "capitalCaseAlphabet": "X",
      "number": "9",
      "smallCaseAlphabet": "x",
      "symbol": "#"
    },
    "MaskIdList": [],
    "MaskAccessibilityIdList": "tll-05-28"
  }
}

5. Validate the file using a JSON validator tool.
6. Build and run the sample app.
7. In the sample app, enter something into the field you have masked.
8. In the Xcode debug area, copy the session ID.
9. In Tealeaf, find the session by the ID and check how your data entry is replayed.

Reference

Tealeaf JSON

The target object in the Tealeaf JSON file contains the following properties.

TealeafLayoutConfig.json in Xcode

The masking object in the Tealeaf Layout Configuration file contains the properties that you will need for masking. All of the properties are optional.