Upsight logo Back to top

Getting Started

Basic Integration


To get started with Upsight's Web SDK simply paste the following code snippet.

<script>
    !function(a,b,c,d,e){a.upsight=a.upsight||function(){for(var a=["createBillboard","extendSession","getAllAttributes","getAttribute",
    "getBillboard","getLatestSessionInfo","getSenderId","init","isContentReady","recordMilestone","removeAllAttributes","removeAttribute",
    "setAttribute","startNewSession","trackCustomEvent","trackMonetizationPriceQuantity","trackMonetizationTotal"],
    b={q:[]},c=0,d=a.length;c<d;c++){var e=a[c];b[e]=function(a){return function(){b.q.push([a,(new Date).getTime(),arguments])}}(e)}
    return b}();var f=b.createElement("script"),g=b.getElementsByTagName("script")[0];f.src="https://js.upsight-api.com/upsight-sdk.min.js",
    f.async=!0,g.parentNode.insertBefore(f,g)}(window,document);
</script>

The code snippet will add a global 'upsight' instance to the 'window' object and creates a queue as a placeholder for the SDK until the SDK is finally loaded. All methods that were previously enqueued will execute immediately when the SDK is ready. In order to work with the 'upsight' instance, it must first be initialized with your application token.

upsight.init('YOUR_APP_TOKEN');

At this point your application should be setup to send messages to Upsight. If you open the Upsight realtime page and then your application, you should see events appear. If there is not a current session in progress then an 'upsight.session.start' event is automatically sent once you call init. The event includes a 'sid' which is generated to uniquely identify the browser and persisted on the client to be used for subsequent sessions. The value of this id can be retrieved using 'getSenderId'.

upsight.getSenderId(function(senderId) {
  console.log(senderId);  // Logs the sender ID
});

Note All standard metrics are based on this identifier and are thus based on the browser being used to access the application and not on the specific user who is logged in.

Debugging


To see whether or not Upsight is successfully integrated after you added in your App Token, you can look at our Real Time dashboard or your browser's network tab.
NoteIt takes an hour for the real time monitor to first start showing data from a newly created application.

Since the dashboard takes time to process data, to track these messages in real time and ensure proper integration go to Real Time. Go to Real Time > Select App > Click on Filter.

Integration Center

After just calling upsight.init, you should see session events on the realtime page.

  • Opening the page for the first time will generate an "upsight.session.start" message.

Every message includes an sid, which is generated to uniquely identify the browser and persisted on the client to be used for subsequent sessions. The value of this id can be retrieved using upsight.getSenderId. Note that all standard metrics are based on this identifier and are thus based on the browser being used to access the application and not on the specific user who is logged in.

You can also turn on logging for the Upsight SDK when calling upsight.init and passing in debug, info, warn, or exception to logLevel as part of the optional parameters as indicated the init method reference:

upsight.init('YOUR_APP_TOKEN', {
    logLevel: "debug"
});

Custom Events


Once you have initialized the SDK, you can track an event just by setting the event name and properties as indicated in the code example below:

var myData =  { 
    item_value : 100
    item_name: "name"
}

upsight.trackCustomEvent("event_name", myData);

Set properties to null or simply call upsight.trackCustomEvent("event_name") if there are no properties you want tracked. Otherwise, create a JSON object representing the event properties you wish to track. Examples include a soft currency value, and item type. Additionally, for custom events periods can be used in the event name to create event hierarchy such as category.subcategory.my_event_name.

Tracking Events


Tracking Events

To track additional events from your application you can call 'trackCustomEvent' anytime something interesting happens.

upsight.trackCustomEvent('my.event', {
  eventAttributeA: 'premium',
  eventAttributeB: 'used_coupon'
});

The supported tracking methods are:

  • trackCustomEvent()
  • trackMonetizationTotal()
  • trackMonetizationPriceQuantity()

Tracking User Attributes

You can also tie particular attributes to your application's current user by calling setAttribute. These attributes will automatically be sent along with every tracking event. Note that you should use one of the remove methods to clear these attributes on logout so that they aren't inadvertently sent for another user later on. The supported user attribute methods are:

  • getAllAttributes()
  • getAttribute()
  • removeAllAttributes()
  • removeAttribute()
  • setAttribute()

Methods Requiring Callbacks

Because the SDK executes its methods asynchronously by default, any method that returns a value requires a callback method. The provided callback method will be invoked with the return value, which the developer can then set their own variable with that return value.

Example:

upsight.setAttribute('my_attribute', 'some value');

upsight.getAttribute('my_attribute', function(attr) {
  console.log(attr); // Logs 'some value'
});

The following methods require a callback method to be passed as an argument to get the return value:

  • createBillboard()
  • getAttribute()
  • getBillboard()
  • getLatestSessionInfo()
  • getSenderId()
  • isContentReady()

Session Control

By default if a tracking event occurs and the browser has not sent an event within the last 30 minutes then a new session is considered to have begun. The length of this interval can be configured when calling 'init'. In addition the SDK provides an 'extendSession' method which tells it to wait an additional interval before beginning a new session as well as 'startNewSession' which will immediately trigger a new session start.