Configure Totango In-App

Before you begin

Installation of the code snippet requires someone on your team with access to the production environment of your application's code base.
While installation is simple, we recommend starting the process early to ensure you obtain the necessary approval or advanced noticed required to identify and schedule this change.
Building experiences with Totango In-App requires a Chrome browser.

The following steps provide detailed instructions for setting up Totango In-App for the first time. Please begin this process with your engineering team as soon as possible to prevent delays.

1. Install the Totango in-app builder code snippet

The Totango In-App code snippet must be installed to publish in-app experiences. Although it is possible to begin drafting in-app experiences for your website with the Totango In-App Builder, we recommend starting this process as soon as possible.

The in-app snippet is included as part of the Totango tracking code used for the JavaScript collector. If you already have the Totango code snippet installed (prior to August 1, 2023), you'll only need to make a small modification to the version number.

Steps:

Determine if your website already has the Totango tracking snippet installed.

If the Totango tracking snippet is already installed, locate the following code in your website, and increase the version number (highlighted in red) to “6.0.0”.

(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/totango6.0.0.js';

  var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(e,s);

})();

If the Totango tracking snippet is not already installed, add the following code to every page in your application (just before the closing </head> tag). Installation of this script sends basic user engagement data to your Totango service and installs the In-App SDK that powers in-app experiences.

Replace the values marked in green with relevant data from your application, most likely a variable to programmatically capture values. Alternatively, visit the In-App Builder Settings (Installation Center) to copy the snippet code.

If the user and/or account does not exist in Totango (based on the Account ID), Totango will create new account and user records in your instance, using the user's email address as the Account ID. It is highly recommended to ensure that your application has a mechanism in place to match its account identifier to each Totango Account ID, prior to installing the snippet.

<!-- Totango Tracking Code -->
<script>
var totango_options = {

service_id: "123456", // Update this value to your Totango service id.
user: {
  id: "john@anonymous.com", // Email address or other unique identifier of the user
  name: "John Doe", // Name of the user

  // Supply any other user data properties here that you would like to have available for real-time filtering and/or content template variables
  },

account: {
  id: "102213x", // Unique identifier of the account the user belongs to
  name: "Anonymous Industries", // Name of the account
  status: "Paying", // OPTIONAL: Status of the account Free, Paying
  "Create Date": "2011-12-20T19:25:58.0Z", // OPTIONAL: Create date of account
  "Account Type": "Account", // OPTIONAL: Business label that describes account
  parent: { // OPTIONAL: reference to the parent account
    id: "1013x", // OPTIONAL: Parent id
    "Account Type": "Agency" // OPTIONAL: Business label that describes parent
     }
  },

// OPTIONAL: Add product if you would like to register usage events on the specific product

product: {
  id: "Photos", // product id
  },

enableHierarchy: false
};

(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/totango6.0.0.js';

        var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(e, s);

        })();

</script>
<!-- End Totango Tracking Code -->

service_id: Your unique Totango service identifier.
user.id: Unique identifier for current user in Totango (most likely email address)
account.id: Unique identifier for the user’s current account in Totango.

If you’d like to install into a testing environment such as a staging application, you can install the same exact code snippet there. We recommend adding a user attribute such as { env: “test”} to help with filtering between environments. See environment pipelines for more details.

Ensure that the script has been installed correctly by visiting the In-App Builder Settings (Installation Center). Active installations appear with a list of domains:

2. Track updates to user data in your application (optional)

This step of the installation process is optional. However, we strongly recommend tracking updates in order to show in-app experiences to users based on real-time updates (i.e., when a user upgrades their subscription or permission level).

To track updates to user data, call the following In-App SDK function with the current user’s ID and any user data properties that you would like to use as real-time filters and/or content template variables.

We recommend calling this SDK function whenever any of the following events occur:

When a user logs in to your app
When a new user registers for an account
When a user's info updates (for example, their permissions change)

Steps:

Copy the code snippet, and replace the values marked in green with relevant data from your application:

totango.identify("john@anonymous.com", { // email address or other unique identifier of the user

permissionLevel: "admin", // Replace these properties with any user data
plan: "premium",
});

Call the following function whenever a user registers, logs in, or updates their information within your application.

3. Track custom events (optional)

This step of the installation process is optional and can be done post-installation.

Tell Totango when a user does a specific action of importance on your application—such as updating their profile picture or sharing a document—and then launch Totango In-App experiences based on these events.

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

4. Set Totango user permissions

This step is not required, but it is recommended. Global admins always have the highest levels of permissions, regardless of the individual application permissions.

Before you start building, determine whether other Totango team members can view experience properties, edit experiences, and publish experiences.

Steps:

From Settings, expand User Management > Permissions.
Click the Application Permissions tab.
For each of the In-App Experiences options, choose from the following:
- Only specific roles (define which roles apply; includes custom roles or account assignment roles)
- Every member of the team
- Everyone in account assignment
- No one (only available to global admins)

Totango users who have permissions to edit experiences must also be an owner or collaborator of the related SuccessBLOC.

5. Add the in-app Chrome extension

This step is required for anyone who wants to edit an in-app experiences.

In order to build experiences on your website, each person with build permissions must add the in-app experience builder extension to their Chrome browser.

Steps:

Visit the Chrome web store and click to add the in-app experience builder extension.
After you install it, optionally pin the extension to your browser bar.
Start building!

FAQs

Question: What is the user ID in reference to?

Answer: The “User ID” field is the unique identifier that you supply to the Totango tracking script for each user. You do not have to supply any special "In-App" user ID.

Question: How can I install the code snippet with TypeScript?

Answer: Depending upon your configuration, TypeScript may throw errors when you attempt to call totango SDK functions (such as "Cannot find name ‘totango’"). This is because "totango" is a global class defined on window, but TypeScript doesn't know that it exists. In order to inform TypeScript about the totango class, you can add the following code to your global.d.ts file (or equivalent):

export declare global {
  interface Window {
  Totango: any;
  }
}

If you'd like better type support for all totango SDK functions, you can include the following more detailed type definitions. Please note that these types are updated periodically.

export declare global {
interface Window {
totango: {
  identify: (id: string, properties?: Record<string, unknown>) => Record<string, unknown>;
  track: (event: string, data?: Record<string, unknown>) => void;
  startTour: (id: string, includeViewRules?: boolean, includeSegmentation?: boolean) => void;
  launchWidget: (id: string, includeViewRules?: boolean, includeSegmentation?: boolean) => void;
  listen: (accepts: string, callback: (...params: any[]) => void) => void;
  stopListening: () => void;
  }
}
}

Question: How can I working with linters?

Answer: Depending upon your configuration, a linter (such as eslint) may throw errors or warnings inside your IDE when you attempt to call totango SDK functions. This is because "totango" is a global class defined on window but your linter doesn't know that it exists. In order to inform your linter about the totango class, you can add the following code to your linter config file (ex. .eslintrc):

{
  ...existingConfig,
  "globals”: {
  ...existingGlobalsConfig,
  “totango": true,
  }
}

Configure Totango In-App

1. Install the Totango in-app builder code snippet

Steps:

2. Track updates to user data in your application (optional)

Steps:

3. Track custom events (optional)

4. Set Totango user permissions

Steps:

5. Add the in-app Chrome extension

Steps:

FAQs

Was this article helpful?

In this article

<%= heading %>

<% if (block.html_url) { %> <%= block.name %> <% } else { %> <%= block.name %> <% } %>

Categories

Toggle navigation menu

<%= category.name %>