Working with the Aptrinsic Web SDK

Updated 4 months ago by Angelo Matheou

Welcome

Welcome to the Aptrinsic Web SDK reference guide!

Tha Aptrinsic Javascript API is capable of performing all of the below functionality:

  1. Sends your web application’s events (i.e. sessions, page views, clicks) back to your Aptrinsic subscription 
    (See Tag Install below for more information)
  2. Sends identify information (i.e. user’s first name, last name, email, company name, etc) so that these events that are captured are also associated with the correct user/account.  
    (See Identifying your Users section below for more information)
  3. Communicates with the Aptrinsic servers to check if it is time to trigger any real-time engagement to the user.
    (This functionality automatically happens as long as your tag has been installed and the identify call is being made)
  4. Retrieves the details of the engagement (i.e. tooltip, guide, slider, location, copy, creative, etc.) so that the engagement can be surfaced to the user’s browser.
    (This functionality automatically happens as long as your tag has been installed and the identify call is being made) 
  5. Add one or more “feature match” Javascript api calls to your application so that you can trigger a feature event from anywhere in your application.  This opens the door to many unique & useful scenarios!
    (See the Feature Match section below for more information) 

NOTE: The first two above are required steps to get Aptrinsic installed on to your application and should already be in use if you have completed the initial installation (see the “Let’s Get Installed” documentation).

Let’s provide more detail around each of the Javascript API functions that allows your developers to make the above magic happen.

Tag Setup to Track your Application’s Sessions, Page Views and Events

The following is a sample Tag that needs to be installed on your application so that the events from your web site or web application can be sent to Aptrinsic. Note that the PRODUCT-KEY should come from your Aptrinsic subscription in the Account Settings->Products Page.  There is a unique PRODUCT-KEY for each Product/Channel combination.

For more information, see the “Let’s Get Installed” documentation

<!-- Aptrinsic Tag-->
           <script type="text/javascript">
           (function(n,t,a,e){var i="aptrinsic";n[i]=n[i]||function(){
               (n[i].q=n[i].q||[]).push(arguments)},n[i].p=e;
             var r=t.createElement("script");r.async=!0,r.src=a+"?a="+e;
             var c=t.getElementsByTagName("script")[0];c.parentNode.insertBefore(r,c)
           })(window,document,"https://web-sdk.aptrinsic.com/api/aptrinsic.js","AP-PRODUCT-KEY-2");
          </script>
          <!-- End Aptrinsic Tag-->

Identifying your Users (post successful login)

The following is a sample identify call that needs to be added to the authentication section of your web application so that those events captured from the Tag Setup can be associated to the correct User/Account.

IMPORTANT:  When sending JSON values, be sure that

  • String types are enclosed in quotes
  • Number types are NOT enclosed in quotes
  • Date types are sent as a Long Value using Epoch time in milliseconds, like here.

When sending user and/or account data, you may want to include attributes on that user or account that are not part of the default set.  We call these custom attributes and you can add your own set of custom attributes from within your Aptrinsic subscription by navigating to  Account Settings->Attributes page here.  Take notice of the Attribute’s API name as you will need to include that in the call below.

Click here to see the default set of available attributes.

// Template
          aptrinsic('identify', [userObject],[accountObject]);
// Minimum Required
          aptrinsic('identify', {id: 'user-id'});
// optional to include the account object
          aptrinsic('identify', {id: 'user-id'},{id:'account-id'});
// it is recommended to include the user & account along with custom attributes
          aptrinsic('identify',
           {
             'id': 'unique-user-id',             // Required for logged in app users
             'email': 'useremail@address.com',
             'signedUpAt': 1516234662215,
             'firstName': 'John',
             'lastName': 'Smith',
             "userHash": '', // optional transient for HMAC identification
             // flat custom attributes
              "plan" : "gold",
              "price" : 95.5
           },
           {
             'id':'IBM',                         //Required
             'name':'International Business Machine',
              
             // flat custom attributes
             'Program': 'Platinum'
           }); 

Custom Events

The Aptrinsic Web SDK supports the ability to send custom events.  You include a name for the custom event as well as properties/values for that event.

The types supported are:

Here is an example call:

// Tracking with event properties
          
          aptrinsic('track', 'Engagement', {"name":"Product Release","Audience Size" :5000 ,"Launched" : true , "Launched date":"2018-03-08T18:11:00Z" });

Global Context

The Aptrinsic Web SDK supports the ability to set a "Global Context" for all user events captured by the Aptrinsic tracking tag.  Setting the "context" will automatically attach/assign those properties/values to all auto-tracked events (including custom events). 

This functionality will help your organization to :

  • Establish a sustainable instrumentation strategy 
  • Gain greater visibility 
  • Add context to the auto-tracked events that are specific to your organization

 The global context can be defined as a list of property/value pairs with the following types supported:

Here is an example call:

// Setting Global Context
          
          aptrinsic('set', 'globalContext', {"projectId":12345,"Project Type" :"Work Order", "Project Date":"2018-03-08T18:11:00Z" });

After this call all future events will be populated with global context: projectId=12345, Project Type = "Work Order" etc.

To update an existing value just call set again with the new value and all future events will now use the new value:

// Setting Global Context (Update a property)
          
          aptrinsic('set', 'globalContext', {"projectId":67890});


In the above example, the global context value for key "projectId" will now be 67890 for all future events.

But in the case we want to override only if not set before, you can call like this:

aptrinsic('set', 'globalContext', {"projectId" : 67890});
          aptrinsic('setOnce', 'globalContext', {"projectId" : 45673})

In the above calls, the global context for key "projectId" stays at 67890 and is not overridden by the second call

Remove

Removes a list of global context. This will remove the global context from being populated in future  events but does not effect past events

aptrinsic('remove', 'globalContext', ["projectId"])

The above call will no longer include the "projectId" property on future events. 

And finally, one more example:

aptrinsic('set', 'globalContext', {"projectId" : 67890});
          //call custom event
          aptrinsic('track', 'purchased', {"amount" : 1});
          aptrinsic('remove', 'globalContext', ["projectId"]);
          //call the same custom event again with different value
          aptrinsic('track', 'purchased', {"amount" : 2});

In the above example, the first call will assign "projectId=67890" to the "purchased" custom event , but it will not be included as part of the second call

Javascript API Debugging

Any exceptions that occur on the Aptrinsic Javascript SDK will be caught internally in the js and will not be exposed in the console along with different info messages.

If you want to see the logs from the Aptrinsic Javascript SDK in the console, navigate to your developer tools->console window and create a cookie called "apt.debug" with a value of "true" like this:

document.cookie = 'apt.debug=true ; path=/ ; domain=' + location.host;

How to validate that the Aptrinsic Tag has been installed

You can validate that the Aptrinsic Javascript SDK by checking the following:

1) Enter “aptrinsic.init” into your developer tools -> console window:

Aptrinsic Javascript SDK was
successfully initialized on the page
Aptrinsic Javascript SDK was NOT 
successfully initialized on the page

2) The following Aptrinsic cookies exist when you go to developer tools -> Application tab, apt.sid & apt.uid per below screenshot


How did we do?