Guides
Guides

Tagging Screens

Good screen names turn raw replays into actionable heat-maps, screen analytics, conversion funnels and journey charts. This guide walks you through choosing a tagging approach, implementing it, and verifying that every screen shows up with a meaningful duration.

Automatic vs Manual Tagging

Tagging MethodReact Native SupportRecommendation
Automatic Screen Tagging❌ Not reliable — React Native navigation doesn't expose native screen changesNot recommended
Manual Screen Tagging✅ Fully supported and reliableStrongly recommended
⚠️

Important: For React Native, manual tagging is strongly recommended. Unlike native iOS/Android apps, React Native screens are JavaScript-based and don't trigger native screen lifecycle events that automatic tagging depends on.

const configuration = {
  userAppKey: 'YOUR_API_KEY',
  enableAutomaticScreenNameTagging: false, // Manual control recommended
  enableImprovedScreenCapture: true,
};

Basic Screen Tagging

Tag screens using RNUxcam.tagScreenName():

import RNUxcam from 'react-native-ux-cam';

// ✅ Good screen names — descriptive and human-readable
RNUxcam.tagScreenName('Home Dashboard');
RNUxcam.tagScreenName('Product Details');
RNUxcam.tagScreenName('Checkout Payment');

// ❌ Avoid technical names
RNUxcam.tagScreenName('HomeComponent');
RNUxcam.tagScreenName('Screen1');

Naming tips:

  • Use descriptive, human-readable names
  • Keep names consistent across similar screens
  • Consider how names appear in analytics dashboards

Centralized Screen Tagging Hook

Create a reusable hook for consistent tagging across your app:

import { useFocusEffect } from '@react-navigation/native';
import RNUxcam from 'react-native-ux-cam';
import { useCallback } from 'react';

export const useScreenTracking = (screenName) => {
  useFocusEffect(
    useCallback(() => {
      if (screenName) {
        RNUxcam.tagScreenName(screenName);
      }
    }, [screenName])
  );
};

// Usage in any screen
function ProductScreen() {
  useScreenTracking('Product Details');
  return (/* Screen content */);
}

Expo Router Integration

import { useSegments } from 'expo-router';
import { useEffect } from 'react';
import RNUxcam from 'react-native-ux-cam';

export default function RootLayout() {
  const segments = useSegments();

  useEffect(() => {
    if (segments.length > 0) {
      const screenName = segments
        .filter(s => !s.startsWith('('))
        .join(' - ') || 'Home';
      RNUxcam.tagScreenName(screenName);
    }
  }, [segments]);

  return (/* Layout content */);
}

Verify Your Tags

  1. In Debug, navigate through every tagged screen, then background the app.
  2. Once the session uploads, confirm:
    • Each screen appears exactly once with duration > 0 s
    • No "Unknown" or class-name entries remain
    • Names match your analytics terminology
  3. Fix any issues by removing duplicate calls or adding a missing tag handler.

A solid screen-naming strategy makes PII masking and heat-map analysis far easier later on.

Troubleshooting Cheat-Sheet

IssueQuick DiagnosisSolution
0 s screensDuplicate tag same frameDebounce manual call or check re-renders
Screen missingNavigation path not handledAdd useScreenTracking() to the screen
Generic namesUsing auto-taggingSet enableAutomaticScreenNameTagging: false
Rapid duplicatesTab switching < 300 msAdd debounce to tag logic

Next Steps

React Navigation & Wix

Full integration guides for React Navigation v6, tab navigators, and Wix/React Native Navigation.

WebView Tagging

Tag screens inside WebViews using URL changes and JavaScript bridges.

Mask PII Data

Protect your users' privacy — mask or blur screens, views and fields.

Updated 13 days ago