In this guide, you'll learn how to install and use the Activity Flow SDK in React Native apps for Android and iOS. By following these steps, you'll be able to track user navigation, order events, deep links, and ad events in your app.

In your app's main file (for example, App.js or App.tsx), import the plugin as follows:

Set the account name to create an instance of the main package class:

To track navigation state changes, integrate the usePageViewObserver hook with the NavigationContainer, the root component of React Navigation, in your app's main file. To do so, follow these steps:

1. Import the observer hook:

   
   

   _10

   import { usePageViewObserver } from '@vtex/activity-flow';

   
   

2. Create a reference for the NavigationContainer:

   
   

   _10

   const navigationRef = useRef(null);

   
   

3. Pass the reference to NavigationContainer:

   
   

   _10

   <NavigationContainer ref={navigationRef}>

   _10

   {/* Stack configurations */}

   _10

   </NavigationContainer>

   
   

4. Use the observer hook to track page views:

Activity Flow now automatically tracks page transitions. When you navigate between screens, it records each page view and sends event data.

The Activity Flow SDK can automatically capture order details from navigation parameters, such as orderGroup or orderPlaced, and any query parameters from the navigator stack. These parameters help validate checkout events and confirm successful purchases.

To enable this feature, include the required parameter in your page redirect configuration. See the example below:

When a user completes a purchase, Activity Flow automatically captures orderGroup and other query parameters during the screen transition.

The Activity Flow SDK automatically captures deep-link query parameters from the usePageViewObserver hook and includes them in page view events. To enable this feature, configure deep linking in your app according to its platform: Android or iOS.

Android

To enable deep-link handling in your Android app, add intent filters to the AndroidManifest.xml file for each route that can be accessed via a deep link. See the example below:

This AndroidManifest adds two intent filters for deep linking:

• One for HTTPS URLs starting with "https://example.com/{APP_ROUTE}".
• One for a custom scheme "{YOUR_CUSTOM_SCHEME}". Both use action.VIEW, category_DEFAULT, and category_BROWSABLE, allowing the Activity Flow to launch from browsers or other apps. The data tag for deep link via HTTP specifies the scheme, host, and an optional pathPrefix, matching any path that begins with that prefix (for example, "/products/42" if {APP_ROUTE} is "/products"). The main difference between intent filters for different routes is the android:pathPrefix attribute, which specifies the app route. For a deep link via a custom scheme, the data tag sets the scheme, matching any URL that starts with that scheme (for example, myapp://... if {YOUR_CUSTOM_SCHEME} is myapp).

iOS

To enable deep-link handling in your iOS app, add your URL scheme to the Info.plist file and handle incoming URLs in the AppDelegate file:

1. Register your custom URL scheme by adding the following configuration to your Info.plist file:

In the info.plist configuration, {YOUR_BUNDLE_URL_SCHEME} is the custom URL scheme your app will handle, that is, the prefix before :// in deep links. For example, setting it to myapp makes links like myapp://path open your app. Enter only the scheme name, without ://. The {YOUR_BUNDLE_URL_NAME} label is a unique identifier for this URL type entry, typically in reverse-DNS format, used to distinguish the configuration and doesn't affect routing. For example, com.example.appname.

2. Handle incoming deep links by modifying your AppDelegate.swift (or AppDelegate.mm) file. The following example handles deep links for cold starts, when the app isn't running, and warm starts, when the app is already running.

Your Android app can now be launched from both web links (https://mystore.com/products/42) and custom scheme links: (myapp://products/42).

Ad tracking is available only for accounts that use VTEX Ads. If you're interested in this feature, open a ticket with VTEX Support.

To configure ad tracking, follow these steps:

1. Create the ad object

To track events, provide an object containing all information relevant to the ad event. The accountName field is mandatory.

2. Integrate the ad tracker into your components

There are two methods to integrate the ad tracker into your components: Using the AFAdsTracker Wrapper component or using the useAdsTracker hook.

Using the AFAdsTracker wrapper component

To track ad events with the AFAdsTracker, wrap your ad component with it and provide the necessary tracking parameters. The wrapper will automatically manage all required event handlers.

Use this method when your entire child component represents a clickable ad. See the example below:

The example below shows a React Native app that uses @vtex/activity-flow with React Navigation to track navigation across multiple screens and ad events from a single location.

The app initializes tracking via initActivityFlow with your VTEX account name, and enables automatic page view tracking by calling usePageViewObserver with a NavigationContainer ref.

On the Ads screen, ad parameters (including the required accountName) are passed to the AFAdsTracker wrapper, which wraps a fully clickable child to automatically fire impression, view, and click events without manual handler wiring.

The wrapper detects clicks via onTouchEndCapture. If your ad interaction isn't based on it or can't be wrapped, use the useAdsTracker hook instead.

To use this example in your project, remember to replace accountName based on your scenario.

Using the useAdsTracker hook

The useAdsTracker hook provides more control over how events are attached. It returns handlers and a ref that you must apply manually to your components.

Use this method when:

• You can't use an extra <View> to wrap your component.
• The component that receives events (for example, a TouchableOpacity) is different from the component that defines the visibility area.
• You integrate with third-party component libraries that don’t allow a generic wrapper.
• The click property isn't onTouchEnd, since the AFAdsTracker wrapper uses onTouchEndCapture.

Follow the steps below to use this hook:

1. Import and call the hook:

2. Attach the handlers and ref to your component. See the example below:

The hook returns an object with three properties:

• handleLayout: A function to be passed to your component's onLayout prop. It fires the impression event.
• handlePress: A function to be passed to a touch prop, like onPress or onTouchEndCapture. It fires the click event.
• viewRef: A ref that must be attached to the ref prop of the ad's main component. It monitors visibility and fires the view event.

Below is an implementation example of a React Native code that defines a CustomAd component. This component uses the useAdsTracker hook from the @vtex/activity-flow library to integrate with an ad tracking system for visibility and interaction.

The component's purpose is to render an ad inside a touchable container and report three key events to the tracking system: impression, view, and click.