Using the Totango JavaScript library is the simplest way to get started with usage data and product instrumentation (i.e., module/activity collection into Totango). Simply place the Totango JavaScript code snippet on the pages of your web application, set up a few parameters and you’re ready to go!

Before you begin, review Totango data objects, design considerations for unique account and user identifiers, and API considerations for account hierarchies. Every user activity must be tied to an account ID.

Copy and customize the code snippet

Modules

Modules in Totango represent key functional areas of your product offering. 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 your teams understand where users are engaging and how. 

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

You do not need to define the module explicitly in Totango. Once you start sending it, Totango will recognize the new module name and start collecting metrics on it.

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 add the following:

• 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 fewer.

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.

You do not need to define the user action explicitly in Totango. Once you start sending it, Totango will recognize the new event-name and start collecting metrics on it.

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

}

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");
});

Disable heartbeats (not recommended)

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 (value metrics).

Heartbeats show up explicitly in Totango with the __heartbeat user-action under the __system module. 

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); })();

Bare bones integration

Your supplementary data (like User Role and Account Name) may 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

Question: Is the Totango API case sensitive?

Answer: Yes. All Totango API nouns and verbs are case sensitive. This means that account-id: ABC123 and abc123 are not the same. Make sure you always send information using a consistent character case.

Question: What are the consequences of deleting a user action from the Instrumentation screen?

Answer: 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).

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. 

Question: How can I exclude specific accounts or users (for example, test accounts or internal users) from sending usage data to Totango?

Answer: 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
}
};

Question: How do I use the Totango Javascript collector on a single page application? 

Answer: To make changes to the Totango collector library after it has initially been setup in your application </body> section, simply update the totango_options object and then call totango.go() to apply the new settings. 

For example, the following code will update the Totango collector with user and account information once this it is obtained from a JavaScript callback.

// this is a callback we use when a user successfully logs into our app
function onUserLoaded(user) {
  // setup Totango from new user session 
  window.totango_options = { 
     user { id: user.emailAddress } 
     account {
       id: user.accountID,        // account this user belongs to
       name: user.accountName,
       status: user.accountType,
       create_date: user.accountCreateDate 
     }

   };
   // totango will start collection for the logged-in username now
   totango.go(totango_options); 

If your application allows users to change accounts or even user profile on the fly and you want to change which account/user you are tracking use:

totango.track("Login", "Application Module", {id:"account1234"}, {id:"user@example.com"});  
// track the activity 'Login' under module 'Application' for user 'user@example.com' under account 'account1234', note user and account should be passed as objects as cited above.