Installing the Freshpaint React Native SDK

Getting Started

The first step installing the Freshpaint React Native SDK is to install the @freshpaint/freshpaint-react-native node module. If you are not using Expo and are using the React Native CLI instead, you'll also need to install and link the @react-native-community/async-storage dependency. For modern React Native projects, native dependencies are autolinked.

Expo

npx expo install --save @freshpaint/freshpaint-react-native

React Native CLI

For iOS projects, run pod install after installing the SDK. The SDK includes native modules for attribution and install-related data collection.

Next, you'll need to setup the Freshpaint React Native babel plugin. This allows Freshpaint to instrument supported React Native components during your app build. To setup the plugin, add the following bit of code to either your .babelrc or babel.config.json:

{
  plugins: [
    'add-react-displayname', 
    './node_modules/@freshpaint/freshpaint-react-native/plugin.js',
  ],
  ...
}

Restart Metro with a cleared cache and rebuild the app so Babel instrumentation is applied.

Then to initialize the Freshpaint SDK, you call freshpaint.init at the top level with your environment ID. This is normally done in the App.js file. You can get your Freshpaint environment ID from the Freshpaint sources page.

import Freshpaint from '@freshpaint/freshpaint-react-native';

Freshpaint.init('<your environment id>');

At this point you'll need to clear any build caches for your app:

Expo

expo r -c

Then restart the expo app on your phone.

React Native CLI

After that Freshpaint will automatically collect the following actions:

• Touches and presses

• Text input edits

• Switch toggles

• Paged ScrollView interactions

Text input autocapture support depends on the React Native/TextInput implementation used by your app.

How it Works

Generally, the React-Native integration works by sending the data to Freshpaint, which then captures that data and sends the data to your destination. The data is sent from Freshpaint to your destination server-side, even if your app destination is configured to be client-side. You can read more about server-side and client-side connection modes here.

Capturing Screen Views

If you are using React Navigation, Freshpaint can also autocapture screen views. To set this up, wrap the NavigationContainer provided by React Navigation with Freshpaint.withReactNavigationAutotrack:

import Freshpaint from '@freshpaint/freshpaint-react-native';
import { NavigationContainer } from '@react-navigation/native';

const FreshpaintNavigationContainer = Freshpaint.withReactNavigationAutotrack(NavigationContainer);

Then use FreshpaintNavigationContainer in place of NavigationContainer:

function App() {
  return (
    <FreshpaintNavigationContainer>
      ...
    </FreshpaintNavigationContainer>
  );
}

Deep Link Tracking

Freshpaint automatically listens for deep links after Freshpaint.init(...). When the app is opened from a deep link, the SDK sends a Deep Link Opened event with the opened URL and supported attribution parameters.

You still need to configure deep linking in your app, such as URL schemes, Universal Links, Android App Links, or Expo linking configuration. Freshpaint does not route users inside your app; it observes URLs received through React Native’s Linking API.

Supported attribution parameters include UTM parameters and common ad click IDs such as gclid, gbraid, wbraid, fbclid, ttclid, and msclkid. The initial launch URL may also contribute attribution properties to the one-time Application Installed event.

User Consent and Ad Tracking

The React Native SDK respects platform-level ad tracking controls.On iOS, the SDK supports App Tracking Transparency (ATT). By default, Freshpaint does not automatically show the ATT prompt. To let the SDK request ATT during initialization, pass autoRequestATT: true:

Freshpaint.init('YOUR_ENVIRONMENT_ID', {autoRequestATT: true,});

When autoRequestATT is enabled, Freshpaint requests ATT before sending the one-time Application Installed event. If the user authorizes tracking, attribution events may include the advertising identifier. If tracking is denied or restricted, the advertising identifier is not included.

Apps that manage their own consent flow can leave autoRequestATT disabled and call the ATT methods directly:

const status = await Freshpaint.getTrackingAuthorizationStatus();
const updatedStatus = await Freshpaint.requestTrackingAuthorization();

On Android, Freshpaint respects the device’s Limit Ad Tracking setting. When ad tracking is limited, advertising identifiers are not collected. When ad tracking is allowed, Freshpaint uses the Google Advertising ID when available and avoids sending both GAID and Android ID together.

Freshpaint’s ad tracking behavior is based on platform-level controls. If your app has its own privacy consent flow, coordinate SDK initialization and ATT prompting with that flow.

Verifying your Instrumentation

To verify your Freshpaint instrumentation, navigate to the Freshpaint Live View. As you navigate around your app and click on various buttons, you should see events show up in the Live View:

You can click one of the events to dig into the specific properties captured. For example, you can see the full React component hierarchy of the captured event: