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)
- 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.
- account.name: Human readable name of the account (used in Totango’s UI and reports)
|
TIP: Review Design consideration - unique account- and user- identifiers if you are not sure about the right id values. |
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",
user: {
id: "john@anonymous.com"
},
account:{
id: "102213x",
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",
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/totango3.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.
|
TIP: 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
}
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/totango3.js'; var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(e, s); })();
Bare bones 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/totango3.js'; var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(e, s); })();