This knowledge base article builds upon our existing documentation regarding element data capture rules. It goes over the intricacies of formulating rules specifically tailored for mobile clients. To fully benefit from this article, we recommend reviewing the foundational information provided in the preceding documentation, as this piece will focus exclusively on the application of element data capture rules for mobile clients and presupposes familiarity with the fundamental concepts of crafting element data capture rules.

Historically, element data capture rules on mobile clients could only use child combinator syntax. From December 18th, 2024, Fullstory has expanded functionality to include  descendant combinator syntax, allowing for more flexible rule creation.

Utilizing Descendant Combinators for Mobile Element Data Capture Rules

With the update effective from December 18th, 2024, mobile capture clients equipped with SDK version 1.54.0 or newer now have the ability to employ descendant combinator syntax in their element data capture rules.

Crafting these rules requires careful consideration of several factors. This guide aims to provide the necessary context to help you navigate these considerations and make informed decisions that align with your organization's needs.

Platform Selection for Rules

When creating an element data capture rule, it's advisable to specify the platform(s) where the rule will be active. Options include iOS, Android, Web, or any combination of these.

For optimal results, we suggest defining separate rules for each mobile platform due to the distinct differences in CSS selector syntax between iOS, Android and web apps. However, if your application uses a cross-platform framework like React Native and the CSS selectors are consistent across the selected platforms, it is then appropriate to apply the rule to multiple platforms.

Crafting an Element Data Capture Rule for Masking or Exclusion

After selecting your desired platform(s) and determining whether to mask or exclude data, you’re now equipped to input the appropriate CSS selector.

When utilizing descendant combinator syntax, a new input field labeled "Backup selector" will become available. The following section explains the purpose and use of this additional field.

Understanding the Backup Selector

Upon entering your chosen selector, you'll encounter the "Backup selector" field. This field is particularly relevant because descendant selectors are supported exclusively by Fullstory mobile SDK versions 1.54.0 and above. The backup selector is intended for use with older SDK versions that do not support descendant combinator syntax.

By default, an automatically generated backup selector is provided. This selector aims to target the last element (leaf node) within your original selector's hierarchy, ensuring continuity and compatibility for app versions running older Fullstory SDKs.

While the backup selector is created for your convenience, you may choose to modify it if you prefer to use a different selector than the one automatically provided. It is crucial to remember that descendant combinator syntax cannot be used for the backup selector. Utilizing descendant syntax in the backup selector could result in the rule not being processed by older SDK versions, potentially leading to unintended data exposure.

Formulating an Element Data Capture Rule to Unmask Data

The process for establishing an unmask rule within your mobile application is similar to creating mask or exclude rules. However, it's important to note a key difference when using descendant combinator syntax for unmask rules: a backup selector will not be generated. By not enabling a backup selector for unmask rules, the risk of inadvertent collection of sensitive data is mitigated on mobile app versions that run on Fullstory SDK versions older than 1.54.0. As a result, unmask rules that employ descendant combinator syntax will be effective only on app versions equipped with SDK version 1.54.0 or newer.

To implement an unmask rule across all versions of your app, opt for child combinator syntax instead. By doing so, the unmask rule will be universally applied to mobile sessions for the given platform, irrespective of the Fullstory SDK version in use.To implement an unmask rule across all versions of your app, opt for child combinator syntax instead. By doing so, the unmask rule will be universally applied to mobile sessions for the given platform, irrespective of the Fullstory SDK version in use.

Updating a Mask or Exclude Element Data Capture Rule

When adjusting a mask or exclude rule for mobile clients that incorporates descendant combinator syntax, it's essential to consider the following aspects:

Adjusting the Selector

Upon modifying the primary selector of your rule, you may observe that the backup selector remains unchanged. This is by design. While you can alter the main selector to address changes in your app, the backup selector is intended for app versions not yet updated to SDK version 1.54.0 or higher. These older app versions, which do not reflect the most recent changes, do not necessitate an updated backup selector.

To put it metaphorically, if you had a historical map of 19th-century London, you wouldn't update it to reflect a contemporary building erected today.

Updating the Backup Selector

In certain scenarios, you might find it necessary to adjust the backup selector. This section will guide you through that process.

Upon editing the backup selector, you will encounter a warning message once you navigate away from the input field. This message serves as a reminder of the considerations highlighted earlier in this article. Typically, if your backup selector functions correctly, there should be no need to modify it. Yet, should you choose to proceed with changes, clicking “Update Selector” will confirm your modifications. It's important to note that this warning will appear every time you alter the backup selector, even within the same editing session.

Should you decide against the modifications, selecting “Cancel” will revert the backup selector to its previous state. This reversion will reflect the last confirmed update by selecting “Update Selector,” or if no prior updates have been made, it will revert to the original state from when the edit session began.

Transitioning from a Mask or Exclude Rule to an Unmask Rule

Modifying an existing mask or exclude rule that uses descendant combinator syntax into an unmask rule will result in the automatic removal of the backup selector. A warning message will appear message indicating this change.

As Fullstory does not support backup selectors for unmask rules with descendant combinator syntax, you'll need to use child combinator syntax to apply the unmask rule across all app versions. Otherwise, the rule will only be active for mobile app versions running Fullstory SDK version 1.54.0 or above.

FAQ

Why do I receive a warning when I select a mobile and web platform?

When creating rules that target multiple platforms, a warning may appear as a reminder to double-check your selections. Android, iOS, and web platforms have distinct CSS selector syntax, but there can be overlap. This warning is simply a precautionary measure to verify the platforms you select align with your intended outcome. If your application uses a framework like React Native, where the selectors can be consistent across mobile and web, it is perfectly acceptable to apply the rule to multiple platforms.

Why are all platforms selected by default on my existing rules?

Previously, element data capture rules were read by all capture clients without discrimination, including web, iOS, and Android, even if they were not actively used on all platforms. To maintain consistency with past behavior, these rules have been updated to indicate they apply to all platforms. You now have the option to refine the platform targeting for your existing rules based on your current needs.

Why is the platform field disabled and only 'Web' is selected?

If the platform field is disabled with 'Web' as the sole option, it indicates that the native mobile capture feature is not enabled for your Fullstory organization. To explore Fullstory's native mobile capture capabilities and understand how to enable them, please visit our mobile capture documentation.

Why does it say my automatically generated backup selector is a duplicate?

When an automatically generated backup selector is created, it generates a selector using the right most node (leaf) within your original selector chain. Consequently, different selectors using descendant combinator syntax might target distinct elements, yet produce identical backup selectors. Consider the following example:

Original Selectors:

• linearlayout[fragment="menu"] appcompattextview[type="text"]
• linearlayout[fragment="sidebar"] appcompattextview[type="text"]

Both yield the same backup selector:

• appcompattextview[type="text"]

This occurs because the backup selector extraction process isolates the most specific common node. To resolve this, you can manually enter a custom backup selector utilizing child combinator syntax. For instance:

Custom Backup Selector:

• linearlayout[fragment="sidebar"]>sidebarview>appcompattextview[type="text"]

This approach ensures that each backup selector is unique and accurately reflects the intended element targeting.

Why do all my existing rules have their selector as their name?

The addition of new fields such as 'platforms' and 'name' to the element data capture rule configuration was made to enhance the user experience. As part of this update, the selector of existing rules was initially populated into the 'name' field to maintain consistency with the previous display in the element data capture rule table. This was a starting point to guarantee an acceptable level of continuity. You are encouraged to rename the 'name' field for any of your existing rules to better describe their purpose or function.