Use JavaScript in Aternity Mobile to Tag Custom Events in Mobile Apps

You can use the JavaScript tagging available in the Aternity Mobile SDK to report custom app events from a mobile app that uses Webview. This enables you to expand your data collection beyond events captured automatically by the Aternity Mobile SDK.

tag an event to monitor custom activities in your mobile app's Webview by inserting a call to the JavaScript tagging API. A custom activity for mobile apps starts and ends when the app reports specific events which match the events of an activity's signature file.

JavaScript tagging is particularly useful because automatically-collected events on mobile apps may not give you the necessary insights into performance. For example, an email app may load a web page very infrequently, making web page load times an poor indicator of performance. The web page may be performing many background activities that are coded in JavaScript and are not picked up by the Aternity Mobile SDK. By explicitly tagging those events you can get a better picture of the app performance.

For example, to measure the response time between the start of a sign in and its response, if those events are not automatically reported, insert an API to tag the sign in action, and add another API call to tag its response. When you report each tag to Aternity, it matches them to the custom activity already in place, and then reports the response time in the dashboards. To create your own custom activities, contact Customer Services.

The Aternity Mobile SDK provides a single JavaScript object Aternity, which has a single method, tag. The code that reports events using Aternity.tag has the following format:

Aternity.tag (["<event name>", "<event type>", "<optional parameter1>", "<optional parameter 2>",...])
Field Description
<event name>

The name of the event, assigned by the web site developer.

<event type>

Can be one of these types:

  • app

  • cancel

  • error

<optional parameters>

Used by the developer to provide additional context for the event, such as the cause of the event.

Before you begin

You must have a mobile app that renders content in WebView.

You must have downloaded the Aternity Mobile SDK, which includes the file aternity_api.js.

The app must be integrated with the Aternity Mobile SDK:

You must be able to modify the web content that the app loads into WebView.

Procedure

  1. Step 1 Copy the aternity_api.js file to your web server, making note of the path.
    Important

    If your app loads web content from the device file system or resources that were bundled and installed with the app, you must also copy aternity_api.js to the same location where that content is located, before the app loads content into Webview.

    The aternity_api.js file, changes infrequently. Configure your Web server to allow the Web browser to cache the file until it is updated.

  2. Step 2 Enable JavaScript API calls from web pages.

    Add this code to the <head> section of the web page, replacing <../aternity_api.js> with the correct path to aternity_api.js. The code is broken into lines for readability.

    <script type="text/javascript">
    var Aternity=window[‘Aternity’]=[];
    Aternity.tag=function(){
    if(this.length>=500)this.splice(0, this.length-499); 
    var a=arguments[0];
    a.ts=Date.now();
    Array.prototype.push.call(this,a);
    };
    (function(b){
    var a=document.createElement("script");
    a.type="text/javascript";
    a.async=true;
    a.src=b;
    document.getElementsByTagName("head")[0].appendChild(a);
    }
    ("<../aternity_api.js>") )   
    </script>
  3. Step 3 Use the Aternity.tag(["setUser", , ]) tag to collect informaiton about the user who logs in when an application is already running in the WebView.

    For example, Aternity.tag([ "setUser", $(‘#txtUserName’).val(), $(‘#txtCompanyName’).val()]); collects the username and company name, and tags the sign-in event for reporting to Aternity.

  4. Step 4 Add tags to your web page as needed to mark the beginnings and ends of events that you want to measure.

    Here are examples of tags you can use to mark events related to a search performed in a mobile app Webview.:

    Tag Description
    Aternity.tag("search", "app", {phase: "start"})

    This marks the beginning of a search.

    Aternity.tag("search", "app", {phase: "end"})

    This marks the end of a search.

    Aternity.tag(["search, "error"])

    Search interrupted by an unspecified error.

    Aternity.tag(["search", "error", {reason : "Server unavailable"}]);

    Tags errors caused by server unavailability.

    Aternity.tag(["search, "cancel"])

    Search canceled by the user.

  5. Step 5 Your Aternity admin must upload a custom activity to Aternity to process the tagged event's data for presentation on Aternity dashboards.