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.
- Log in to Acoustic Tealeaf as an administrator.
- In the menu bar, click on your user profile and select Admin.
- On the Admin page, open the Applications tab.
- If a new app is required, click to add an app and fill out required settings.
- 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
- Clone the sample app code from GitHub.
git clone https://github.com/acoustic-analytics/SwiftUIMindBlowing.git
- Go to the sample app directory.
cd /Users/admin/SwiftUIMindBlowing
- 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
- Open the SwiftUIMindBlowing.xcworkspace file (not SwiftUIMindBlowing.xcodeproj).
- Confirm that you trust the workspace and want to open it.
- 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
andPostMessageUrl
.
- 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.
- Click around in the sample app.
- 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'sFA695124CCA445034996E52DE7C94A82
.
Tealeaf - NSURLSession:SERVER SESSION ID for ACOUSTIC EXPERIENCE ANALYTICS (TEALEAF): FA695124CCA445034996E52DE7C94A82
- 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).
- In a Tealeaf session, find the text field to enable privacy protection for.
- 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"
}
}
}
- In the Xcode project, navigate to
/SwiftUIMindBlowing/PatchTealeafSDK/TealeafLayoutConfig.json
. - In the
masking
object, setHasMasking
totrue
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"
}
}
- Validate the file using a JSON validator tool.
- Build and run the sample app.
- In the sample app, enter something into the field you have masked.
- In the Xcode debug area, copy the session ID.
- 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.
Property | Values | Required? | Description |
---|---|---|---|
id | String | Required | The ID of a UI element |
tlType | String | Required | The type of the UI element |
accessibility | Object with the following keys: - id - label | Optional | The accessibility tags assigned to the UI element |
idType | Integer. For a native iOS app, the following values are supported: - 1 - native- 3 - hash code- 4 - XPath | Required | Indicates 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.
Property | Values | Description |
---|---|---|
HasMasking | Boolean | Set the value to true to allow masking. |
HasCustomMask | Boolean | If a custom mask is enabled, protected text is replaced with symbols. If not, it appears as blank. |
MaskAccessibilityIdList | String or array of string | The accessibility ID assigned to the UI element (user-accessible) |
MaskAccessibilityLabelList | String or array of string | The accessibility ID assigned to the UI element (internal) |
MaskIdList | String or array of string | The IDs of UI elements. All XPath IDs must be converted to regular expressions. |
Updated 3 months ago