Automatic screen name tracking with Instana for mobile apps
In the realm of observability tools, identifying screen names is crucial, especially when continuous monitoring is involved. Screen name data serves various purposes in observability, such as pinpointing the exact screen where an error occurred, analyzing user traffic on different screens, understanding user flows within the app, and much more.
Traditionally, observability platforms provide APIs for manual interception and instrumentation of applications. Developers had to manually add API calls and custom names for each page, often aligning screen names with the names of the files that contain the respective screens. However, this process consumes significant developer effort and time, especially when screens are changed, or added — a common scenario in application development.
Instana operated under a similar mechanism, requiring developers to expose APIs and instrument applications to capture screen names.
Instana.view = “Some name”Many observability tools also support automatic screen name capture. With this approach, developers need to enable the API only once, and the rest is taken care of automatically. Screen names are collected from class names or file names and sent to the backend as active screens.
A new update on Instana iOS and Android agents adds the ability to capture screen names automatically. With this update, developers can enable this feature, and the rest is seamless. Instana now searches various places for meaningful screen names on every platform.
Enabling auto-capture on the Android Agent
To enable auto-capture of screen names on the Instana Android agent, set the InstanaConfiguration parameter autoCaptureScreenNames to true. By default, this mechanism is disabled to support manual screen name capture using Instana.view. With auto-capture enabled, developers no longer need the legacy API, but it remains available if needed.
Note: Currently, the agent supports Activity and Fragment-based UI approaches.
With auto-capture enabled, Instana automatically tracks loaded Activities and Fragments. Here’s how it works:
Processing names from the Activity class
For meaningful names from the Activity classes, Instana first checks content descriptions assigned to the root layout. If no content descriptions are found, it uses the Activity class name. If a meaningful name is found in the content descriptions, it uses that as the screen name.
Metadata collected for Activity classes includes:
// Class name of the activity loaded to the screen.
ACTIVITY_CLASS_NAME("act.class.name"):// Local path from the root to the loaded class.
ACTIVITY_LOCAL_PATH_NAME("act.local.path.name"):// Screen name collected based on the mentioned conditions.
ACTIVITY_SCREEN_NAME("act.screen.name"):/**This is the time when the onResume() lifecycle method is called
* for activity, (Note: as this is collected in nano time, you
* might get to see a minimal deviation from the actual one) */
ACTIVITY_RESUME_TIME("act.resume.time"):Processing names from Fragments
An activity can host one or more Fragments at a time. For Fragments, Instana searches several locations for meaningful names. It first checks the navController for a label, then the tag of the Fragment, and finally the content description of the root layout. If no names are found, it uses the Fragment class name as the screen name.
Metadata collected for Fragments includes:
// Class name of the active fragment.
FRAGMENT_CLASS_NAME("frag.class.name"):// Local path from the root to the loaded class.
FRAGMENT_LOCAL_PATH_NAME("frag.local.path.name"):// Screen name collected based on the mentioned conditions.
FRAGMENT_SCREEN_NAME("frag.screen.name"):// **(detailed explanation below) List of active fragments visible to the user.
FRAGMENT_ACTIVE_SCREENS_LIST("frag.active.screen.list"):// Time when the onResume() lifecycle method is called.
FRAGMENT_RESUME_TIME("frag.resume.time"):FRAGMENT_ACTIVE_SCREENS_LIST
This metadata in Fragment provides crucial insights into the active fragments within a single activity of your Android app. This attribute lists the fragments that are visible to the user at any given moment in an Activity.
Let’s dive into how this works. Imagine your application has three fragments — FragmentA, FragmentB, and FragmentC — all housed within the same activity and visible simultaneously. Although these fragments appear at once to the user, they load sequentially. This sequential loading plays a significant role in how Instana tracks and reports active screens.
Here’s a breakdown:
- When FragmentA loads, FRAGMENT_ACTIVE_SCREENS_LIST will only list [FragmentA].
- As FragmentB loads next, the list updates to include both fragments, shown as [FragmentA, FragmentB].
- Finally, when FragmentC loads, the list fully populates to [FragmentA, FragmentB, FragmentC], reflecting all three fragments currently interacting with the user.
By leveraging these new features provided by Instana, developers can gain deeper insights into user interactions and instrument their apps to observe real-time user experiences.
Reference Links:
