Build a sample app to evaluate the Tealeaf iOS SDK

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.
  1. On the Admin page, open the Applications tab.
  1. If a new app is required, click to add an app and fill out required settings.
  2. 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
  1. Go to the sample app directory.
cd /Users/admin/SwiftUIMindBlowing
  1. 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
  1. Open the SwiftUIMindBlowing.xcworkspace file (not SwiftUIMindBlowing.xcodeproj).
  1. Confirm that you trust the workspace and want to open it.
  1. 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.
Entering Tealeaf credials to configuration file
  1. Use the SwiftUIMindBlowing target to build and run the app.
SwiftUIMindBlowing target in Xcode

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
  1. 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.
Session search in Tealeaf

πŸ“˜

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.

Ways to set accessibility labels and IDs

πŸ“˜

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.
Tealeaf interface: view accessility label and ID of UI element
  1. 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"
    }
  }
}
  1. In the Xcode project, navigate to /SwiftUIMindBlowing/PatchTealeafSDK/TealeafLayoutConfig.json.
  2. 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"
  }
}
  1. Validate the file using a JSON validator tool.
  2. Build and run the sample app.
  3. In the sample app, enter something into the field you have masked.
  4. In the Xcode debug area, copy the session ID.
  5. 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.

PropertyValuesRequired?Description
idStringRequiredThe ID of a UI element
tlTypeStringRequiredThe type of the UI element
accessibilityObject with the following keys:

- id
- label
OptionalThe accessibility tags assigned to the UI element
idTypeInteger.

For a native iOS app, the following values are supported:

- 1 - native
-3 - hash code
-4 - XPath
RequiredIndicates what the element ID is based on

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.

PropertyValuesDescription
HasMaskingBooleanSet the value to true to allow masking.
HasCustomMaskBooleanIf a custom mask is enabled, protected text is replaced with symbols. If not, it appears as blank.
MaskAccessibilityIdListString or array of stringThe accessibility ID assigned to the UI element (user-accessible)
MaskAccessibilityLabelListString or array of stringThe accessibility ID assigned to the UI element (internal)
MaskIdListString or array of stringThe IDs of UI elements.

All XPath IDs must be converted to regular expressions.