# Analytics React Native Amplitude Plugin

[Amplitude](https://amplitude.com/) is an event tracking and segmentation platform for your web and mobile apps. By analyzing the actions your users perform, you can gain a better understanding to drive retention, engagement, and conversion.

## Getting started

1. Before you start, go to your [Amplitude workspace](https://analytics.amplitude.com). Click **Settings** in the bottom left, then click **Projects** in the left menu. Select your **Project**. Copy the Amplitude API Key and Secret Key for the project.
2. From the Segment web app, click **Catalog**, then click **Destinations**.
3. Find the Destinations Actions item in the left navigation, and click it.
4. Click the "Amplitude" item to select it and click **Configure**.
5. Choose which of your sources to connect the destination to. (You can connect more sources to the destination later.)

Once you have a mapping, you can follow the steps in the Destinations Actions documentation on [Customizing mappings](/docs/segment/connections/destinations/actions#customize-mappings).

The Amplitude React Native plugin doesn't send events to Amplitude from the client side. It instead adds Amplitude session data and then sends it server side from the Amplitude Actions destination.

## Adding the dependency

Using NPM:

```bash
npm install --save @segment/analytics-react-native-plugin-amplitude-session
```

Using Yarn:

```bash
yarn add @segment/analytics-react-native-plugin-amplitude-session
```

## Using the plugin in your app

Follow the [instructions for adding plugins](https://github.com/segmentio/analytics-react-native#adding-plugins) on the main Analytics client:

In your code where you initialize the analytics client call the `.add(plugin)` method with an `AmplitudeSessionPlugin` instance:

```ts
import { createClient } from '@segment/analytics-react-native';

import { AmplitudeSessionPlugin } from '@segment/analytics-react-native-plugin-amplitude-session';

const segmentClient = createClient({
  writeKey: 'SEGMENT_KEY'
});

segmentClient.add({ plugin: new AmplitudeSessionPlugin() });
```

### Log purchases in existing destination instances

Initially, the Log Event Action was reporting purchases to Amplitude for all events containing a `products` array, even if the products were just added to cart. This inflated the LTV Chart in Amplitude.

To resolve this, purchase reporting takes place in a new Action called Log Purchase.

For instances created prior to before the Log Purchases action was released, you need to manually add the Log Purchases Action to report purchases to Amplitude.

To manually add the Log Purchases Action:

1. Add a new Mapping for the Log Purchases Action. The default trigger for this action is Order Completed events.
2. Modify the Trigger if you need to report purchases for any other events.
3. Modify the Trigger of Log Event to exclude these same events. This helps you to avoid sending the same event twice.
4. Enable the Log Purchases mapping.

### Connection modes for Amplitude (Actions) destination

The Amplitude (actions) destination does not offer a device-mode connection mode. With the Actions-framework version of the destination, you do not need the device-mode connection.

Most previous deployments of the Amplitude Segment destination used the device-mode connection to use the `session_id` tracking feature. The new Actions-framework Amplitude destination, includes session ID tracking by default. This means you don't need to bundle any software to run on the user's device, or write any code. It also means that you can use more of the Segment platform features on data going to Amplitude, such as Protocols filtering and transformations, and Profiles Identity Resolution.

### Device ID mappings

The Amplitude destination requires that each event include either a Device ID or a User ID. If a User ID isn't present, Amplitude uses the a Device ID, and vice versa, if a Device ID isn't present, Amplitude uses the User ID.

By default, Segment maps the Segment property `context.device.id` to the Amplitude property `Device ID`. If `context.device.id` isn't available, Segment maps the property `anonymousId` to the Amplitude `Device ID`. The Actions interface indicates this with the following contents of the Device ID field: `coalesce(` `context.device.id` `anonymousId` `)`.

### Amplitude (Actions) uses Amplitude's HTTP API v2

> \[!WARNING]
>
> If you used Amplitude Classic in cloud-mode, you'll notice different responses from Amplitude to calls you make with the destination.

You configure the Amplitude (Actions) destination through Filters and Actions. Consult the following table for information about configuring your Amplitude (Actions) destination similarly to your classic Amplitude destination.

Contact Segment support if you find features missing from the Amplitude (Actions) destination that were available in the classic Amplitude destination.

### Amplitude settings mappings

#### CONNECTION SETTINGS

* **API Key** (CLOUD, DEVICE-WEB, DEVICE-MOBILE):
  * Global Setting
* **Version Name** (DEVICE-WEB):
  * Action field \*\*App Version\*\*.
  * Defaults to \`context.app.version\`.
* **Connection Mode** (CLOUD, DEVICE-WEB, DEVICE-MOBILE):
  * Actions support Cloud mode connections

#### PAGE AND SCREEN

* **Track all pages to Amplitude** (CLOUD, DEVICE-WEB, DEVICE-MOBILE):
  * Subscription \*\*Page Calls\*\*
  * When enabled, Amplitude (Actions) tracks all Page calls by default
* **Track all Screens** (CLOUD, DEVICE-WEB, DEVICE-MOBILE):
  * Subscription \*\*Page Calls\*\*
  * When enabled, Amplitude (Actions) tracks all Screen calls by default
* **Track Categorized Pages to Amplitude** (CLOUD, DEVICE-WEB, DEVICE-MOBILE):
  * Subscription \*\*Page Calls\*\*
  * Add a Trigger filter condition to check that Event Property \*\*category\*\* exists
* **Track Named Pages to Amplitude** (CLOUD, DEVICE-WEB, DEVICE-MOBILE):
  * Subscription \*\*Page Calls\*\*
  * Add a Trigger filter condition to check that Event Property \*\*name\*\* exists

#### TRAITS

* **Group Type Trait** (CLOUD, DEVICE-WEB, DEVICE-MOBILE):
  * Subscription \*\*Group Identify User\*\*.
  * Select a value in the \*\*Group Type\*\* actions field. This field is mandatory in Amplitude (Actions). In the Amplitude Classic destination, ommiting a value for property field resulted in Amplitude creating a group called \`\[Segment] Group\`.
* **Group Value Trait** (CLOUD, DEVICE-WEB, DEVICE-MOBILE):
  * Subscription \*\*Group Identify User\*\*.
  * Select a value in the \*\*Group Value\*\* actions field. This field is mandatory in Amplitude actions. In the Amplitude Classic destination, ommiting a value for this property resulted in an alpha-numeric value.

#### OTHER SETTINGS

* **Batch Events** (DEVICE-WEB):
  * \*\*Use Batch Endpoint\*\* field on the \*\*Log Event\*\* action
* **Prefer Anonymous Device ID** (CLOUD, DEVICE-WEB, DEVICE-MOBILE):
  * Actions field \*\*Device ID\*\*.
  * Replace the contents of the field with your preferred value.
* **Secret Key** (CLOUD, DEVICE-WEB, DEVICE-MOBILE):
  * Global Setting
* **Enable Alias** (CLOUD):
  * Use the \*\*Map User\*\* action.
  * The \*\*Map User\*\* action is not enabled by default. Add a new Subscription to access the \*\*Map User\*\* action.
* **Send to Batch Endpoint** (CLOUD):
  * \*\*Use Batch Endpoint\*\* field on the \*\*Log Event\*\* action
* **Track Referrer to Amplitude** (DEVICE-WEB):
  * Update the User Properties mapping to send \`context.page.referrer\`.
* **Track Revenue per Product** (CLOUD, DEVICE-WEB, DEVICE-MOBILE):
  * Actions field \*\*Track Revenue Per Product\*\*.
  * Available in any subscription that uses the \*\*Log Event\*\* action. \<br /> In Amplitude (Actions), this setting elevates \`revenue\` to a top-level property. This allows revenue data to pass through to Amplitude's LTV reports.
* **Track UTM Properties to Amplitude** (CLOUD, DEVICE-WEB):
  * Supported by default. See the UTM Properties section to view the mappings.
* **Use Advertising ID for Device ID** (CLOUD, DEVICE-WEB, DEVICE-MOBILE):
  * Actions field \*\*Device ID\*\*.
  * Update the value so your preferred field appears first in the \`coalesce()\` function.
* **Send Custom Language and Country Properties**:
  * Actions fields \*\*Language\*\* and \*\*Country\*\*
  * These fields are set by default with values from the context object.

## Advanced Amplitude (Actions) settings

### Increment traits

The `traitsToIncrement` setting increases a user property by some numerical value. If the user property does not have a value set yet, Segment initializes it with a value of 0. The trait must have a numerical value so it can be incremented.

In the following example, the Amplitude User property `friendCount` equals 4.

```js
"traits" : {"$add": {"friendCount": 3} }
"traits" : {"$add": {"friendCount": 1} }
```