Once you have instrumented your Cordova-based application with the Cordova Plugin, you can also use the APIs to customize the data for your app that appears in the Controller UI. The following sections show you how to use the Cordova Plugin SDK API to customize your instrumentation:

Using the Cordova Plugin SDK API

Syntax

To call SDK API methods, use the following syntax: window.plugins.ADEUMMobilePlugin.<method>

Arguments

The last two arguments for all of the SDK API methods should always be two functions. The first function should handle successful cases and the last method should handle failures.

For example:

window.plugins.ADEUMMobilePlugin.changeAppKey("<EUM_APP_KEY>",
    (success) => {
        this.showAlert("changeAppKey return: success");
    },
    (error) => {
        this.showAlert("changeAppKey error:" + error);
    }
);
JS

Add Methods to Call SDK APIs

To use the SDK APIs, you are recommended to create class methods that call the SDK APIs as shown below.

export class HomePage {
    ...
    someMethod(event) {
         window.plugins.ADEUMMobilePlugin.<method>(<arg1>, <success_function>, <failure_function>);
    }
    ...
}
JS

Example

Thus, for the HomePage.js file, your HomePage class could have the method takeScreenshot that calls the SDK API method screenshot as shown here.

export class HomePage {
    ...
    takeScreenshot(event) {
      // Call the Cordova plugin SDK methods
      window.plugins.ADEUMMobilePlugin.screenshot(
       (success) => {
        this.showAlert("crash return: success");
       },
      (error) => {
        this.showAlert("crash error:" + error);
      });
    }
    ...
}
JS

Change the App Key

To change the EUM application key, you use the method changeAppKey with the parameters below.

Parameter NameData TypeDescription
appKeystringThe EUM application key.
successfunctionA user-defined function that is called when changeAppKey is successful.
errorfunctionA user-defined function that is called when changeAppKey fails.

For example, you could create a new method that takes a new app key and passed it to the SDK API method changeAppKey.

changeAppKey(event, newAppKey) {
    window.plugins.ADEUMMobilePlugin.changeAppKey(newAppKey,
        (success) => {
            this.showAlert("changeAppKey return: success");
        },
        (error) => {
            this.showAlert("changeAppKey error:" + error);
        }
    );
}
JS

Collect Additional Types of Data

You can use methods available in the ADEUMMobilePlugin class to collect five additional types of data:

Info Points

Information points allow you to track how your own code is running. You can see how often a method is invoked, and how long it takes to run by calling beginCall. When the callbacks success or error are called, the call to track the info point ends.

  • beginCall(name, functionName, args, success, error)

Parameters

The table below describes the parameters for the two methods:

NameTypeDescription
namestringThe name of the file or module where the info point is being recorded.
functionNamestringThe function that is invoking beginCall to track an info point.
successfunctionThe user-defined callback for successful cases.
errorfunctionThe user-defined callback for failed cases.

Example

For example, you can use create info points with something like the code below to determine how a method is invoked, and how long it takes to run:

beginCall(event) {
    window.plugins.ADEUMMobilePlugin.beginCall("home.ts", "callTrackerFunction", "event",
        (tracker) => {
            tracker.reportCallEndedWithReturnValue("Return from home.ts",
                (success) => { console.log("End call with return value success:" + success);},
                (error) => { console.log("End call with return value error:" + error); });
            },
            (error) => {
                console.log("Begin call error:" + error);
        }
    );
}
JS

Custom Timers

You can create custom timers to time any arbitrary sequence of events within your code, even spanning multiple methods. You create the custom timers using the SDK API methods startTimer and stopTimer.

  • startTimerWithName(name, success, error)

  • stopTimerWithName(name, success, error)

 Parameters

The two methods take the following parameters:

NameTypeDescription
namestringThe name of the custom timer. Allowed characters are [A-Za-z\s0-9]. Illegal characters are replaced by their ASCII hex value.
successfunctionThe user-defined callback for successful cases.
errorfunctionThe user-defined callback for failed cases.

Example

For example, to track the time a user spends viewing a screen, the instrumentation could look like this:

startTimer(event) {
    window.plugins.ADEUMMobilePlugin.startTimerWithName(data.name,
        (success) => {
            this.showAlert("startTimerWithName return: success");
        },
        (error) => {
            this.showAlert("startTimerWithName error:" + error);
        }
    );
}
stopTimer(event) {
    window.plugins.ADEUMMobilePlugin.stopTimerWithName(data.name,
        (success) => {
            this.showAlert("stopTimerWithName return: success");
        },
        (error) => {
            this.showAlert("stopTimerWithName error:" + error);
        }
    );
}
JS

Custom Metrics

You can also report custom metrics. 

You create custom metrics with the reportMetricWithName:

  • reportMetricWithName(name, value, success, error) 

Parameters

The reportMetricWithName method takes the following parameters:

NameTypeDescription
namestringThe name of the custom metric. The metric names must consist of alphanumeric characters. Illegal characters are replaced by their ASCII hex value.
valuenumberif value is not a whole number an error will be returned.
successfunctionUser-defined success callback.
errorfunctionUser-defined error callback.

Example

For example, the following method could be used to report custom metrics:

