Tag Screen Name

🚧

Important

Please keep in mind if an already tagged screen has an updated name, this will generate a new screenshot in the Heatmaps section.

UXCam captures the Screen (view controller/activity) name automatically. However, there are some cases where you will need to manually tag your screens to ensure you have them separately in your recordings and heatmaps.

Use our API to tag screens if you:

  • Have one or more fragments inside an Android activity, and you need to tag fragment name instead of an activity.
  • Use SwiftUI, Flutter, React Native or Cordova, where the application usually runs within a single activity or controller.
  • Want to define which views or activities should be considered screens or want to define different names.
  • Use OpenGL or have a game where the screens are dynamically shown.

Tag Screen Name

👍

iOS Recommendation

After improvements made on iOS SDK version 3.5.1, to manually tag screens along with automatic tagging at the same time, UXCam.tagScreenName should be called in viewWillAppear method of your screens.

UXCam.tagScreenName(_ screenName: String)

//Example  
override open func viewWillAppear(_ animated: Bool) {
      super.viewWillAppear(animated)
      UXCam.tagScreenName("Home Screen Manual")
}
UXCam.tagScreenName(String screenName);
RNUxcam.tagScreenName: (screenName: string) => void
void tagScreenName(String screenName)
uxcamTagScreenName(_ screenName: String) -> some View

//eg. 
var body: some View
{
    Text("Hello world")
        .uxcamTagScreenName("HelloScreen")
}
void UXCam.TagScreenName(string screenName)
UXCam.tagScreenName: (screenName: string) => void
NSUXCam.tagScreenName: (screenName: string) => void

📘

The API parameters are:
screenName: A String with name for the screen as required.


Control Automatic Tagging

📘

Note: Cross-platform frameworks often have inconsistent view controller/activity naming; it is recommended to manually tag your screens if you're using such frameworks.

By default, automatic screen name tagging is set to true, so to enable or disable the automatic screen tagging you should do so from the configuration object at SDK startup:

let configuration = UXCamConfiguration(appKey: "YourAppKey")

//Example      
configuration.enableAutomaticScreenNameTagging = true // call it False in order to disable the Automatic Screen taggin
UXConfig config = new UXConfig.Builder('yourAppKey')
    .enableAutomaticScreenNameTagging(true) // call it False in order to disable the Automatic Screen tagging
    .enableImprovedScreenCapture(true)
    .build()
FlutterUxConfig config = FlutterUxConfig(
      userAppKey: "UXCAM_APP_KEY",
      enableAutomaticScreenNameTagging: false);
   
const configuration = {
    userAppKey: 'YOUR API KEY',
    enableAutomaticScreenNameTagging: false,
    enableImprovedScreenCapture: true
 }
const configuration = {
    userAppKey: 'YOUR API KEY',
    enableAutomaticScreenNameTagging:false, // default is true
    enableImprovedScreenCapture:true,
}
UXCamConfiguration configuration = new UXCamConfiguration(
     userAppKey: ‘userAppKey’,
     enableImprovedScreenCapture: true,
     enableAutomaticScreenNameTagging:false, //default is true
);

Flutter Tagging Approach:

🚧

Important:

Flutter SDK version 2.2.2 enables the option to add tagging from the Flutter side of your app. This is an optional feature that will be still improved upon, so please do provide any feedback you may have when testing.

This feature does not currently support Bottom Navigation or Tab Navigation for the tagging if using Navigator 1.0 or 2.0, however there is ongoing work on Navigator 2.0 that will tackle similar issues in the near future.

From the FlutterUXCam SDK version 2.2.2 you'll have now the option to add a FlutterUxcamNavigatorObserver to your app, which will enable capturing your routes (screens) for screen Tagging without having to manually tag them.

Follow the below steps to add this to your app:

  1. Inside your dart file import flutter_uxcam_observer like this:
import 'package:flutter_uxcam/flutter_uxcam_observer.dart';
  1. Make sure the config parameter enableAutomaticScreenNameTagging is set as false
  2. Add the observer:
  • If using Navigator 1.0:
MaterialApp(
   ...
   navigatorObservers: [
     FlutterUxcamNavigatorObserver(), 
   ],
   ...
 )
  • If using Navigator 2.0:

Add it to the observers for your Router.

(The below example is using GoRouter)

final GoRouter router = GoRouter(
    ...
 observers: [
    FlutterUxcamNavigatorObserver(),
 ],
    ...
)
  1. It is suggested you add names to your routes, otherwise some routes may show as default, i.e '/ '
GoRoute(
  path: {routeName},
  name: {Preferred Route Name},
  builder: (BuildContext context, GoRouterState state) {
    return ScreenName(key: state.pageKey);
  },
),

Scrolling Screens Examples:

📘

For screens that scroll:

  • Tag screen name as usual - you can find an instruction above
    • When a user scrolls to 800 points - change the screen name using our tag API. The scroll area is calculated by default UIKit methods - it should be one of the “scroll view delegate methods”
    • The same follows for the third section 800*2 = 1600. Once a user scrolls to 1600, change to the 3rd screen name.
    • When users scroll up, the same calculation can be applied.

The biggest challenge that can appear is if users have both section 1 and some part of section 2 visible (it can usually happen on big iPad screens for apps not optimised for iPads). However, if it’s not the case for your app, you can go ahead and use this workaround for the long screens.


What’s Next