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 Totango In-App solution is scheduled for sunset

The following steps provide detailed instructions for setting up Totango In-App for the first time.

Please review recommended prerequisite knowledge prior to beginning.

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.

  1. 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. See Step 1.A below.
  2. If you have never installed the Totango code snippet on your application, you must use extreme caution to carefully map the right account identifier—as all activity in your application will be ingested as new account and user records in Totango if they system can't find a matching Totango account ID. You should first ensure the account and user IDs you will send to Totango are available in the front-end code of your product. See Step 1.B below.

Steps:

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

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

     

    B. 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 and user identifiers to each Totango Account and User ID, prior to installing the snippet. Or, install the script conditionally so that if there is not Account ID for a user, your application does not even load the script.

    FOR NON-EU CUSTOMERS

    <!-- Totango Tracking Code -->
    <script>
    var totango_options = {
    
service_id: "SP-123456-01", // Update this value to your Totango service id.
user: {
  id: myuserobject.email, // Email address or other unique identifier of the user
      name: myuserobject.fullname, // 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: myaccountobject.totangoaccountid, // Unique identifier of the account the user belongs to
      name: myaccountobject.accountname, // Name of the account
      status: "Paying", // OPTIONAL: Status of the account Free, Paying
      
      "Account Type": "Account", // OPTIONAL: Business label that describes account
      parent: { // OPTIONAL: reference to the parent account
        id: myaccountobject.totangoparentaccountid, // 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 -->

    FOR EU CUSTOMERS

    Please adapt the script based on the EU region that you're already using in Totango: eu or eu1

    <!-- Totango Tracking Code -->
    <script>
    var totango_options = {
    
service_id: "SP-123456-01", // Update this value to your Totango service id.
user: {
  id: myuserobject.email, // Email address or other unique identifier of the user
      name: myuserobject.fullname, // 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: myaccountobject.totangoaccountid, // Unique identifier of the account the user belongs to
      name: myaccountobject.accountname, // Name of the account
      status: "Paying", // OPTIONAL: Status of the account Free, Paying
      
      "Account Type": "Account", // OPTIONAL: Business label that describes account
      parent: { // OPTIONAL: reference to the parent account
        id: myaccountobject.totangoparentaccountid, // OPTIONAL: Parent id
        "Account Type": "Agency" // OPTIONAL: Business label that describes parent
         }
      },
    region: "eu", //Use "eu1" instead if that's Totango region
    
// 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 (must include the prefix and suffix).
    • 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.

  2. 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. The totango.identify method allows you to identify user attributes change throughout a user’s session on the website and leverage those conditions within your in-app experiences in real-time. For example, if a user completes a training event on your platform, you may want to show the user a celebratory announcement with an in-app step afterward. So, you may want to set some property (e.g., hasCompletedTraining) in the identify method to account for such scenario.

The takeaway here is that these properties are tracked real-time within your application and don't necessarily require you to additionally track them in Totango as custom user attributes.

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.

Some examples of common events for which to call this SDK function may include:

  • 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:

  1. Copy the code snippet, and replace the values marked in green with relevant data from your application:
    totango.identify(myuserobject.email, { // email address or other unique identifier of the user
    
permissionLevel: "admin", // Replace these properties with any user data
    plan: "premium",
    });
  2. 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.

Custom events are a way to enhance your web application usage data within Totango—not just specific to in-app. These events tell Totango when a user does a specific action of importance on your application—such as updating their profile picture or sharing a document. You then leverage this usage data throughout Totango, including launching campaigns, SuccessPlays, and 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. 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:

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

5. Enable the in-app tab

The "In-App" tab must be enabled within the SuccessBLOC for which you want to build experiences. SuccessBLOC collaborators, owners, and global admins can configure SuccessBLOC tabs.

Steps:

    1. From within the SuccessBLOC, click the SuccessBLOC title to edit.
    2. From the Visible tab, select the InApp box, and click Save.

 

6. 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:

    1. From Settings, expand User Management > Permissions.
    2. Click the Application Permissions tab.
    3. For each of the In-App Experiences options, choose from the following:

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

FAQs

Question: My users aren't associated with an Account ID in my application. Can I still use Totango In-App?

Answer: No. Only users identified with Account IDs and User IDs will be eligible for In-App experiences

Question: Can I build an In-App experience on our login page?

Answer: We do not support any anonymous user use cases because users must be identified and tracked in Totango in order to be eligible for In-App experiences.

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

Was this article helpful?

0 out of 0 found this helpful

Have more questions? Submit a request