Skip to content
App Experience Analytics
Documentation powered by DocOps

Browser Agent Extension APIs

Last update November 27, 2018

The Browser Agent Extension APIs help the web app to collect custom events. Custom events include Transactions, Location, User Id (Customers), Session Information, and Network Events. 

Follow these steps: 

  1. Complete the instructions in Collect Data from Your Web App
  2. Use the APIs mentioned in this section.

API Reference

Use the following APIs to collect information from the Browser Agent extension.

Custom Metrics

Custom Event APIs reflect the state at which the event was triggered. Use these APIs to understand the characteristics of a given event better. For example, you can determine cart value in a shopping application, package destination in a shipping application, car color in a car sales application, and so on. The data also appears in the Custom Metrics with trends on Average, Occurrences, and Aggregate for the selected time period. The aggregated data is grouped into hourly, daily, weekly, and monthly increments. For example, capture the number of chips won per session on a poker game application and display totals over time, and so on.

 Logs a text metric.

BrowserAgentExtension.logTextMetric({"key" : "key",
					"value": "value",
					"attributes" : { "k" : "v" } });

Parameters:

Event JSON object with the following fields:

key String Name of the session information.
value String Value of the session information.
attributes Map To send any extra parameters or additional information set as key (k), value (v) which are strings.  This parameter does not get stored in the Kibana index and so it cannot be visualised in the Kibana dashboards.

 Logs a numeric metric.

BrowserAgentExtension.logNumericMetric({"key" : "key",
					"value": 99.99,
					"attributes" : { "k" : "v" } });

Parameters:

Event JSON object with the following fields:

key String Name of the session information.
value Numeric Value of the session information.
attributes Map To send any extra parameters or additional information set as key (k), value (v) which are strings.  This parameter does not get stored in the Kibana index and so it cannot be visualised in the Kibana dashboards.

Session Information

Session Information APIs are related to user properties and reflect the current state of the user. Use these APIs to filter analytics based on these properties. For example, you can filter on the age of the user, or customer type such as Premium, Gold.

 Logs a session level information.

BrowserAgentExtension.setSessionAttribute({"type":"string" , 
					"key" : "sessionEventKey",
					"value": "sessionEventValue"});

Parameters:

Event JSON object with the following fields:

type String Values can be string or double.
key String Name of the session information.
value String Value of the session information.

 Sets the customer ID, usually post-login of application. Get a unique identifier such as username or userId to set as customerId.

BrowserAgentExtension.setCustomerId({"customerId" : "UserName" , 
				"attributes" : { "k" : "v" } });

Parameters:

Event JSON object with the following fields:

customerId String User identifier. Can be username or user ID.
attributes String Additional information set as key (k), value (v) which are strings.

Location

Sets the location of the device. Collects the country code and ZIP Code or latitude and longitude of the user location as set by application. This API sets country code and ZIP Code value in the header.

BrowserAgentExtension.setCustomerLocation({"zipCode" : "95051",
						"countryCode": "US",
						"latitude": "122.222" , 
						"longitude":"33" , 
						"attributes" : { "k" : "v" } });

Parameters:

Event JSON object with the following fields:

If ZIP Code, Country code is sent and that takes priority over latitude or longitude.

zipCode String  ZIP Code of the user. 
countryCode  String  Country code of the user. 
latitude String Latitude of the user location.
longitude String Longitude of the user location.
attributes Map Additional information set as key (k), value (v) which are strings.

Note: If your browser JavaScript API is unable to determine geolocation, you can create your own Google API key at the following link: https://developers.google.com/maps/documentation/javascript/get-api-key.

Use the following code snippet with the Browser Agent SDK, calling setCustomerLocation() on any page you would like to obtain location data.

function setCustomerLocation() {


    var API_KEY = "PUT_YOUR_KEY_HERE";


    var geolocate = new XMLHttpRequest();

    geolocate.onreadystatechange = function() {

        if (geolocate.readyState == 4 && geolocate.status == 200) {

            var location = BrowserAgent.globals.origFuncMap.jsonParse(geolocate.responseText);


            var latStr = location.location && location.location.lat ?

                                              location.location.lat.toString() : "";

            var lngStr = location.location && location.location.lng ?

                                              location.location.lng.toString() : "";


            var event = { "latitude" : latStr, "longitude" : lngStr };


            BrowserAgentExtension.setCustomerLocation(event);

        }

        else {

            console.log("setCustomerLocation: ready state: " + geolocate.readyState + " , status code: " + geolocate.status );

        }

    };

    geolocate.open("POST", "https://www.googleapis.com/geolocation/v1/geolocate?key=" + API_KEY, true );

    geolocate.setRequestHeader("Content-type", "application/json; charset=utf-8");


    var requestPayload = { "considerIp" : true };

    geolocate.send(BrowserAgent.jsonStringify(requestPayload));

Transactions

Transactional events group a set of events that are collected and display whether a transaction is complete, incomplete, or failed based on the usage of the transaction start and stop APIs.

Starts a new application transaction that bounds all the subsequent events.

BrowserAgentExtension.startApplicationTransaction({"transactionName" : "itemAddedToShoppingCart",
						"serviceName" : "CheckoutScreen", 
						"attributes" : { "k" : "v"}});

Parameters:

Event JSON object with the following fields:

transactionName  String  Name of the transaction. 
serviceName String Name of the service that includes the transaction.
attributes Map Additional information set as key (k), value (v) which are strings.

Stops the application transaction. Subsequent events are part of the previous transaction, if there is one. The parameter Failure passes null for a successful transaction. The parameter Failure passes a brief description about the failure for a failed transaction.

BrowserAgentExtension.stopApplicationTransaction({"transactionName" : "itemAddedToShoppingCart",
					"serviceName" : "CheckoutScreen", 
					"attributes" : { "k" : "v"}});
BrowserAgentExtension.stopApplicationTransaction({"transactionName" : "itemAddedToShoppingCart",
					"serviceName" : "CheckoutScreen", 
					"failure": "Reason for failure",
					"attributes" : { "k" : "v"}});

Parameters:

Event JSON object with the following fields:

transactionName  String  Name of the transaction. 
serviceName String Name of the service that includes the transaction.
failure String  Reason for the transaction to fail.
attributes Map Additional information set as key (k), value (v) which are strings.

 Sends a network event.

BrowserAgentExtension.logNetworkEvent({ "url": "http://ck.com",
                         "status": 200, //http status code
                         "inbytes": 33, //in bytes
                         "outbytes": 33, //in bytes
                         "time": 344, //in milliseconds
                         "attributes" : { "k" : "v"}});

Parameters:

Event JSON object with the following fields:

url String  Network URL
status  Numeric Integer  HTTP status code 
inbytes Numeric Integer  Bytes received 
outbytes Numeric Integer Bytes sent
time Numeric Integer Response time
attributes Map Additional information set as key (k), value (v) which are strings.

User Feedback

Lets users provide feedback about your app.

BrowserAgentExtension.setUserFeedback(string)

Parameters:

type String

Miscellaneous

Transaction Traces are events that capture a detailed description of the execution of a component (or thread) in your application. Since the browser is seen as such a component, transaction traces are generated by the Browser Agent and are automatically correlated with the down-stream transactions of a specific network call or request.
Use this API to add custom and contextual information to the transaction trace by adding properties (key-value pairs). For example, add custom and contextual information about a specific user session, the ASN or Internet Provider currently serving the network calls.

BrowserAgentExtension.addCustomOptionalProperty(key, value);
Usage Example
BrowserAgentExtension.addCustomOptionalProperty("my-key", "my-value");

Parameters:

key String Name of the Transaction Trace property.
value String Value of the Transaction Trace property.
Was this helpful?

Please log in to post comments.

  1. Bala Venkateswarlu Papisetti
    2018-09-19 06:42

    6th step need to update with latest Async changes

    1. Sunder Rosy
      2018-09-21 02:02

      Hi Bala,

      Thank you for the feedback. Will make the required change.

      Regards,
      Rosy

  2. Stefan Lindenberg
    2018-10-16 11:11

    I have two questions: How to send the app version (version column in the Axa UI), if we have a web application (javascript)? Whats the difference between "custom metrics" and "session information"?

    1. Sunder Rosy
      2018-10-17 02:37

      Hi Stefan,

      App Version can be displayed only for mobile apps and not for web apps. The web app version is always displayed as 1.0. 

      For information about custom metrics, see the Custom Metrics section.

      Regards,

      Rosy