Customize the Cordova Instrumentation
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
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.
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
export class HomePage {
...
someMethod(event) {
window.plugins.ADEUMMobilePlugin.<method>(<arg1>, <success_function>, <failure_function>);
}
...
}
Example
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
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. |
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
ADEUMMobilePlugin
class to collect five additional types of data:- Info Points
- Custom Timers
- Custom Metrics
- User Data
- Breadcrumbs
Info Points
beginCall
. When the callbacks success
or error
are called, the call to track the info point ends.beginCall(name, functionName, args, success, error)
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. |
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
startTimer
and stopTimer
.startTimerWithName(name, success, error)
stopTimerWithName(name, success, error)
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. |
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.
reportMetricWithName
: reportMetricWithName(name, value, success, error)
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. |
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.
leaveBreadcrumb(breadcrumb, mode, success, error)
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. |
breadcrumb(mode) {
window.plugins.ADEUMMobilePlugin.leaveBreadcrumb( "breadcrumb1", mode,
(success) => {
this.showAlert("leaveBreadcrumb return: success");
},
(error) => {
this.showAlert("leaveBreadcrumb error:" + error);
}
)
Add Customer User Data
setUserData(key, value, success, error)
removeUserData(key, success, error)
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. |
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.
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
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 Sessions 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
- 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
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
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
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);
});
}
Block and Unblock Screenshots
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
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. |
Info
:window.plugins.ADEUMMobilePlugin.initWithConfiguration(
{
"appKey": "<EUM_APP_KEY>",
"loggingLevel": 3
},
(success) => {
this.showAlert("initWithConfiguration return: success");
},
(error) => {
this.showAlert("initWithConfiguration error:" + error);
}
);