reportMetric(event, data) {
    window.plugins.ADEUMMobilePlugin.reportMetricWithName(data.name, parseInt(data.value),
        (success) => {
            this.showAlert("reportMetricWithName : success");
        },
        (error) => {
            this.showAlert("reportMetricWithName error:" + error);
        }
    );
};
JS

Breadcrumbs

Breadcrumbs allow you to situate a crash in the context of your user's experience. Set a breadcrumb when something interesting happens. If your application crashes at some point in the future, the breadcrumb will be displayed along with the crash report. Each crash report displays the most recent 99 breadcrumbs.

You create and leave breadcrumbs with the following SDK API method:

  • leaveBreadcrumb(breadcrumb, mode, success, error)

Parameters

The method leaveBreadcrumb takes the following parameters:

NameTypeDescription
breadcrumbstringThe string to include in the crash report and sessions. Truncated at 2048 characters; empty values are ignored.
modenumber

The mode determining where the breadcrumb will be displayed:

  • 0 - for crashes only
  • 1 - for crashes and sessions.

The mode defaults to crashes if the value is not parseable.

successfunctionThe user-defined callback for successful cases.
errorfunctionThe user-defined callback for failed cases.

Example

This code example shows how to use the SDK API to leave a breadcrumb:

breadcrumb(mode) {
      window.plugins.ADEUMMobilePlugin.leaveBreadcrumb( "breadcrumb1", mode,
     (success) => {
        this.showAlert("leaveBreadcrumb return: success");
      },
      (error) => {
        this.showAlert("leaveBreadcrumb error:" + error);
    }
)  
JS

Add Custom User Data

You can set and later remove any string key/value pair you think might be useful with the following methods:

  • setUserData(key, value, success, error)

  • removeUserData(key, success, error)

Parameters

The following table describes the parameters:

NameTypeDescription
keystringThe key identifying the key-value pair.
valuestringThe value associated with the key.
successfunctionThe user-defined callback for successful cases.
errorfunctionThe user-defined callback for failed cases.

Example

The code example below shows how to set and remove user data with the SDK API:

setCustomData(event, data) {
    window.plugins.ADEUMMobilePlugin.setUserData(data.name, data.value,
        (success) => {
            this.showAlert("setUserData return: success");
        },
        (error) => {
            this.showAlert("setUserData error:" + error);
        }
    );
};
removeUserData(event, key) {
    window.plugins.ADEUMMobilePlugin.removeUserData(key,
        (success) => {
            this.showAlert("removeUserData return: success");
        },
        (error) => {
            this.showAlert("removeUserData error:" + error);
        }
    );
}
JS

Programmatically Control Sessions

By default, a mobile session ends after a period of user inactivity. For example, when a user opens your application, the session begins and only ends after the user stops using the app for a set period of time. When the user begins to use the application again, a new session begins. 

Instead of having a period of inactivity to define the duration of a session, however, you can use the following API to programmatically control when sessions begin and end.

startNextSession(success, error)
JS

When you call the method startNextSession from ADEUMMobilePlugin, the current session ends and a new session begins. The API enables you to define and frame your sessions so that they align more closely with business goals and expected user flows. For example, you could use the API to define a session that tracks a purchase of a product or registers a new user.  

Excessive use of this API will cause sessions to be throttled (excessive use is >10 calls per minute, but is subject to change). When not using the API, sessions will fall back to the default of ending after a period of user inactivity. 

Example of a Programmatically Controlled Session

In the example below, the current session ends and a new one begins when the checkout is made.

completeCheckout() {
    if (this.validateAddress() && this.validatePayment()){
        let loader = this.loader.create({
            content: "Completing the checkout..."
        });
        loader.present();
        return this.order.create({
          shipping_address: this.address,
          billing_address: this.address,
          cart_id: Number(this.configuration.get('cart_id'))
        })
        ...
        window.plugins.ADEUMMobilePlugin.startNextSession(
           (success) => {
                           console.log("startNextSession return: success");
                        },
           (error) => {
                           console.log("startNextSession error:" + error);
                      }
       );
}
JS

Start and End Session Frames

You can use Cordova Plugin to create session frames that will appear in the session activity. Session frames provide context for what the user is doing during a session. With the API, you can improve the names of user screens and chronicle user flows within a business context. 

Use Cases

The following are common using session frames:

  • One page performs multiple functions and you want more granular tracking of the individual functions.
  • A user flow spans multiple pages or user interactions. For example, you could use the API to create the session frames "Login", "Product Selection", and "Purchase" to chronicle the user flow for purchases.
  • You want to capture dynamic information based on user interactions to name session frames, such as an order ID.

SessionFrame API

The table below lists the three methods you can use with session frames. In short, you start a session frame with startSessionFrame and then use updateName and end to rename and end the session frame. 

Method
Parameters
Description
startSessionFrame(name, success, error)
  • name (string) - The name of the session frame.
  • success (function) - The user-defined success callback.
  • error (function) - The user-defined error callback.

Use this to start and name your session frame.

You call this method from window.plugins.ADEUMMobilePlugin.

updateName(name, success, error)
  • name (string) - The name of the session frame.
  • success (function) - The user-defined success callback.
  • error (function) - The user-defined error callback.

Rename the session frame name.

You call this method from the ADEUMMobilePlugin object.

 


end(success, error)
  • success (function) - The user-defined success callback.
  • error (function) - The user-defined error callback.

End the session frame. 

You call this method from the ADEUMMobilePlugin object.

Session Frame Example

In the following example, session frames are used to track user activity during the checkout process.

declare var window: any;
@Component({
    ...
})
export class OrderPage {
    sessionFrame: any;
    ...
   
    checkoutCartButtonClicked() {
        // The user starting to check out starts when the user clicks the checkout button
        // this may be after they have updated quantities of items in their cart, etc.
        window.plugins.ADEUMMobilePlugin.startSessionFrame("Checkout",
            (sessionFrame) => {
                // The returned object is saved to the class property 'sessionFrame' so 
                // the SessionFrame API methods 'updateName' and 'end' can be called from it later.
                this.sessionFrame = sessionFrame;
            },
            (error) => {
                console.log("startSessionFrame call error:" + error);
             }
        );
    }
    confirmOrderButtonClicked() {
        // Once they have confirmed payment info and shipping information, and they
        // are clicking the "Confirm" button to start the backend process of checking out
        // we may know more information about the order itself, such as an Order ID.
        this.sessionFrame.updateName("Checkout: Order ID " + this.orderId, 
            (success) => { 
                console.log("Order has been placed and sessionFrame updated:" + this.orderId); 
            },
            (error) => { 
                console.log("Order has been placed but sessionFrame couldn't be updated because of the error " + error); 
            }
        );
    }
    processOrderCompleted() {
        // Once the order is processed, the user is done "checking out" so we end
        // the session frame.
        this.sessionFrame.end(
            (success) => { 
                console.log("Order was completed and sessionFrame ended: " + success);
            },
            (error) => { 
                console.log("Order was completed but sessionFrame couldn't be ended because of: " + error); 
            }
        );
    }
    checkoutCancelled() {
        // If they cancel or go back, you'll want to end the session frame also, or else
        // it will be left open and appear to have never ended.
        this.sessionFrame.end(
            (success) => { 
                console.log("Order was cancelled and sessionFrame ended: " + success);
            },
            (error) => { 
                console.log("Order was cancelled but sessionFrame couldn't be ended because of: " + error); 
            }
        );
    }
} // end of export class OrderPage
JS

Configure and Take Screenshots

By default, mobile screenshots are enabled on the agent-side but disabled on the Controller-side. These screenshots appear in the Controller in the Sessions Details dialog. To programmatically take manual screenshots, you must enable screenshots in the Controller UI and add the Screenshot API below. 


screenshot(event) {
     // make a call to plugin
     console.log("screenshot click handler");
      window.plugins.ADEUMMobilePlugin.takeScreenshot(

     (success) => {
        this.showAlert("screenshot return: success");
      },
      (error) => {
        this.showAlert("screenshot error:" + error);
      });
}
JS

This will capture everything, including personal information, so you must be cautious of when to take the screenshot. 


Block and Unblock Screenshots

You can also block screenshots from being taken during the execution of a code block. This just temporarily blocks screenshots from being taken until you unblock screenshots. This enables you to stop taking screenshots in situations where users are entering personal data, such as on login and account screens. 

logInScreen(event) {
    // Block Screen while getting user input 
    window.plugins.ADEUMMobilePlugin.blockScreenshots(
        (success) => {
            console.log("blockScreenshots return: success");
            this.getUserInput();
            this.submitUserInput();
        },
        (error) => {
            console.log("blockScreenshots error:" + error);
         }
    );
    // Unblock screen and return to home page
    window.plugins.ADEUMMobilePlugin.unblockScreenshots(
        (success) => {
            console.log("unblockScreenshots return: success");
            this.homePage()
        },
        (error) => {
            console.log("unblockScreenshots error:" + error);
        }
    );
}
JS


Enable Logging and Set Logging Level

You use the method loggingLevel to enable and set the logging level. You can set logging to one of the following levels:

ValueLogging LevelDescription
0NoneNo logs are displayed. This level disables logging.
1ErrorOnly error messages are displayed. This is the default logging level.
2WarnWarning and error messages are displayed.
3InfoWarning, errors, and developer-focused messages are displayed.
4DebugErrors, warnings, developer information, and debugging messages are displayed.
5VerboseErrors, warnings, developer information, debugging, and troubleshooting messages are displayed.
6AllAll the supported log messages are displayed.

You enable logging by setting the logging level in the instrumentation configuration. For example, in this example, you are enabling logging and setting the logging level to Info:

window.plugins.ADEUMMobilePlugin.initWithConfiguration(
    {
        "appKey": "<EUM_APP_KEY>",
        "loggingLevel": 3
     },
     (success) => {
        this.showAlert("initWithConfiguration return: success");
     },
     (error) => {
        this.showAlert("initWithConfiguration error:" + error);
     }
);
JS

Cordova SDK Documentation

For the Cordova SDK API reference documentation, see the latest JSDoc documentation or the previous versions listed below: