# Totango Destination

## Destination Info

* Accepts [Page](/docs/segment/connections/spec/page), [Group](/docs/segment/connections/spec/group), [Identify](/docs/segment/connections/spec/identify), [Track](/docs/segment/connections/spec/track) calls.
* Refer to it as **Totango** in the [Integrations object.](/docs/segment/guides/filtering-data/#filtering-with-the-integrations-object)

### Components

* [Browser](https://github.com/segment-integrations/analytics.js-integration-totango)
* 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

Segment's Totango destination code is all open-source on GitHub: [JavaScript](https://github.com/segmentio/analytics.js-integrations/tree/master/integrations/totango).

## Getting Started

To get started with Totango and Segment, toggle Totango on in your Segment destinations and add your **Service ID**, which you can find in your Totango settings.

Once you've done that, those new settings will propagate to our CDN (that usually takes around 45 minutes) and Totango will be live on your site! Since Totango is all about identified users, the next thing you'll want to do is add a few API calls with exactly the information Totango needs. We'll show you how.

**Note:** As part of setup, you should know the user and call `identify` before the `group` call. Remember that every `page` and `track` call that you want to show up in Totango must be tied to a `groupId` (Totango calls this Account ID). , however.

For our client-side Javascript library (Analytics.js) that means you need to call `group` at least once with a `groupId` and we will cache it and attach it to future calls to other methods.

For server-side and mobile libraries you must include `context.groupId` in every call you want to be sent through to Totango so they can connect the dots between a call made to Segment and an account in their system.

## Group

Totango also needs to know what "account" the user belongs to. To record this, you'd use our [`group`](/docs/segment/connections/spec/group/) method. Group also takes a unique ID (for the group this time!) and a dictionary of properties about the group. It looks like this:

A call to `group` is required before any `track` calls will be sent to Totango.

```js
analytics.group('sjsj2hdj2', {
  name: 'Initech',
  website: 'http://www.example.com'
});
```

Making a call like that will add the current user to the group, which maps directly to Totango's "accounts".

You should always call [`group`](/docs/segment/connections/spec/group/) after your call to [`identify`](/docs/segment/connections/spec/identify/), so that we know which user you want to associate with the group. To learn more about how [`group`](/docs/segment/connections/spec/group/) works, check out our [Group docs](/docs/segment/connections/spec/group/).

## Page

Totango allows you to split your application into functional sections known as `modules`. By default, Totango pulls this module out of the users current URL. You can customize this behavior by using our [`page`](/docs/segment/connections/spec/page) method. You can pass `category` as a property to [`page`](/docs/segment/connections/spec/page) and we'll set that as the `module` in Totango.

[`page`](/docs/segment/connections/spec/page) takes the category of the page, the name of the page and any optional properties you want to associate with the pageview. The [`page`](/docs/segment/connections/spec/page) call is included by default in your snippet, since it's a required call. Modify the [`page`](/docs/segment/connections/spec/page) call inside the snippet or move it elsewhere, but don't delete it.

It looks like this:

```js
// Names and categorizes the page... sets the totango module to "Blog"
analytics.page('Blog', '15,000 Ways to Increase Conversion');
```

You can label as many categories / modules as you need, but as a best practice you'll probably want to have around 5 for a small – medium sized app to 20 for a very large web-application.

## Identify

The first thing Totango needs to know is "who is the user browsing your site?" You record this with our [`identify`](/docs/segment/connections/spec/identify/) method. Identify takes the unique ID of a user and any traits you know about them. It looks like this:

```js
analytics.identify('29ej29d', {
  email: 'lawrence@example.com',
  name: 'Lawrence Drywall',
  age: 42
});
```

To learn more about how [`identify`](/docs/segment/connections/spec/identify/) works, check out our [Identify docs](/docs/segment/connections/spec/identify/). For example, `email` and `name` are two of our [special traits](/docs/segment/connections/spec/identify/#traits) that we recognize semantically.

**If you're sending data using the server-side or mobile libraries**, you'll need to include `context.groupId`. Check out the [server-side](#server-side-methods-require-group-id) section to see how.

### Special Properties

Totango recognizes a few special properties for accounts that mean very specific things. For example, an account's `plan` indicates whether they are paying you or not. Here are the special properties for the [`group`](/docs/segment/connections/spec/group/) method that Segment will recognize and translate for you automatically:

| `created` *Date or String*  | The date when the account was first created. We will automatically change this from `created` to `'Create Date'` for the Totango API, but you should send it to us as `created`. If you don't provide this, Totango will default to the current date. |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `plan` *String*, *optional* | The "Free" or "Paying" plan of the account. You can set up extra types of plans in your Totango settings if "Free" and "Paying" don't suit your needs. If you don't provide this, we'll default it to `"Free"`.                                       |

To use the rest of the Totango's special properties, just pass them exactly like you would normally to Totango and we'll send them straight through!

## Track

Totango also lets you record any events a user triggers in your interface. To do that with Segment you'd use our [`track`](/docs/segment/connections/spec/track/) method. If you're just starting out with events, we usually recommend recording 5-10 of your business's most important events. You can always add more later!

[`track`](/docs/segment/connections/spec/track/) takes the name of the event and any optional properties you want to associate with the event. If you'd like to add a `category` to your `track` calls in addition to your `page` calls, you can add them as `properties`. It looks like this:

```js
analytics.track('Completed Purchase', {
  revenue: 42.99,
  shippingMethod: '2-day',
  category: 'Conversion'
});
```

To learn more about how [`track`](/docs/segment/connections/spec/track/) works check out our [Track docs](/docs/segment/connections/spec/identify/). For example, `revenue` is a special property that lets you semantically describe how much money you're making.

**If you're sending data using the server-side or mobile libraries**, you'll need to include `context.groupId`. Check out the [troubleshooting](#troubleshooting) section to see how.

## Troubleshooting

### Server-side Methods Require Group ID

Totango requires `groupId` on every `identify`, `page` and `track` call, so you'll need to pass it using `context.groupId`.

Here's a node `identify` example to get you started:

```js
analytics.identify({
  userId: '29ej29d',
  traits: {
    email: 'lawrence@example.com',
    name: 'Lawrence Drywall',
    age: 42
  },
  context: {
    groupId: 'sjsj2hdj2'
  }
});
```

## 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 Totango  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    |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- |
| Disable the Totango Heartbeat      | By default Totango's Javascript pings its servers once a minute to see if the user has left the page. If you don't want that to happen, enable this setting.                                                                                                                          | No       | boolean |
| Region                             | What region should data be sent to. Currently applies only for web device-mode integration and not cloud-mode integration. Please note, the region should match your settings in Totango.                                                                                             | No       | select  |
| Service ID                         | You can find your Service ID under \*\*Settings > Developer Console\*\* in \[Totango]\(https://app.totango.com/#!/integration/developerConsole).                                                                                                                                      | Yes      | string  |
| Track Categorized Pages to Totango | This will track events to Totango for \[\`page\` method]\(/docs/segment/connections/sources/catalog/libraries/website/javascript/#page) calls that have a \`category\` associated with them. For example \`page('Docs', 'Index')\` would translate to \*\*Viewed Docs Index Page\*\*. | No       | boolean |
| Track Named Pages to Totango       | This will track events to Totango for \[\`page\` method]\(/docs/segment/connections/sources/catalog/libraries/website/javascript/#page) calls that have a \`name\` associated with them. For example \`page('Signup')\` would translate to \*\*Viewed Signup Page\*\*.                | No       | boolean |