Download PDF
Download page Customize the Cordova Instrumentation.
Customize the Cordova Instrumentation
Related pages:
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);
}
);
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>);
}
...
}
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);
});
}
...
}
Change the App Key
To change the EUM application key, you use the method changeAppKey
with the parameters below.
Parameter Name | Data Type | Description |
---|---|---|
appKey | string | The EUM application key. |
success | function | A user-defined function that is called when changeAppKey is successful. |
error | function | A 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);
}
);
}
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:
Name | Type | Description |
---|---|---|
name | string | The name of the file or module where the info point is being recorded. |
functionName | string | The function that is invoking beginCall to track an info point. |
success | function | The user-defined callback for successful cases. |
error | function | The 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);
}
);
}
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:
Name | Type | Description |
---|---|---|
name | string | The name of the custom timer. Allowed characters are [A-Za-z\s0-9]. Illegal characters are replaced by their ASCII hex value. |
success | function | The user-defined callback for successful cases. |
error | function | The 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);
}
);
}
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:
Name | Type | Description |
---|---|---|
name | string | The name of the custom metric. The metric names must consist of alphanumeric characters. Illegal characters are replaced by their ASCII hex value. |
value | number | if value is not a whole number an error will be returned. |
success | function | User-defined success callback. |
error | function | User-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);
}
);
};
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:
Name | Type | Description |
---|---|---|
breadcrumb | string | The string to include in the crash report and sessions. Truncated at 2048 characters; empty values are ignored. |
mode | number | The mode determining where the breadcrumb will be displayed:
The mode defaults to crashes if the value is not parseable. |
success | function | The user-defined callback for successful cases. |
error | function | The 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);
}
)
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:
Name | Type | Description |
---|---|---|
key | string | The key identifying the key-value pair. |
value | string | The value associated with the key. |
success | function | The user-defined callback for successful cases. |
error | function | The 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);
}
);
}
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)
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);
}
);
}
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 | |
---|---|---|---|
|
| Use this to start and name your session frame. You call this method from | |
|
| Rename the session frame name. You call this method from the | |
|
| End the session frame. You call this method from the |
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
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);
});
}
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);
}
);
}
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:
Value | Logging Level | Description |
---|---|---|
0 | None | No logs are displayed. This level disables logging. |
1 | Error | Only error messages are displayed. This is the default logging level. |
2 | Warn | Warning and error messages are displayed. |
3 | Info | Warning, errors, and developer-focused messages are displayed. |
4 | Debug | Errors, warnings, developer information, and debugging messages are displayed. |
5 | Verbose | Errors, warnings, developer information, debugging, and troubleshooting messages are displayed. |
6 | All | All 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);
}
);
Cordova SDK Documentation
For the Cordova SDK API reference documentation, see the latest JSDoc documentation or the previous versions listed below: