Mobile Tagging - Technical Info

Last Updated: September 12, 2023 10:06

This article provides an overview of the technicalities of Pendo mobile tagging.

Mobile analytics identification is different from web identification in two ways:

Mobile doesn't have URLs representing pages
CSS rules representing buttons/features.

Identifying screens and buttons is the basis for guide display as well.

How does the Pendo SDK work?

The SDK automatically collects page views, feature clicks, time on page, time on app, etc.
The SDK detects UI changes: scrolling, clicks, and changes in the view hierarchy of the visible screen (Activity/fragments/UIViewControllers).
In iOS, real-time identification of page views and clicks is fulfilled by swizzling, the process of changing the implementation of an existing selector at runtime.
The SDK reports on page views/feature clicks.
Each time the SDK detects a new page or button it checks whether there is a guide that should be activated on that page/button.

Android Page Identification

Pendo identifies a page by the visible fragments and the current activity hosting them, and the hierarchy between them
Additional hints like selected tab and text (in TabLayouts), selected page (ViewPager), and select title (BottomNavigationView) are also used
Users can assign a UI label as a 'custom identifier' to a page to distinguish between pages with a similar structure. This can be done by users under the 'Page Rules' tab (under 'Manage Page'). In order to achieve this, Pendo uses page texts (fully hashed). This can be turned off but might hamper the page identification.
Tip: Try adding custom identifiers to the page when it has the same analytics data as a different page (if you're seeing the same number of page views/visitors/accounts).
If the 'page rule' is still not specific enough, our Support team can help fine-tune it.

iOS Page Identification

Pendo identifies a page in iOS by the comprising UIViewControllers and their hierarchy.
Other hints, like the index of a selected tab, are also used.
If the page has a title, the title is included in the Page rule by default and can be removed by the end-user in the 'Page rules' tab of this page.

Tip: Try removing the title when you're seeing too little data for that page.
Users can assign a UI label as a 'custom identifier' to a page to distinguish between pages with a similar structure. This can be done by users under the 'Page Rules' tab. In order to achieve this, Pendo uses page texts (fully hashed). This can be turned off but might hamper the page identification.
Tip: Try adding custom identifiers to the page when it has the same analytics data as a different page (if you're seeing the same number of page views/visitors/accounts).
If the 'page rule' is still not specific enough, our Support team can help fine-tune it.

Feature Identification

Pendo identifies any element that has a click handler as clickable.
Pendo uses many pieces of data to identify features - text, accessibility, class name, action, index in the list, or index in the parent.
A default 'feature rule' is created using this information.
Sometimes, this rule might be too narrow or too wide. You can ask our Support team to alter the rule and fine-tune it to your needs. In the future, we'll also enable more control for end-users to determine which attributes are included in the feature rule.
iOS SDK 2.6+ also identifies views implemented with gestures as clickable.

Feature Options

The following attributes are available for a tagged feature:

Include/Exclude text - if the button's text is dynamic, you can exclude it from the feature rule. Note that removing the text removes a very important hint and so should be used only if really necessary.
Include any element in the list - if you want to capture clicks regardless of the position in the list. In this case, we ignore the button's text. If needed, our Support team can add back the text.
App wide - capture clicks regardless of the page this feature is on, for global features (i.e. tabs)

Through Support, you can set more fine-grained rules such as "anywhere on the list with this text".

Setting up a code-based solution for Mobile Tagging

Our code-based solution solves problems for when Pendo does not always recognize a feature in your apps.

To set up a code-based solution:

For native applications:

For iOS Use`enableClickAnalytics` API to mark a feature as taggable and collect its analytics.
For Android, make sure the feature's property is `clickable:true, as Pendo’s UI only allows tagging on clickable views. If you've tagged a feature but you aren’t getting any analytics for it, use `sendClickAnalytic` API to fix this.

Once features have been tagged in this way, you must install that app version on your device and tag the page or update an existing one.

For React Native applications:

To mark any element as clickable, the “nativeID“ property is used.

<Image
    nativeID="pendoClickableImage"
    source={require('../../../assets/icons/react_native.png')}
    style={{resizeMode: 'contain', width: 100, height: 100, alignSelf: 'center'}}
    onTouchEnd={()=> { Alert.alert("Wohoo I love react native");}}
/>

The “nativeID“ must match the regex template. The default one is 'pendoClickable' as a prefix for “nativeID“ and does not require any setup. For any other Regex template, if the customer already has defined“nativeID“s, their developer configures Regex as follows:
- For React Native Navigation lib via navigationOptions.clickableElementsNativeIDsRegex:

const navigationOptions = {library: NavigationLibraryType.ReactNativeNavigation, navigation: Navigation, clickableElementsNativeIDsRegex: '^clickable|^pendo_|customRegex'};
PendoSDK.setup(pendoKey, navigationOptions, options);

- For React Navigation lib via traversalOptionsObject.clickableElementsNativeIDsRegex:

let traversalOptionsObject: RNTraverseOptions = {clickableElementsNativeIDsRegex: '^clickable|^pendo_|...'};

export default withPendoRN(RootNavigator, traversalOptionsObject);

If a customer configures Regex on their own, they must make sure that all regex templates are included the default template, are included 'pendoClickable' i.e clickableElementsNativeIDsRegex: '^clickable|^pendoClickable|customRegex'
If the click analytic is not generated after marking the element, the developer needs to call to “sendClickAnalytics“ API and pass the “nativeID“ as a parameter. Our native SDK then finds this view in a layout hierarchy to gather element info and send its analytics.

onTouchEnd={()=> {
  Alert.alert("Wohoo I love react native");
  PendoSDK.sendClickAnalytic("pendoClickableImage")
}

Note: Analytics are not retroactive when using the API. Data is collected only after using this API (similar to a track event).

Example - Send track event with properties

let traversalOptionsObject: RNTraverseOptions = {clickableElementsNativeIDsRegex: '^clickable|^pendo_|...'};

const PendoNavigationContainer = WithPendoReactNavigation(PendoNavigationContainer, traversalOptionsObject)
   <PendoNavigationContainer> 
   {/* Rest of your app code */} 
   </PendoNavigationContainer>