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.

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: Valid values: Alpha-numeric (a..z, 0..9), underscore (_), Minus (-)).
  
  

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 are engaging and how.  Your business team should identify the modules that they want tracked.

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"
   },

   // 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 (Optional)
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:

• Name attribute to the user
• Role attribute to the user
• Checkin-enabled attribute to the Account
• Licenses attribute to the Account

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, these are all optional..
 },

 account: {
      id: "102213x",
      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 recommendation is 50 user-action types or 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 calculate Engagement and Time metrics within 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. 

Q: How can I exclude specific accounts or users (for example, test accounts or internal users) from sending usage data to Totango?
A: In order to exclude the accounts/users, just set null to the user_id property - this will prevent the JS collector (the snippet code you are using) from sending any data to Totango.

<!-- Totango Tracking Code -->
<script>
// prevent SDR for internal users
var UserId = "shmulik@totango.com";
if (UserId.endsWith("totango.com")){
UserId = null;
} 
var totango_options = {
service_id: "SP-0000-01", 

user: {
id: UserId, // if value is null, no SDR will be sent. 
},
account: {
id: "test_acc", // unique identifier of the account the user is part of
account_name: "Test Account Name", // name of the account
status: "Paying", // OPTIONAL: status of the account "Free", "Paying", ..
"Create Date": "2011-12-20T19:25:58.0Z", // OPTIONAL: date the account was created
"Account Type": "Account", // OPTIONAL: business label that describe this entity
}
};