Freshsuccess JS Event Collector Quickstart

Javascript Event Library - Quick Start

API Docs

See the Javascript Event API for the complete set of Javascript API methods.

Audience

This document is aimed at Freshsuccess customers looking to instrument their products and start collecting and sending usage events to Freshsuccess.

Overview

This library provides a mechanism by which user interactions can be tracked and logged to Freshsuccess. Each event contains information about the specific interaction. This includes: the time at which the interaction occurred, the module and feature associated with the action, and the account and user ID that performed the action.

Modules and features specify a hierarchy by which to categorize events. Modules may include multiple features; while features are mapped to individual clicks or events within a module. E.g., a dashboard is an example of a module, while the specific action of adding a widget to that dashboard is associated with a feature.

A unique feature of the Freshsuccess JS Data API is the tracking of user time spent in your product. Time is tracked on both a per module and a per session basis. Mousemove and key events are used to accurately detect idle time. Sessions timeout after 30 minutes of inactivity.

NOTE: data sent via the event API is batch processed and is not immediately visible via the Freshsuccess UI. Data is aggregated every hour and is then viewable via the Freshsuccess Data Explorer. Data is then further aggregated every day and updates to some of the internal dashboards are only visible after the daily aggregation has occured.

Quick Start Guide

Data collection is achieved by inserting a single script reference to the Freshsuccess JS source in your app entry point, and then annotating your code where necessary.

Installation steps:

1. Obtain Api Keys

Obtain a JS Data ApiKey and AuthKey from the Freshsuccess product within the IT Administration module (see this support article in the Source Overview section.)

2. Obtain Debug URL

Obtain debug URL from the Freshsuccess product within IT Center > Instrumentation viewer

3. Insert Library

In your main app entry point (e.g., app.html) insert the following:

<script type="text/javascript" src="http://developer.freshsuccess.com/scripts/success.min.js"></script>

<script type="text/javascript" src="https://developer.freshsuccess.com/scripts/success.min.js"></script>

4. Instantiate Library

In your main app entry point (e.g., app.html) insert the following:

<script>
    /*
     * On each page that loads, initialize the Freshsuccess analytics js library.
     * The userId and accountId can be set here if known at initialization time.
     * Once the userId/accountId are set they are stored in a cookie for later use,
     * so that they only need to be set once per session.
     */
    window.onload = function() {
        _na = new na('yourApiKey', 'yourAuthKey',
                     {
                         userId: yourProduct.getUserId(),
                         accountId: yourProduct.getAccountId(),
                         trackUnload: true,
                         debugUrl: [debugUrl],
                         disableEventSend: false, // disable the sending of events
                         debug: false // disable console debug prints
                     });
    };
</script>

Replace yourApiKey, yourAuthKey with strings obtained in step #1, and getUserId()and getAccountId() with your own methods or vars corresponding to your userId and accountId. The accountId and userId can also be set at login time using the login() call (see below for an example), or they can be set via setAccountId()/setUserId() API calls.

Login

The first time the user logs into the system, a login() call should be made. In addition to sending a special login event it sets the current accountId and userId. Additionally, the login() call can also be used to register new product users (by sending details about them to Freshsuccess). For example:

    /*
     * Example of a login event sending additional details about the user.
     * See: https://developer.freshsuccess.com/api/jsapi.html for more details.
     */
    _na.login('user-5312', 'account-3324', {
        first_name: "Joe",
        last_name: "Hellerstein",
        email: "joe@gmail.com",
        phone: "5109828332"
    });

Setting the userId and accountId

Optionally, the accountId and userId can be set individually with setAccountId() and setUserId() if they are not known at Library init time. Once set, the accountId and userId are stored in cookies on the client, so they do not have to be provided on every instantiation of the Freshsuccess analytics object.

Changing account or user details

After the accountId and userId have been set, modules and feature events can be sent (see the next section for more details). Additional information about the account or the user can also be sent at this time via the identifyUser() and identifyAccount() calls. This is useful for updating the Freshsuccess system with new or changed information about an account or user.

    /*
     * Provide additional details about a user outside of the login call.
     * Note: the accountId and userId must have been previously set.
     * See: https://developer.freshsuccess.com/api/jsapi.html for more details.
     */
    _na.identifyUser({
        first_name: "Joe",
        last_name: "Hellerstein",
        email: "joe@gmail.com",
        phone: "5109828332"
    });

    /*
     * Provide additional details about an account.
     * Note: the accountId and must have been previously set.
     * See: https://developer.freshsuccess.com/api/jsapi.html for more details.
     */
    _na.identifyAccount({
        name: "Amazon",
        join_date: "1446662632025",
        phone: "5109828332",
        tier: "gold"
    });

Errors and debugging

Invalid api / auth keys result in POST 401 (Unauthorized) errors (in your Freshsuccess's JS console). Note, that if userId and/or accountId are not set, events will be anonymous and features/modules will not be tracked -- only session time is tracked (not recommended).

Also note that we have enabled debugUrl in this step we will disable it in step #6. The debugUrl sends the events collected to a specified URL instead of the primary data collector. This is useful for viewing the events (see step #5).

5. Track Module and Feature Usage

Javascript based data collection is achieved by inserting Freshsuccess API calls within your JS code base.

Modules

Modules are used to distinguish logical parts of your application to indicate where your customers spend time in your product. Freshsuccess will track the amount of time your customers spend in each of the modules you define.

To enable module tracking, insert the following code:

_na.setModuleId(moduleName);

Replace moduleName with the applicable module name (string). Once a module has been set, it remains set until the page is reloaded. To clear a module, the set the moduleName to null. This instrumentation enables time tracking within a module.

In an MVC-type framework, e.g., Backbone.js, this would be best placed in the initialize method of each view.

Note that the moduleName will not be changed until explicitly modified or cleared, i.e., all views/modules need to be instrumented to ensure accuracy.

Features

Features are the user interactions that occur in a module (they map to user events), which can include buttons clicked, actions taken etc. Each feature is associated with the current module.

To enable feature tracking, insert the following code:

_na.sendFeatureEvent(featureName);

Replace featureName with the applicable feature name (string). The module name for the feature is set to the previously set module (unless the moduleName is explicitly cleared); otherwise the moduleName can be specified as an optional parameter to the sendFeatureEvent() call.

In an MVC-type framework, e.g., Backbone.js, this would be best placed within each individual method of a view.

6. Test Usage Tracking

To verify that your app has been properly instrumented, we have temporarily enabled debugUrl in step #3 and you may check event generation in the Freshsuccess product within
IT Center > Instrumentation Viewer:

Look out for accurate accountId, userId, module and feature attributes for each event.

7. Finalize

In your main app entry point (e.g., app.html) remove the debugUrl, replace with the following:

<script>
    window.onload = function() {
        _na = new na(‘yourApiKey’, ‘yourAuthKey’,
                     {
                        userId: yourProduct.getUserId(),
                        accountId: yourProduct.getAccountId(),
                        trackUnload: true
                    });
    };
</script>

If you are located in the EU and would like to use the EU data collection endpoint, you can add the option:

euEndpoint: true

To the options object passed into the na constructor (the default is false).

As mentioned in step #3, replace yourApiKey, yourAuthKey, getUserId() and getAccountId().

8. Let us know

Once your data is ready to be processed and has been sent to our production systems let us know so that we can create the workflows that process your data. Each workflow is updated manually, so it might take us a day or two to make your data visible via the UI. Don't worry, your data has been stored and will be processed in its entirety.

You have successfully instrumented your app, Cheers! :-)