# Freshpaint React Native SDK Reference

## track <a href="#track" id="track"></a>

The `track` call can be used to manually send data to your destinations. See the docs on [manually tracking events in Freshpaint](https://www.freshpaint.io/docs/manual-event-tracking-in-freshpaint) for more information.

```javascript
Freshpaint.track("Purchase", {"price": 500});
```

| Argument       | Type     | Required | Description                                                                                                     |
| -------------- | -------- | -------- | --------------------------------------------------------------------------------------------------------------- |
| **Event Name** | `String` | Yes      | The name of the event you want to send to Freshpaint.                                                           |
| **Properties** | `Object` | No       | A JSON object of properties you want to send along with the event.                                              |
| **options**    | `Object` | No       | Options object containing `integrations` for [per-call destination filtering](#per-call-destination-filtering). |

## identify <a href="#identify" id="identify"></a>

The `identify` call can used to attach user properties the current user. Destinations will then use that data to create a single profile for that user, even if data for that user comes from multiple places. See the [identify docs](https://www.freshpaint.io/docs/identify-user-identities) for more information.

```javascript
// Associate all future events sent from
// the library with the distinct_id ada.lovelace@example.com
Freshpaint.identify("ada.lovelace@example.com", { 
  "email": "ada.lovelace@example.com", 
  "name": "Ada Lovelace"
});‌
```

The properties argument is optional. If you want to only attach a unique identifier to the user, you can call identify like so:

```javascript
Freshpaint.identify("ada.lovelace@example.com");
```

Likewise, the identifier is also optional. If you only want to attach properties to the user without attaching an identifier, you can perform a call like the following:

```javascript
Freshpaint.identify({ 
  "email": "ada.lovelace@example.com", 
  "name": "Ada Lovelace"
});
```

| Argument       | Type     | Required | Description                                                                                                     |
| -------------- | -------- | -------- | --------------------------------------------------------------------------------------------------------------- |
| **unique\_id** | `String` | No       | A string that uniquely identifies a user (such as email address).                                               |
| **properties** | `Object` | No       | A JSON object of user properties to send to the destinations.                                                   |
| **options**    | `Object` | No       | Options object containing `integrations` for [per-call destination filtering](#per-call-destination-filtering). |

## group <a href="#reset" id="reset"></a>

The `group` call will add the given user to a group and attach the provided properties to the group. The call

```javascript
freshpaint.group("Google", {
  "plan": "enterprise",
  "sign-up-date": "04/01/2019"
});
```

will add the current user to the "Google" group and attach the provided properties to the group.

| Argument       | Type     | Required | Description                                                                                                     |
| -------------- | -------- | -------- | --------------------------------------------------------------------------------------------------------------- |
| **unique\_id** | `String` | No       | The ID of the group the user is being added to.                                                                 |
| **properties** | `Object` | No       | Properties to attach to the group.                                                                              |
| **options**    | `Object` | No       | Options object containing `integrations` for [per-call destination filtering](#per-call-destination-filtering). |

## reset <a href="#reset" id="reset"></a>

The `reset` call clears any local Freshpaint data attached to this user. This does not clear any local data for any of your destinations.

```javascript
Freshpaint.reset();
```

## addEventProperties <a href="#addeventproperties" id="addeventproperties"></a>

The `addEventProperties` call can be used to set data layer properties. Once a property is set through `addEventProperties` all events going forward will contain that property. The call

```javascript
Freshpaint.addEventProperties({"pricing plan": "enterprise"});
```

will include the property `pricing plan` with the value `enterprise` until either the value is overwritten or you delete the property with `removeEventProperty`. `addEventProperties` should be used to set any properties that can change.

| Argument   | Type     | Required | Description                                                               |
| ---------- | -------- | -------- | ------------------------------------------------------------------------- |
| properties | `Object` | Yes      | An object of properties and values to attach to all events going forward. |

## addInitialEventProperties

The `addInitialEventProperties` call works the same way as `addEventProperties` except if a property is already set, `addInitialEventProperties` will not override it. This is useful for when you care about the first value of some property. As an example, the call

```javascript
Freshpaint.addInitialEventProperties({"initial landing page": "/article"});
```

will set the value of the property `initial landing page` to `/article`. Even after calling `addInitialEventProperties` with a different of `initial landing page` the value of `initial landing page` will still be `/article`. `addInitialEventProperties` should be used to set properties that you never want to change.

| Argument   | Type     | Required | Description                                                               |
| ---------- | -------- | -------- | ------------------------------------------------------------------------- |
| properties | `Object` | Yes      | An object of properties and values to attach to all events going forward. |

## removeEventProperty <a href="#removeeventproperty" id="removeeventproperty"></a>

The `removeEventProperty` call can be used to remove data layer properties. Once used, freshpaint will no longer send the given property. As an example, the call:

```javascript
Freshpaint.removeEventProperty('search term');
```

will delete the current `search term` property and Freshpaint will stop sending it going forward.

| Argument | Type     | Required | Description                         |
| -------- | -------- | -------- | ----------------------------------- |
| property | `String` | Yes      | The name of the property to remove. |

## setOptOut <a href="#removeeventproperty" id="removeeventproperty"></a>

The `setOptOut` call can be used to opt the current user out of tracking.

```javascript
Freshpaint.setOptOut(true)
```

| Argument | Type    | Required | Description                                             |
| -------- | ------- | -------- | ------------------------------------------------------- |
| property | Boolean | No       | True or false to disable tracking for the current user. |

## init <a href="#removeeventproperty" id="removeeventproperty"></a>

Freshpaint's React Native SDK accepts some options in its `init` method. We'll go over these options in this section.

{% hint style="info" %}
While there are technically other `init` options that may be available, options not documented below are unsupported and may not work as intended. Use them at your own risk, and please contact <support@freshpaint.io> if there is a specific option you would like added supported for.
{% endhint %}

<table><thead><tr><th>Option</th><th width="103.73828125">Type</th><th width="192.3984375">Default</th><th>Description</th></tr></thead><tbody><tr><td><code>sessionTimeout</code></td><td>number</td><td><code>1800000 ms</code> (30 minutes)</td><td><p>The timeout for Freshpaint to start a new session, in seconds. If more than <code>sessionTimeout</code> seconds have passed since the last event was registered in an existing session, Freshpaint will start a new session and generate a new session_id.</p><h4 id="event-options"><br></h4></td></tr><tr><td><code>optOut</code></td><td>boolean</td><td><code>false</code></td><td>If true then Freshpaint will not send or log events.</td></tr></tbody></table>

## Per-Call Destination Filtering <a href="#per-call-destination-filtering" id="per-call-destination-filtering"></a>

The Freshpaint React Native SDK supports per-call destination filtering, allowing you to control which destinations receive specific events. This feature provides parity with the Web SDK's destination filtering capability.

### Overview

By default, events are sent to all destinations enabled for your project. With per-call destination filtering, you can override this behavior on a per-event basis by passing an `options` parameter with an `integrations` object.

### Usage

#### track()

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

// Send to all destinations (default behavior)
Freshpaint.track('Purchase Completed', { amount: 99.99 });

// Send only to specific destinations
Freshpaint.track('Purchase Completed', { amount: 99.99 }, {
  integrations: {
    All: false,
    Mixpanel: true,
    Amplitude: true
  }
});

// Exclude specific destinations (send to all except these)
Freshpaint.track('Purchase Completed', { amount: 99.99 }, {
  integrations: {
    Mixpanel: false,
    'Facebook Conversions API': false
  }
});

// Use destination UUID
Freshpaint.track('Purchase Completed', { amount: 99.99 }, {
  integrations: {
    All: false,
    'a1b2c3d4-e5f6-7890-abcd-ef1234567890': true
  }
});
```

#### identify()

```javascript
// Send to all destinations (default behavior)
Freshpaint.identify('user-123', { name: 'John Doe', email: 'john@example.com' });

// Send only to specific destinations
Freshpaint.identify('user-123', { name: 'John Doe' }, {
  integrations: {
    All: false,
    Mixpanel: true
  }
});

// With props only (no userId)
Freshpaint.identify({ name: 'John Doe' }, {
  integrations: {
    Mixpanel: true
  }
});
```

#### group()

```javascript
// Send to all destinations (default behavior)
Freshpaint.group('company-456', { plan: 'enterprise', employees: 500 });

// Send only to specific destinations
Freshpaint.group('company-456', { plan: 'enterprise' }, {
  integrations: {
    All: false,
    Amplitude: true
  }
});

// With props only (no groupId)
Freshpaint.group({ plan: 'enterprise' }, {
  integrations: {
    Amplitude: true
  }
});
```

### API Reference

#### Options Object

| Property       | Type     | Description                                                                  |
| -------------- | -------- | ---------------------------------------------------------------------------- |
| `integrations` | `Object` | An object where keys are destination names or UUIDs, and values are booleans |

#### Integrations Object

| Key                 | Type      | Description                                                              |
| ------------------- | --------- | ------------------------------------------------------------------------ |
| `All`               | `boolean` | When set to `false`, disables all destinations unless explicitly enabled |
| `[DestinationName]` | `boolean` | Enable (`true`) or disable (`false`) a specific destination by name      |
| `[DestinationUUID]` | `boolean` | Enable (`true`) or disable (`false`) a specific destination by its UUID  |

#### Supported Destination Names

Use the exact destination name as shown in your Freshpaint dashboard. Common examples:

* `Mixpanel`
* `Amplitude`
* `Iterable`
* `Facebook Conversions API`
* `Google Analytics 4`

{% hint style="info" %}
If you have multiple configured instances of a given destination type, you can choose a specific one with a suffix, such as: **Facebook Conversions API::0123456789012345.** The [configuration page](https://app.freshpaint.io/destinations/apps) for the instance shows the full value to use. When no suffix is specified, all configured instances of the destination type are selected for inclusion / exclusion.
{% endhint %}

### Common Patterns

#### Whitelist Pattern (Send only to specific destinations)

```javascript
Freshpaint.track('Sensitive Event', { data: 'value' }, {
  integrations: {
    All: false,           // Disable all destinations
    Amplitude: true,      // Enable only Amplitude
    Mixpanel: true        // Enable only Mixpanel
  }
});
```

#### Blacklist Pattern (Send to all except specific destinations)

```javascript
Freshpaint.track('General Event', { data: 'value' }, {
  integrations: {
    'Facebook Conversions API': false,  // Exclude Facebook
    'Google Ads': false                  // Exclude Google Ads
  }
});
```

### Notes

* If the `options` parameter is not provided or `options.integrations` is undefined, events are sent to all enabled destinations (default behavior)
* The UI setting "Override hardcoded destinations" in the Freshpaint dashboard takes precedence over the integrations object set in code
* This feature is available in `@freshpaint/freshpaint-react-native` version 0.3.2 and later

### Comparison with Web SDK

The React Native SDK uses a third `options` parameter for better ergonomics, while the Web SDK nests `$options` inside the properties object:

**React Native SDK:**

```javascript
Freshpaint.track('Event', { property: 'value' }, {
  integrations: { Mixpanel: true }
});
```

**Web SDK:**

```javascript
freshpaint.track('Event', {
  property: 'value',
  $options: {
    integrations: { Mixpanel: true }
  }
});
```

Both approaches result in the same backend behavior.


---

# 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/reference/developer/freshpaint-react-native-sdk-reference.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.