Totango Product Integration (AKA Javascript Collector)

Using the Totango Javascript library is the simplest way to get started with Totango. Simply place the Totango Javascript code on the pages of your web-app, set up a few parameters and you’re ready to go with basic Totango collection.

Adding the code

Your Javascript code is available when you log in to Totango.  Browse to https://app.totango.com/#/developer (or click on the 'Product Integration' box under the Integration Hub) and simply copy the code.

Setting up parameters

Update the parameters in the code-snippet to match the current user and session information. Usually, this is done by using session variables either on the server or front-end javascript.

• service_id: Your unique Totango service identifier (Login to Totango)
• region: optional - for EU services, please add the value “eu1” (region: "eu1")
• user.id: Email address of the current user
• account.id: Unique identifier for the user’s current account. Usually your web application's internal unique tenant-id or customer-id (Note: Totango only accepts alpha-numeric account IDs, no special characters).
  
  
• account.name:  Human-readable name of the account (used in Totango’s UI and reports)
  
  

Modules
Modules in Totango represent key functional areas of your product offering. An example if your product has a different application for end-users and managers, you may want to separate usage to “users-app” and “managers-app” modules. This will help the customer success team understand where users and engaging and how.  Your Totango administrator should have identified the modules to identify.

To set the module of a session, simply set the Module parameter with the totango_options variable. In the example below, we set the current module to “Managers-App”.

window.totango_options = {
   service_id: "SP-0000-00", 
   region: "eu1",                  //only for EU services
   user: {
     id: "john@anonymous.com"  
   },
   account:{
      id: "102213x",
      account_name: "Anonymous Industries" // Name of the account
   },

   // use the current page in the app as the Module name in Totango
   module: "Managers-App" 

};(function() { var tracker_name=window.totango_options.tracker_name||"totango";window.totango_tmp_stack=[];window[tracker_name]={go:function(){return -1;},setAccountAttributes:function(){},identify:function(){},track:function(t,o,n,a){window.totango_tmp_stack.push({activity:t,module:o,org:n,user:a}); return -1;}}; var e = document.createElement('script'); e.type = 'text/javascript'; e.async = true; e.src = ('https:' == document.location.protocol ? 'https://' : 'http://') + 'tracker.totango.com/totango3.js'; var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(e, s); })();

If you want to change the module while the session is currently running (common for Single Page Applications), you can update the totango_options variable and call totango.go():

   // somewhere in your code...
   
   window.totango_options = window.totango_options || {};
   // set the module
   window.totango_options.module = "Managers-App"; 

   // apply changes on Totango session
   totango.go(window.totango_options); 

Custom Attributes
You can add additional information describing accounts and users in the form of attributes. These are used in Totango for analysis and segmentation purposes.

In the example below, we are adding a name and role attribute to the user and checkin-enabled and Licenses, account attributes.

window.totango_options = {
 // replace with your code
 service_id: "SP-0000-00", 

 user: {
   id: "john@anonymous.com",  
   name: "John Doe",
   role: "admin",           
   // ...add more user attributes here..
 },

 account: {
      id: "102213x",
      account_name: "Anonymous Industries", // Name of the account
      enabled_checking: true,
      Licenses: 20
      // ... add more account attributes here.

}


};

(function() { var tracker_name=window.totango_options.tracker_name||"totango";window.totango_tmp_stack=[];window[tracker_name]={go:function(){return -1;},setAccountAttributes:function(){},identify:function(){},track:function(t,o,n,a){window.totango_tmp_stack.push({activity:t,module:o,org:n,user:a}); return -1;}}; var e = document.createElement('script'); e.type = 'text/javascript'; e.async = true; e.src = ('https:' == document.location.protocol ? 'https://' : 'http://') + 'tracker.totango.com/totango4.0.3.js'; var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(e, s); })();

Custom User-actions
You can tell Totango when a user does a specific action of importance on your application, such as updating their profile picture, sharing a document or creating a new project.

You can add as many actions as you like, but in general you should only do so for those actions that carry significant meaning in terms of user engagement. The rule of thumb is to have 50 user-action types of less.

To collect an action, use the totango.track() method. In the example below, we’re telling Totango that the current user just shared a document in the document management module. The first parameter is the user-action name and the second is the module.

// Assumes jQuery is loaded..
$("#Share-Button").click(function() {
   totango.track("Share Document", "Document Management"); 
   // Action name=Share Document; Module=Document Management

}

Make sure the Totango library is loaded before use

Be sure to only call track() after the totango library has fully loaded, otherwise it will silently fail. If you’d like to track an event on page load, use the window.load() call back as shown in the example below

  // (NOTE: Uses jQuery). 
  // Issue an event track as soon as the library is loaded...
  $(window).load(function() {
  // executes when page  fully loads 
  totango.track("user-action", "module");
});

Advanced Option - Disable Heartbeats

Heartbeats are automatically generated by the Totango javascript library every 60 seconds of user-activity. They are used by Totango to calculated Engagement and Time metrics on Totango. (read more).

While not recommended, you can disable heartbeats by adding the disable_heartbeat: true to totango_options, as shown below.

window.totango_options = {
  // replace with your code
  service_id: "SP-0000-00",
  // only explicit calls to totango.track() will generate events on Totango 
  disable_heartbeat:true, 
  user: { 
   },
  account: {
   } 
}; 

(function() { var tracker_name=window.totango_options.tracker_name||"totango";window.totango_tmp_stack=[];window[tracker_name]={go:function(){return -1;},setAccountAttributes:function(){},identify:function(){},track:function(t,o,n,a){window.totango_tmp_stack.push({activity:t,module:o,org:n,user:a}); return -1;}}; var e = document.createElement('script'); e.type = 'text/javascript'; e.async = true; e.src = ('https:' == document.location.protocol ? 'https://' : 'http://') + 'tracker.totango.com/totango4.0.3.js'; var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(e, s); })();

Barebones integration

Often times your supplementary data like User Role and Account Name are going to come from a different environment, here is the bare bones header information for that scenario.

window.totango_options = {
service_id: "SP-0000-00",         // Replace with your Totango service code (tenant ID)
user:                             // Start of the USER Array
  { 
   id: "john@anonymous.com",      // email address or other unique identifier of the user
   },
 
account:                          // Start of the ACCOUNT Array
   {
       id: "102213x",             // Unique identifier of the account the user is part of
    },
};
(function() { var tracker_name=window.totango_options.tracker_name||"totango";window.totango_tmp_stack=[];window[tracker_name]={go:function(){return -1;},setAccountAttributes:function(){},identify:function(){},track:function(t,o,n,a){window.totango_tmp_stack.push({activity:t,module:o,org:n,user:a}); return -1;}}; var e = document.createElement('script'); e.type = 'text/javascript'; e.async = true; e.src = ('https:' == document.location.protocol ? 'https://' : 'http://') + 'tracker.totango.com/totango4.0.3.js'; var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(e, s); })();

FAQs

Q: What are the consequences of deleting a user action from the Instrumentation screen?
A: You will still be able to see these actions in the historical data (it will not be deleted) but you will not be able to search by these actions (in a segment for example).

Q: Will Totango create new accounts or users for me?
A: Yes. If the Account does not exist in Totango (based on the Account ID), the HTTP API will create the Account and the user.