Events & Screen Tracking

Tracking custom events

Use track to record an event with optional properties and tags:

import Grovs from 'react-native-grovs-wrapper';
 
Grovs.track('checkout_completed', { sku: 'abc', total: 42 }, ['shop']);
Grovs.track('level_complete', { level: 5, score: 1200 });
Grovs.track('button_tap');

The call is forwarded to the native SDK, which validates, stores, and batches the event. Events are sent in batches, kept on the device until they are delivered, and held during install attribution so they are credited to the right link. The details are the native SDK's; see the Android and iOS pages.

Event name rules

An event name must not be empty and must not be one of the reserved system event names:

view, open, install, reinstall, app_open, time_spent, reactivation, user_referred, custom, screen_view

Rejected events are logged natively and dropped. track itself does not throw. Use trackScreenView for screen views rather than track('screen_view').

Property values

Properties are typed as { [key: string]: Any }, where Any is a string, number, boolean, or a flat array of those. Nested objects, null, and Date values are not part of the type. Values reach the native SDK as native types, so the native limits apply: properties that serialize to more than 8 KB are dropped as a whole, and the event is still recorded. On Android, values the bridge cannot represent as Serializable are dropped.

Tags

Tags are strings, capped natively at 20 per event with up to 255 characters each. Set global tags to attach them to every subsequent event:

Grovs.setGlobalTags(['beta', 'experiment-A']);
 
Grovs.setGlobalTags(); // clear

Global tags are merged with per-event tags, up to the combined cap of 20.

Tracking screen views

Grovs.trackScreenView('Checkout', { section: 'payment' });

If the same screen name is sent twice within one second the duplicate is dropped natively, which keeps a transient re-render or a quick tab switch from flooding the dashboard. The window does not deduplicate a genuine return to the same screen later.

Automatic screen tracking with React Navigation

The wrapper can subscribe to a React Navigation container and report every route change as a screen view. Pass the container ref from onReady:

import { NavigationContainer, useNavigationContainerRef } from '@react-navigation/native';
import Grovs from 'react-native-grovs-wrapper';
 
function App() {
  const navigationRef = useNavigationContainerRef();
 
  return (
    <NavigationContainer
      ref={navigationRef}
      onReady={() => Grovs.startScreenTracking(navigationRef)}>
      {/* navigators */}
    </NavigationContainer>
  );
}

startScreenTracking reports the current route immediately, then listens for state events and reports each route whose name differs from the previous one. Navigating away and back reports the screen again. The screen name is the route name React Navigation returns from getCurrentRoute(); use aliases to rename them in the dashboard.

The method returns an unsubscribe function. Calling startScreenTracking again replaces the previous subscription, so screens are never double-tracked when onReady fires again after a container remount. A ref without getCurrentRoute and addListener is rejected with a logged error and a no-op unsubscribe.

The wrapper has no dependency on @react-navigation/native. It accepts any object matching NavigationContainerRefLike:

interface NavigationContainerRefLike {
  getCurrentRoute(): { name: string } | undefined;
  addListener(type: 'state', callback: () => void): () => void;
}

A ref created with createNavigationContainerRef() works the same way as one from the hook.

Expo Router and other navigators

For Expo Router or a custom navigation solution, call trackScreenView yourself whenever the visible screen changes:

Grovs.trackScreenView('Checkout');

Turn off native automatic screen tracking

The native SDKs' own automatic screen tracking, on by default in 3.0, only sees the single Activity or view controller that hosts React Native, so it cannot report individual React Native screens. Pass autoTrackScreenViews: false in the native configure calls, as shown in the Quick Start, and track screens from JavaScript instead. The Expo config plugin injects this for you; if you are upgrading an existing Expo project, re-run npx expo prebuild --clean so the new configure line is generated.

Screen name aliases

Map the screen names you report to friendlier names in the dashboard:

Grovs.setScreenAliases({ Home: 'Home Page', ProductDetail: 'Product' });

Keys are the names you pass to trackScreenView or that startScreenTracking reads from your routes. Only string values are forwarded. Aliases are synced to the backend natively after authentication, and held while the SDK is disabled.

What the wrapper does not expose

The Android trackNavigation(navController) API and the iOS screenNameProvider and .grovsScreen() modifier are for native UI and have no React Native equivalent. Use startScreenTracking or trackScreenView instead.

Next steps

• Track revenue and purchases →
• Gate collection on consent →
• Full API reference →