Segment.com libraries (sources) generate messages about what’s happening in your site or app, and send them to the Segment.com servers. Segment then translates the content of those messages into different formats for use by other tools (destinations), and sends the translated messages to those tools.

Segment.com supports most programming languages and software stacks; please reference their source catalog for more information on building an implementation that is compatible with your application stack.

This article provides information on Analytics.js, the JavaScript library for a web source type (browser integration).

A code sample is attached to the bottom of this article.

Overview

As part of the setup, remember that every page, track and identify call that you want to show up in Totango must be tied to a groupId (defined in Totango as the Account ID). This is done via the group call. You must include context.groupId in every call you want to be sent through to Totango so our system can link the groupId in a call made to Segment with the associated account in Totango.

For the client-side/front-end Javascript library (Analytics.js):

• Sending Account data is done via the group call and pushes account attribute data to Totango.
• Sending Usage data requires an identify and group call before sending the usage data to Totango via a track or page call. 

Since Totango is all about identifying users, it is important to add a few API calls to your segment implementation with the exact information Totango needs. This requires sending both the Totango User ID and Account ID as a part of the Segment API call. 

Activity tracking  (front-end integration)

analytics.identify([user ID], {

  email: [user email],
  //name is optional 
  name: [user name],
  }).group([account ID], {
     //account name is optional
     name: [account name],
     }).track([action],{
        category: [module]
        }).page(["__heartbeat"]);
}}();

Attribute tracking

[app object].analytics.track({
  userId: [User identification],
  [Attribute name]: [Attribute value],
  context: {
     groupId: [Account identification]
  }
} 

analytics.track({
    userId: 'User ID',
    event: [action],
    properties: {
         "category": [module]
    },
    "context": {
      "groupId": 'Account ID',
      "traits": {
        //user attributes optional
        "email": "a@a.com",
        "age": 23
      }
});

Configure the code snippet

Add a call to analytics.identify() and analytics.group() within the segment snippet, using the syntax identified in the elements below. These should be inserted immediately below analytics.page(). 

When you want to track a specific activity you should call the analytics.track() method when the activity is triggered.

Identify

The identify() method is used to configure Totango user data.

Here is the syntax for the identify method.

analytics.identify([userId], [traits], [options], [callback])

Example of the identify method:

analytics.identify('jack@totango.com', {
  name: 'Jack Frank'
});

Group

The group() method is used to configure Totango account data.  It expects to find Totango multi-product and/or hierarchy settings in the options object.  Depending on the feature set you are using you can use product, or product and parent, or neither.

Here is the syntax for the group method:

analytics.group(groupId, [traits], [options], [callback]);

Example of the group method with options set for multi product and hierarchy:

analytics.group('test_group', // account id
{ 
   name: "Initech",
},
{ 
   Totango: {
      parent: {
         id: 'XYZ-85b'
      }
      product: {
         id: 'productA'   
      }
   }
});

Explained:

When sending data to Totango the above will send two calls:

#1: Account ID: test_group will receive the Name 'Initech', and parentID: 'XYZ-85b'

#2: Account ID: test_group__productA will receive any activities fired in this session.

Optional:

To override the system to not set the product account ID, (ie test_group__productA) you can override with:

...
product: {
         id: 'productA'
         account_id: '123'
         }
...

To override so that only one call is made to test_group__productA:

...
{ 
   Totango: {
      enableHierarchy = false
...

To not send data to Totango from a specific page replace the Totango JSON element with Totango:False

...
Totango: False
...

FAQs

Question: Will Totango create new accounts or users for me?

Answer: Yes. If the account does not exist in Totango (based on the Account ID), the HTTP API will create the account and the user. Please ensure that both Totango and Segment share the same unique identifiers for both users and accounts. 

Question: Where can I monitor usage data sent from Segment to Totango?

Answer: Refer to Totango's Developer Console.

Question: How dow I filter Segment.com data once added to Totango?

Answer: All filtering of data must be completed on the Segment side before sending it to Totango.

• segment_io_example.html2 KB