# Mixpanel Web Device Mode Integration

After you have successfully instrumented Mixpanel as a destination in RudderStack, follow this guide to correctly send your events to Mixpanel in [device mode]({{< ref "/destinations/rudderstack-connection-modes.md#cloud-mode" >}}).

Find the open source transformer code for this destination in the [GitHub repository](https://github.com/rudderlabs/rudder-sdk-js/tree/develop/packages/analytics-js-integrations/src/integrations/Mixpanel).

## Identify

You can use the [`identify`]({{< ref "event-spec/standard-events/identify.md" >}}) call to create or update a user in Mixpanel.

{{< warning >}}
When sending events to Mixpanel with **Simplified ID Merge**, you need to pass `deviceId` generated by the Mixpanel SDK as `anonymousId` in the RudderStack calls to merge two profiles together successfully. For more information, see [Mixpanel User Profiles documentation](https://help.mixpanel.com/hc/en-us/articles/14377628688788#user-profiles).
{{< /warning >}}

A sample `identify` call is as shown:

```javascript
rudderanalytics.identify("12345", {
  firstname: "Alex",
  city: "New Orleans",
  country: "USA",
  phone: "8005550100",
  email: "alex@example.com"
})
```

### Setting traits as People Properties and Super Properties

If **Use Mixpanel People** option is toggled on in the dashboard, you can set the `identify` traits as both **Super Properties** and **People Properties**. To do so, turn on the **Automatically set all Traits as Super Properties and People Properties** option in the dashboard settings.

You can also choose to filter your reports by both People Properties and Super Properties. This gives you better control over what traits you can set as a Super Property or People Property. To do this:

1. Disable the **Automatically set all Traits as Super Properties and People Properties** option in the dashboard.
2. Add the traits that you want to send to Mixpanel as Super Properties or People Properties in the **Properties to send as Super Properties** and **Traits to set as People Properties** fields respectively:

{{< image src="images/event-stream-destinations/mixpanel-super-people.webp"  >}}

{{< info >}}
RudderStack sends all Mixpanel [special traits](#mixpanel-special-traits) as People Properties. Hence, you can only add the properties that are not in this list.
{{< /info >}}

### Properties to set only once

RudderStack lets you set the `identify` traits as Mixpanel properties whose values you do not want to change at the user profile level, that is, Mixpanel will not overwrite the existing property values. See [Mixpanel documentation](https://developer.mixpanel.com/reference/profile-set-property-once/) for more information on this feature.

To use this feature:

1. Enable the **Use Mixpanel People** option in the dashboard.
2. Add the traits in the **Properties to set only once** setting.

{{< image src="images/event-stream-destinations/mixpanel-properties-set-once.webp"  >}}

RudderStack expects the traits specified in the above field to be present in the `context.traits` object within the `identify` event.

For example, if your `identify` event contains the following and you specify `address.city` in the **Properties to set only once** field:

```javascript
"traits": {
  "address": {
    "city": "London"
  }
}

...

"context": {
  "traits": {
    "address": {
      "city": "Berlin"
    }
  }
}
```

Then, RudderStack maps `city` as `Berlin`.

### Reserved Mixpanel properties

Mixpanel has some reserved properties:

- `$first_name`
- `$last_name`
- `$name`
- `$username`
- `$created`
- `$email`
- `$phone`
- `$avatar`
- `$city`
- `$country_code`
- `$region`
- `$unsubscribed`

{{< warning >}}
You should not create custom properties that begin with a `$` sign.
{{< /warning >}}

### Mixpanel People

RudderStack does not send data to Mixpanel People by default, as it usually requires you to upgrade your Mixpanel account. If you want to use this feature, you can turn on the [Use Mixpanel People]({{< ref "destinations/streaming-destinations/mixpanel/setup-guide.md#web-sdk-settings" >}}) setting in the RudderStack dashboard.

You can identify the user traits without the `userId` if you wish to add the people properties in Mixpanel before knowing the `userId`. To do so, see the following snippet:

```javascript
rudderanalytics.identify({
  email: 'alex@example.com',
  name: 'Alex Keener'
})
```

## Track

To track user events, use the [`track`]({{< ref "event-spec/standard-events/track.md" >}}) method with the event name and the associated properties.

When you select **Simplified ID Merge** in the [Identity Merge]({{< ref "destinations/streaming-destinations/mixpanel/setup-guide.md#connection-settings" >}}) dashboard setting, RudderStack sets the event's `userId` and `anonymousId` using Mixpanel's [Simplified ID Merge API](https://help.mixpanel.com/hc/en-us/articles/14377628688788) so that the two identifiers are glued to a single user profile.

A sample `track` call is as shown:

```javascript
rudderanalytics.track("track event", {
    test_prop1: 50,
    test_prop2: "prop_value"
});
```

### Track revenue

Mixpanel lets you track revenue events. If you send `revenue` as a property in your `track` event, RudderStack tracks it as a revenue event.

Revenue tracking is done with a `distinct_id` \(`userId` that you provide in your `identify` call; if `userId` is not present then it will be associated with an `anonymousId`.\)

A sample revenue `track` call is as shown:

```javascript
rudderanalytics.track("Purchase", {
  revenue: 100,
  currency: "USD"
});
```

### Track charge

If **Use Mixpanel People** setting is toggled on in your RudderStack dashboard and you include `revenue` as an event property, RudderStack will track a charge for the current user.

## Page

RudderStack passes all page properties that you provide via the [`page`]({{< ref "event-spec/standard-events/page.md" >}}) call to Mixpanel, along with the other default properties. It sets the event name as **Page** for a `page` call.

When you select **Simplified ID Merge** in the **Identity Merge** dashboard setting, RudderStack sets the event's `userId` and `anonymousId` using Mixpanel's [Simplified ID Merge API](https://help.mixpanel.com/hc/en-us/articles/14377628688788) so that the two identifiers are glued to a single user profile.

A sample `page` call is shown below:

```javascript
rudderanalytics.page();
```

### Page web device mode settings

RudderStack sends one event to Mixpanel per `page` call and offers the following three options:

- **Track All Pages with a Consolidated Event Name**: This setting is on by default. RudderStack sends all `page`calls with the name `Loaded a Page` with the corresponding properties of the call. This lets you leverage Mixpanel's reporting capabilities for page/screen analytics in the best possible way.
- **Track Categorized Pages to Mixpanel**: RudderStack tracks the categorized pages to Mixpanel. If you turn on this setting in the dashboard, RudderStack sends a `Viewed [<category>] Page` event to Mixpanel. If the page name is also present in the event, then RudderStack sends a `Viewed [<category> <page_name>] Page` event.
- **Track Named Pages to Mixpanel**: RudderStack also tracks the named pages to Mixpanel. If you turn on this setting in the dashboard, RudderStack will send a `Viewed [page_name] Page` event. Note that this option has the least precedence and comes to effect only if the above two options are disabled in the RudderStack dashboard.

{{< info >}}
RudderStack gives the highest precedence to the **Track All Pages with a Consolidated Event Name** option even if **Track Categorized Pages to Mixpanel** and 
**Track Named Pages to Mixpanel** are turned on in the dashboard.
{{< /info >}}

{{< warning >}}
RudderStack expects atleast one of the three options listed above to be toggled on for sending the `page` events to Mixpanel using device mode.
{{< /warning >}}

## Alias

The [`alias`]({{< ref "event-spec/standard-events/alias.md" >}}) call lets you associate multiple identities of a known user.

{{< warning >}}
The `alias` call is deprecated with the **Simplified ID Merge** dashboard setting.
{{< /warning >}}

A sample `alias` call is as shown:

```javascript
analytics.alias('userId', `previousId`);
```

## Group

The [`group`]({{< ref "event-spec/standard-events/group.md" >}}) call lets you link an identified user with a group such as a company, organization, or an account, and record any traits associated with that group, for example, company name, number of employees, etc. For more information on how the `group` call works in Mixpanel, see Mixpanel's [Group Analytics](https://help.mixpanel.com/hc/en-us/articles/360025333632-Group-Analytics) documentation.

RudderStack lets you record the custom traits associated with a user group and send this information to Mixpanel.

A sample `group` call is shown below:

```javascript
rudderanalytics.group(
  "sample_group_id", {
    name: "Tech group",
    industry: "Technology",
    employees: 100,
  }
);
```

### Group key

You can create group keys in the [Mixpanel project settings](https://help.mixpanel.com/hc/en-us/articles/360025333632-Group-Analytics#implementation), which act as the group identifiers in Mixpanel. To successfully send a `group` call to Mixpanel, you must specify **at least** one group key in the [Group key settings]({{< ref "destinations/streaming-destinations/mixpanel/setup-guide.md#group-settings-web-device-mode" >}}) in the RudderStack dashboard.

{{< warning >}}
Note the following points:
- If you map the `groupId` as a group key, RudderStack looks up its value in the following priority order:
    1. In `message.groupId`
    2. In `message.traits.groupId`
- If you map any other field as a group key, RudderStack looks up its value in `message.traits.groupKey`.
- You can specify multiple values for a group key and send them in an array in the `group` event payload.
{{< /warning >}}

## Send historic events

Mixpanel supports importing historical event data. However, note that the event timestamp should be within the **last 5 years**. Mixpanel rejects any data older than this duration. To send historic events, provide the timestamp in the `timestamp` field of the message. RudderStack will then send the event with the same timestamp to Mixpanel.

## Mixpanel special traits

The following table lists all properties that RudderStack sends to Mixpanel as special traits:

| RudderStack Properties     | Mixpanel Properties  |
| :------------------------- | :------------------- |
| `created`                  | `$created`           |
| `email`                    | `$email`             | 
| `firstName`                | `$first_name`        |
| `lastName`                 | `$last_name`         |
| `lastSeen`                 | `$last_seen`         |
| `name`                     | `$name`              |
| `username`                 | `$username`          |
| `phone`                    | `$phone`             |
| `city`/`address.city`      | `$city`              |
| `region`/`address.state`   | `$region`            |
| `country`/`address.country`| `$country_code`      |

## Increment events in Mixpanel People

To increment event counts in Mixpanel People, you can add the events in the [Events to increment in People]({{< ref "destinations/streaming-destinations/mixpanel/setup-guide.md#web-sdk-settings" >}}) field.

For each event name added, RudderStack automatically calls Mixpanel and sets a user trait as `Last + <event_name>`. For example, if you add `Logged In` to the list of increment events, RudderStack will increment a user trait called `Logged In` and set a trait called `Last Logged In` with the current date and time.

{{< warning >}}
Increment works for known users only. If you make a `track` call, you must identify your user first.
{{< /warning >}}

## Increment properties in Mixpanel People

To increment properties in Mixpanel People, you can add them in the [Properties to Increment in People]({{< ref "destinations/streaming-destinations/mixpanel/setup-guide.md#mixpanel-config-device-mode" >}}) dashboard setting.

RudderStack calls Mixpanel’s increment when you attach a number to the specified property. For example, `'items purchased': 5`.

## Events sent for session replay {#session-replay}

Use the [Percentage of SDK Initializations that qualify for Replay Data Capture]({{< ref "destinations/streaming-destinations/mixpanel/setup-guide.md#web-sdk-settings" >}}) to specify the percentage of events (0 to 100) that Mixpanel considers for session replay.

{{< warning >}}
If you do not specify any value, RudderStack sets it to `0` by default, meaning Mixpanel **does not** consider any events for session replay.
{{< /warning >}}

You can also add [other configuration fields](https://docs.mixpanel.com/docs/tracking-methods/sdks/javascript#init-options) for this setting while initializing the JavaScript SDK:

```javascript
rudderanalytics.load(
  "WRITE_KEY",
  "DATA_PLANE_URL", {
    configUrl: "https://api.rudderlabs.com",
    logLevel: "DEBUG",
    integrations: {
      Mixpanel: {
        recordBlockClass: 'block-class',
        recordCollectFonts: true,
        recordIdleTimeout: 5000,
        recordMaskTextClass: 'mask-text',
        recordMaskTextSelector: '.sensitive',
        recordMaxMs: 30000,
        recordMinMs: 1000,
      }
    }
  }
);
```

Note that:

- RudderStack considers the above configuration fields in the `integrations` object values **only if** the [Percentage of SDK Initializations that qualify for Replay Data Capture]({{< ref "destinations/streaming-destinations/mixpanel/setup-guide.md#web-sdk-settings" >}}) dashboard setting is non-empty.
- If not set explicitly, RudderStack **does not** consider any default values for these configuration fields.

## FAQ 

#### Can I pass `null` and empty values for the properties?

Yes, RudderStack supports passing empty or `null` values for the properties sent to Mixpanel.

<br />