Totango Destination

Segment makes it easy to send your data to Totango (and lots of other destinations). Once you've tracked your data through our open source libraries we'll translate and route your data to Totango in the format they understand. Learn more about how to use Totango with Segment.

Our Totango destination code is all open-source on GitHub if you want to check it out: Javascript, Server.

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

analytics.group('sjsj2hdj2', {
  name: 'Initech',
  website: 'http://www.initech.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 after your call to identify, so that we know which user you want to associate with the group. To learn more about how group works, check out our Group docs.

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 method. You can pass category as a property to page and we’ll set that as the module in Totango.

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 call is included by default in your snippet, since it’s a required call. Modify the page call inside the snippet or move it elsewhere, but don’t delete it.

It looks like this:

// 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. Not sure which modules to use? Check out Totango’s Best Practices guide.

Identify

The first thing Totango needs to know is “who is the user browsing your site?” You record this with our identify method. Identify takes the unique ID of a user and any traits you know about them. It looks like this:

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

To learn more about how identify works, check out our Identify docs. For example, email and name are two of our special traits that we recognize semantically.

If you’re sending data via the server-side or mobile libraries, you’ll need to include context.groupId. Check out the server-side 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 method that Segment will recognize and translate for you automatically:

created Date or StringThe 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, optionalThe “Free” or “Paying” plan of the account. You can setup 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 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 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:

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

To learn more about how track works check out our Track docs. For example, revenue is a special property that lets you semantically describe how much money you’re making.

If you’re sending data via the server-side or mobile libraries, you’ll need to include context.groupId. Check out the 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 via context.groupId.

Here’s a node identify example to get you started:

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

Supported Sources and Connection Modes

WebMobileServer
📱 Device-based
☁️ Cloud-based

To learn more about about Connection Modes and what dictates which we support, see here.

Settings

Segment lets you change these destination settings via your Segment dashboard without having to touch any code.

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.

Service ID

You can find your Service ID under Settings > Developer Console in Totango.

Track Categorized Pages to Totango

This will track events to Totango for page method calls that have a category associated with them. For example page('Docs', 'Index') would translate to Viewed Docs Index Page.

Track Named Pages to Totango

This will track events to Totango for page method calls that have a name associated with them. For example page('Signup') would translate to Viewed Signup Page.


If you have any questions or see anywhere we can improve our documentation, please let us know or kick off a conversation in the Segment Community!