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