Enable privacy protection in the Tealeaf iOS SDK

When capturing user behavior data, you must take measures to exclude personally identifiable information (PII) such as credit card numbers or home addresses.

Before you begin

We recommend assigning accessibility labels or IDs to all UI elements that require privacy protection. You can do it programmatically or with the help of the Attribute Inspector in Xcode.

Ways to set accessibility labels and IDs

Important:

  • Accessibility labels are audible. Accessibility IDs are inaccessible for end users, which makes them useful for internal purposes.
  • 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.
  • If a UI element isn't assigned an accessibility label, accessibility ID or 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.

Instructions

  1. In the root project directory, navigate to PatchTealeafSDK/TealeafLayoutConfig.json.
  2. In the masking object, set HasMasking to true and enter accessibility labels and IDs for masking.
  3. (optional) Enable a custom mask and adjust replacement symbols in the Sensitive property. If the custom mask is disabled, fields containing protected data will appear blank in session replays.
{
  "Masking": {
    "HasMasking": true,
    "HasCustomMask": true,
    "Sensitive": {
      "capitalCaseAlphabet": "X",
      "number": "9",
      "smallCaseAlphabet": "x",
      "symbol": "#"
    },
    "MaskIdList": [],
    "MaskAccessibilityIdList": "pii-08",
    "MaskAccessibilityLabelList": [
      "Card Number",
      "Billing Address"
    ]
  }
}
  1. Validate the file using a JSON validator (the library may be fail to capture session data correctly if the syntax is invalid).

Scope

You can create a general rule for all screens of your app. In that case, nest the rule into the AutoLayout.GlobalScreenSettings object. To create a rule for a particular screen, add the AutoLayout.ScreenName object. Feel free to combine general and screen-specific rules within your TealeafLayoutConfig.json file.

{
  "AutoLayout": {
    "GlobalScreenSettings": {
      "ScreenChange": true,
      "DisplayName": "",
      "CaptureLayoutDelay": 500,
      "ScreenShot": false,
      "NumberOfWebViews": 0,
      "CaptureUserEvents": true,
      "CaptureScreenVisits": true,
      "CaptureLayoutOn": 2,
      "CaptureScreenshotOn": 0,
      "Masking": {
        "HasMasking": true,
        "HasCustomMask": true,
        "Sensitive": {
          "capitalCaseAlphabet": "X",
          "number": "9",
          "smallCaseAlphabet": "x",
          "symbol": "#"
        },
        "MaskIdList": [
          "^9[0-9][0-9][0-9]$"
        ],
        "MaskAccessibilityIdList": [
          "3",
          "myAccessId"
        ],
        "MaskAccessibilityLabelList": [
          "SLIDER slider example",
          "TRANSITIONS"
        ]
      }
    }
  },
  "PaymentViewController": {
    "ScreenChange": true,
    "DisplayName": "",
    "CaptureLayoutDelay": 500,
    "ScreenShot": false,
    "NumberOfWebViews": 0,
    "CaptureUserEvents": true,
    "CaptureScreenVisits": true,
    "CaptureLayoutOn": 2,
    "CaptureScreenshotOn": 0,
    "Masking": {
      "HasMasking": true,
      "HasCustomMask": true,
      "Sensitive": {
        "capitalCaseAlphabet": "X",
        "number": "9",
        "smallCaseAlphabet": "x",
        "symbol": "#"
      },
      "MaskIdList": [],
      "MaskAccessibilityIdList": [
        "pii-1",
        "pii"
      ],
      "MaskAccessibilityLabelList": [
        "Card Number",
        "Billing Address"
      ]
    }
  }
}

Testing privacy settings

To make sure your new rule is working correctly, run the app and enter something into the fields you have masked. Then find the session in Tealeaf and check how the input is displayed.

Tealeaf interface: view accessility label and ID of UI element

Summary of configuration parameters

The masking object in the Tealeaf Layout Configuration file contains all properties related to PII protection.

PropertyNested fieldValuesDescription
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.
SensitivecapitalCaseAlphabetStringThe symbol to display instead of capital letters. Works if HasCustomMask is set to true.
numberStringThe symbol to display instead of numbers. Works if HasCustomMask is set to true.
smallCaseAlphabetStringThe symbol to display instead of lower-case letters. Works if HasCustomMask is set to true.
symbolStringThe symbol to display instead of other characters. Works if HasCustomMask is set to true.
MaskAccessibilityIdListString or array of stringThe accessibility ID assigned to the UI element
MaskAccessibilityLabelListString or array of stringThe accessibility label assigned to the UI element (internal)
MaskIdListString or array of stringThe IDs of UI elements.

All XPath IDs must be converted to regular expressions. For example, you can set the regular expression as ^9[0-9][0-9][0-9]$ to match all the controls whose ID has 4 characters.