Expo Router

Expo Router manages navigation differently from bare React Navigation — it owns the NavigationContainer internally. Use useNavigationContainerRef from expo-router instead of creating your own ref, and pass registerWhenContainerReady: true so Pulse hooks in when the container is ready without needing an onReady callback.

Setup

import { Stack, useNavigationContainerRef } from 'expo-router';
import { Pulse } from '@dreamhorizonorg/pulse-react-native';

function Root() {
    const navigationRef = useNavigationContainerRef();

    Pulse.useNavigationTracking(navigationRef, {
        registerWhenContainerReady: true,
    });

    return <Stack />;
}

The registerWhenContainerReady: true option tells Pulse to wait until the container is mounted before attaching listeners — no manual onReady wiring needed.

What gets tracked

Once connected, Pulse tracks three metrics per screen automatically:

Metric	What it measures	Default
Screen Load	Navigation start → screen displayed	On
Screen Session	Screen in focus → user navigates away	On
Screen Interactive	Screen displayed → your content is ready	Off (opt-in)

Configure individual metrics

Pulse.useNavigationTracking(navigationRef, {
    registerWhenContainerReady:  true,
    screenSessionTracking:       true,   // default: on
    screenNavigationTracking:    true,   // default: on
    screenInteractiveTracking:   false,  // default: off
});

Screen Interactive Tracking

Opt-in. Measures time from screen display to when your content is actually usable. Enable it, then call markContentReady() when your data has loaded:

Pulse.useNavigationTracking(navigationRef, {
    registerWhenContainerReady: true,
    screenInteractiveTracking:  true,
});

// In your screen — call when meaningful content is ready
function HomeScreen() {
    useEffect(() => {
        fetchData().then(() => {
            Pulse.markContentReady();
        });
    }, []);
}

If the user navigates away before markContentReady() is called, the span is discarded. See Navigation Instrumentation for guidance on when to call it.

Difference from Bare React Native

	Bare React Native	Expo Router
Ref	React.useRef<NavigationContainerRef>	useNavigationContainerRef() from expo-router
Hook option	—	registerWhenContainerReady: true
onReady callback	Pass to <NavigationContainer onReady={onReady}>	Not needed

Next Steps

• Plugin Reference — Full app.json options
• Navigation Instrumentation — Full attributes reference, greenfield tip, Marco integration