# 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.

{% tabs %}
{% tab title="Expo" %}

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

{% endtab %}

{% tab title="React Native CLI" %}

```
npm install --save @freshpaint/freshpaint-react-native
npm install --save @react-native-async-storage/async-storage
npx react-native link @react-native-async-storage/async-storage
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
For iOS projects, run `pod install` after installing the SDK. The SDK includes native modules for attribution and install-related data collection.
{% endhint %}

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`:

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

{% hint style="info" %}
Restart Metro with a cleared cache and rebuild the app so Babel instrumentation is applied.
{% endhint %}

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.

```javascript
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:

{% tabs %}
{% tab title="Expo" %}

```bash
expo r -c
```

Then restart the expo app on your phone.
{% endtab %}

{% tab title="React Native CLI" %}

```
npx react-native start --reset-cache
```

{% endtab %}
{% endtabs %}

After that Freshpaint will automatically collect the following actions:

* Touches and presses
* Text input edits
* Switch toggles
* Paged ScrollView interactions

{% hint style="warning" %}
Text input autocapture support depends on the React Native/TextInput implementation used by your app.
{% endhint %}

## 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](https://documentation.freshpaint.io/sources/server-side).

## 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`:

```javascript
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`:

```javascript
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`:

```javascript
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:

```javascript
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](https://app.freshpaint.io/events/liveview). As you navigate around your app and click on various buttons, you should see events show up in the Live View:

![](/files/-MH8O2GLGYuBQ-G0zQ1A)

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:

![](/files/-MH8OdkeLx_RV4GMGM0j)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://documentation.freshpaint.io/readme/guides/react-native-quickstart-guide/installing-the-freshpaint-react-native-sdk.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.