# Kissmetrics Destination

## Destination Info

* Accepts [Page](/docs/segment/connections/spec/page), [Alias](/docs/segment/connections/spec/alias), [Group](/docs/segment/connections/spec/group), [Identify](/docs/segment/connections/spec/identify), [Track](/docs/segment/connections/spec/track) calls.
* In Cloud-mode, refer to it as **KISSmetrics** in the [Integrations object.](/docs/segment/guides/filtering-data/#filtering-with-the-integrations-object)
* In Device-mode, refer to it as **KISSmetrics** in the [Integrations object.](/docs/segment/guides/filtering-data/#filtering-with-the-integrations-object)

### Components

* [Browser](https://github.com/segment-integrations/analytics.js-integration-kissmetrics)
* Server

## Connection Modes

[Learn more about connection modes.](/docs/segment/connections/destinations/#connection-modes)

### Device-Mode

* web: yes
* mobile: no
* server: no

### Cloud-Mode

* web: yes
* mobile: yes
* server: yes

[Kissmetrics](https://www.kissmetrics.io/?utm_source=segmentio\&utm_medium=docs\&utm_campaign=partners) is a behavioral email and analytics platform. It pulls cross-platform behavior reports so marketers can analyze key audience growth segments. It also provides an overview of custom populations, population change and growth, so marketers can analyze populations from customers who have completed actions or events.

## Getting Started

To enable Kissmetrics in Segment:

1. From the Segment web app, click **Catalog**.
2. Search for "Kissmetrics" in the Catalog, select it, and choose which of your sources to connect the destination to.
3. In the destination settings, enter your Kissmetrics "API Key".
4. If you are using Kissmetrics using Segment's client-side analytics.js library, Segment asynchronously loads Kissmetrics JavaScript library onto the page. (This means you should remove Kissmetrics's snippet from your page.)

Your Kissmetrics source starts automatically collecting "Visited Site" events and [other automatically tracked events](https://support.kissmetrics.io/docs/javascript-settings).

## Page

If you're not familiar with the Segment Specs, take a look to understand what the [Page method](/docs/segment/connections/spec/page/) does. An example call would look like:

```javascript
analytics.page('Docs');
```

By default page calls with `name` and `category` properties will automatically be sent to Kissmetrics in your [`page`](/docs/segment/connections/spec/page/) calls. You can adjust this behavior in your Kissmetrics destination settings by toggling on and off the 'Track Categorized Pages' and 'Track Named Pages' settings.

Here's an example call on docs pages:

```javascript
analytics.page('Docs', { url: 'http:example.com/docs', referrer: 'http://google.com' })
```

This [`page`](/docs/segment/connections/spec/page/) call is translated into an event labeled: **Viewed Docs Page** and will have the properties:

```text
'Page - url': 'http:example.com/docs'
'Page - referrer': 'http://google.com'
```

**Note:** Kissmetrics requires an initial pageview to load the library. By default we include a call to [`page`](/docs/segment/connections/spec/page/) in your snippet. This call must be made at least once on any page where you expect Kissmetrics to be loaded.

## Identify

If you're not familiar with the Segment Specs, take a look to understand what the [Identify method](/docs/segment/connections/spec/identify/) does. An example call would look like:

```javascript
analytics.identify('userId123');
```

When you call [`identify`](/docs/segment/connections/spec/identify/), we first call Kissmetrics' `identify` method to store the `userId`. Then we call `set` to store the `traits`.

## Track

If you're not familiar with the Segment Specs, take a look to understand what the [Track method](/docs/segment/connections/spec/track/) does. An example call would look like:

```javascript
analytics.track('Clicked Button');
```

When you call [`track`](/docs/segment/connections/spec/track/) or one of its helper functions ([`trackLink`](/docs/segment/connections/sources/catalog/libraries/website/javascript/#track-link) and [`trackForm`](/docs/segment/connections/sources/catalog/libraries/website/javascript/#track-form),) we will call Kissmetrics' `record` with the exact same parameters.

The Kissmetrics javascript library automatically tracks a bunch of events (Visited Site, Ad Campaign Hit, Search Engine Hit, Form Submit, Pageview, etc.) These will all still work when you use Kissmetrics through Segment.

**Note:** If you send us an event with a property called "revenue" and we'll pass that on to Kissmetrics as `Billing amount`.

## Group

If you're not familiar with the Segment Specs, take a look to understand what the [Group method](/docs/segment/connections/spec/group/) does. An example call would look like:

```javascript
analytics.group('123');
```

When you call [`group`](/docs/segment/connections/spec/group/), we first call Kissmetrics' `identify` method to store the `userId`. Then we call `set` to store the company `traits` on the user. We prefix these traits with 'Group -'. For example,

```javascript
analytics.group('123', {
  name: 'Test Inc',
  employees: 250
})
```

will add the following traits to the user:

```javascript
'Group - id': '123',
'Group - Name': 'Test Inc'
'Group - Employees': 250
```

## Alias

If you're not familiar with the Segment Specs, take a look to understand what the [Alias method](/docs/segment/connections/spec/alias/) does. An example call would look like:

```javascript
analytics.alias();
```

Kissmetrics automatically aliases anonymous visitors the first time you call [`identify`](/docs/segment/connections/spec/identify/) from the browser. That means there's no need to explicitly call [`alias`](/docs/segment/connections/spec/alias/) if you're tracking anonymous visitors and identified users in client-side javascript.

### Aliasing on iOS

We will automatically call [`alias`](/docs/segment/connections/spec/alias/) for you the first time you [`identify`](/docs/segment/connections/spec/identify/) users from our iOS SDK. That way it works exactly like web browser tracking - you don't have to manually [`alias`](/docs/segment/connections/spec/alias/) new users.

You can read more about how Kissmetrics recommends using [`alias`](/docs/segment/connections/spec/alias/) [in their docs](https://support.kissmetrics.io/docs/understanding-identities).

## Best Practices

### Merging Identities

A common use of [`alias`](/docs/segment/connections/spec/alias/) for Kissmetrics is when an already identified user's unique `id` changes. In this case you need to merge the old identity with a new one.

For example, if you're identifying people by their email address and they change it. In that case you'll need to alias from the previous `id` (their old email address) to the new `userId` (their new email address). Here's an example in `node`:

```javascript
analytics.alias({
  previousId: 'old_email@aol.com',
  userId: 'new_email@example.com'
});
```

### Aliasing New Users Server-Side

In order to [`identify`](/docs/segment/connections/spec/identify/) **new users** server side and connect that user profile to an existing anonymous visitor profile there's some work to be done.

**Remember:** Kissmetrics aliases automatically the first time you call [`identify`](/docs/segment/connections/spec/identify/) in client-side JavaScript, so in most cases you don't have to call [`alias`](/docs/segment/connections/spec/alias/) at all.

We don't recommend handling [`alias`](/docs/segment/connections/spec/alias/) server side, but if you must, here's how to make it happen. There are two options: aliasing **in conjunction with client-side tracking** or aliasing when **tracking exclusively server side**.

### In Conjunction with Client-Side Tracking

If you're already tracking anonymous users on the client side you'll need to pass the Kissmetrics identity from the browser to your servers in order to [`alias`](/docs/segment/connections/spec/alias/) it to the new `userId`.

First, use [`analytics.ready`](/docs/segment/connections/sources/catalog/libraries/website/javascript#ready) to grab the Kissmetrics identity:

```javascript
analytics.ready(function(){
  var anonIdentity = KM.i();
});
```

Next, pass the `anonIdentity` to your server and [`alias`](/docs/segment/connections/spec/alias/), [`identify`](/docs/segment/connections/spec/identify/), [`track`](/docs/segment/connections/spec/track/) your new user.

Here's a `node` example where the new `userId` is `12345`:

```javascript
analytics.alias({ previousId: anonIdentity, userId: '12345' });
analytics.identify('12345');
analytics.track('Connected Facebook');
```

### Tracking Exclusively Server-Side

If you're only tracking anonymous users with one of our server-side sources that makes things easier. All you have to do is [`alias`](/docs/segment/connections/spec/alias/) the anonymous `id` to the new `userId`.

Here's a Python example of the [`alias`](/docs/segment/connections/spec/alias/), [`identify`](/docs/segment/connections/spec/identify/), [`track`](/docs/segment/connections/spec/track/) sequence where the server-side anonymous `id` was `92fh49fqh9849hf` and the new `userId` is `12345`:

```python
analytics.alias('92fh49fqh9849hf', '12345')
analytics.identify('12345')
analytics.track('Registered')
```

## Appendix

### User Properties

You can set Kissmetrics user properties in 2 ways with Segment:

1. Make an [`identify`](/docs/segment/connections/spec/identify/) call and include a `traits` object.
2. Make a [`track`](/docs/segment/connections/spec/track/) call and include a `properties` object.

### Nested Objects or Arrays

Keep in mind that if you send arrays, we will stringify them. Also if you pass a nested object as `traits` or `properties` inside the `identify` or `track` call, we will flatten them.

For example:

```text
analytics.track('Signed Up', {
  foo: {
    bar: {
      prop: [1, 2, 3]
    }
  }
});
```

The properties would be sent as `foo.bar.prop: '1,2,3'`.

Note that this is without the prefix setting enabled. If you had enabled that feature, it would be `Signed Up - foo.bar.prop: '1,2,3'`.

### Receive experiment data from A/B Testing tools

You can track A/B testing event data like [`Experiment Viewed`](/docs/segment/connections/spec/ab-testing/#experiment-viewed) and send it to Kissmetrics using Segment.

In order to enable this feature,

1. Find your A/B testing tool in your Segment dashboard
2. Select "Send experiment data to other tools (as an identify call) in Overview
3. Save and Close
4. You should see these events in the debugger

### E-Commerce

If you are using our ecommerce api, we will forward that data along to Kissmetrics following the [Kissmetrics Ecommerce Essentials Guide](https://support.kissmetrics.io/docs/e-commerce-javascript-code-examples).

## Engage

You can send computed traits and audiences generated using [Engage](/docs/segment/engage) to this destination as a **user property**. To learn more about Engage, schedule a [demo](https://segment.com/contact/demo).

For user-property destinations, an [identify](/docs/segment/connections/spec/identify/) call is sent to the destination for each user being added and removed. The property name is the snake\_cased version of the audience name, with a true/false value to indicate membership. For example, when a user first completes an order in the last 30 days, Engage sends an Identify call with the property `order_completed_last_30days: true`. When the user no longer satisfies this condition (for example, it's been more than 30 days since their last order), Engage sets that value to `false`.

When you first create an audience, Engage sends an Identify call for every user in that audience. Later audience syncs only send updates for users whose membership has changed since the last sync.

> \[!NOTE]
>
> Real-time audience syncs to Kissmetrics  may take six or more hours for the initial sync to complete. Upon completion, a sync frequency of two to three hours is expected.

## Settings

Segment lets you change these destination settings from the Segment app without having to touch any code.

| Field                   | Description                                                                                          | Required | Type    |
| ----------------------- | ---------------------------------------------------------------------------------------------------- | -------- | ------- |
| API Key                 | You can find your API Key on the Kissmetrics \[Settings page]\(https://app.kissmetrics.io/settings). | Yes      | string  |
| Prefix Properties       | Prefix the properties with the page or event name.                                                   | No       | boolean |
| Track Categorized Pages | Send an event for every page with a category.                                                        | No       | boolean |
| Track Named Pages       | Send an event for every page with a name.                                                            | No       | boolean |