Download PDF
Download page Instrument Cordova Applications.
Instrument Cordova Applications
Follow the steps below to get your EUM App Key and instrument your Cordova-based apps.
For native mobile applications, follow either the iOS Instrumentation or Android Instrumentation instructions. The mobile agents will inject the JavaScript Agent and auto-instrument your mobile application including the auto-instrumentation of the WKWebView.
Check Requirements
To use the AppDynamics Cordova plugin, your hybrid application must be using the following:
- Cordova >= 8.0.0
- npm >= 3.10.10
- Node.js >= 6.11.3
- WKWebView for iOS applications
WkWebView Requirements
By default, the Cordova iOS platform command adds a version of cordova-ios
that supports UIWebView. AppDynamics does not support UIWebView, so you must manually change this to WkWebView.
Run the following command:
(ionic) cordova platform add ios
CODEVerify the log output returns:
Using WkWebView
CODE- If the log output returns
Using UIWebView
, you must manually change it toUsing UIWebView
.
Get Your Application Key
After you completed the Getting Started Wizard, you were given an EUM App Key. You will need this key when you modify the source code. In some cases, multiple mobile applications can share the same key.
If you have completed the Getting Started Wizard, but don't have your EUM App Key, see Get Your Application Key.
Install and Initialize the Cordova Plugin
The AppDynamics Cordova plugin is certified to work with the Ionic and PhoneGap frameworks. Thus, the installation instructions below are for Ionic and PhoneGap applications. See the plugin installation instructions for your Cordova-based framework.
From the root directory of your Ionic application, run the following commands to install the plugin and build the mobile app. See the Ionic Cordova plugin documentation for more information.
Replace the values in brackets with the configurations for your app and run the command to add the configured plugin.
For SaaS deployments:ionic cordova plugin add appd-plugin-eum-mobile --variable APP_KEY="<#EUM_APP_KEY#>" --variable SCREENSHOTS_ENABLED=<true|false> --variable LOGGING_LEVEL=[0-6] --save
JSFor on-prem deployments, replace the value for the variable
COLLECTOR_URL
with the URL to your EUM Server and the value forSCREENSHOT_URL
with the URL to your on-prem Screenshot Service.ionic cordova plugin add appd-plugin-eum-mobile --variable APP_KEY="<#EUM_APP_KEY#>" --variable SCREENSHOTS_ENABLED=<true|false> --variable LOGGING_LEVEL=[0-6] --variable COLLECTOR_URL="http(s)://<on-prem_eum-server_url>:<PORT>" --variable SCREENSHOT_URL="http(s)://<on-prem_screenshot_service-url>" --save
JS(Optional) You can also disable or set the interaction capture mode (iOS/Android) and set the URL to test the network connectivity of Cordova iOS applications.
The interaction capture mode is on by default, but you can disable it by setting the variable
INTERACTION_CAPTURE_MODE
to0
or specify the desired capture mode for the platform (see the interaction mode values for iOS and Android in the table below). SettingINTERACTION_CAPTURE_MODE
only controls capturing of webview interactions. If you setINTERACTION_CAPTURE_MODE
to0
, interactions with webviews will no longer be captured. However, interactions with native UI elements, such as UI Buttons under iOS, will still be captured, as they always are captured by the underlying native agent for each platform.ionic cordova plugin add appd-plugin-eum-mobile --variable APP_KEY="<#EUM_APP_KEY#>" --variable INTERACTION_CAPTURE_MODE=<see modes in table below> --variable SCREENSHOTS_ENABLED=<true|false> --variable LOGGING_LEVEL=[0-6] --variable COLLECTOR_URL="http(s)://<on-prem_eum-server_url>:<PORT>" --variable SCREENSHOT_URL="http(s)://<on-prem_screenshot_service-url>" --save
CPPCapture Mode Value Description Capture None 0 No user interactions are captured. Button Pressed 1 Button presses are captured. Table Cell Selected 2 Table cell selections are captured. Text Field Selected 4 Text field selections are captured. Text View Selected 8 Text view selections are captured. All -1 All user interactions are captured. Capture Mode Value Description Capture None 0 No user interactions are captured. Button Pressed 1 Button presses are captured. Edit Text Selected 2 Selection of edited text is captured. List Item Selected 4 Selection of list item is captured. All -1 All user interactions are captured. By default, the Cordova Plugin will use
http://google.com/
to test the connectivity of Cordova iOS applications You can, however, use a different URL to test the connectivity by setting the variableREACHABILITY_HOST
to the URL. In the example below, the Cordova Plugin is configured to usehttp://example.com
to test the connectivity of the Cordova iOS application.ionic cordova plugin add appd-plugin-eum-mobile --variable APP_KEY="<#EUM_APP_KEY#>" --variable REACHABILITY_HOST="http://example.com" --variable SCREENSHOTS_ENABLED=<true|false> --variable LOGGING_LEVEL=[0-6] --save
JS
Build the mobile app:
ionic cordova build [android, ios]
JS
From the root directory of your PhoneGap application, run the commands below to install the plugin. See the PhoneGap plugin documentation for more information.
Replace the values in brackets with the configurations for your app and run the command to add the configured plugin.
For SaaS deployments:phonegap cordova plugin add appd-plugin-eum-mobile --variable APP_KEY="<#EUM_APP_KEY#>" --variable SCREENSHOTS_ENABLED=<true|false> --variable LOGGING_LEVEL=[0-6] --save
JSFor on-prem deployments, replace the value for the variable
COLLECTOR_URL
with the URL to your EUM Server and the value forSCREENSHOT_URL
with the URL to your on-prem Screenshot Service.phonegap cordova plugin add appd-plugin-eum-mobile --variable APP_KEY="<#EUM_APP_KEY#>" --variable SCREENSHOTS_ENABLED=<true|false> --variable LOGGING_LEVEL=[0-6] --variable COLLECTOR_URL="http(s)://<on-prem_eum-server_url>:<PORT>" --variable SCREENSHOT_URL="http(s)://<on-prem_screenshot_service-url>" --save
JS(Optional) You can also set variables to enable user interaction capture mode (iOS/Android) and troubleshoot the network connectivity of Cordova iOS applications.
The interaction capture mode is on by default, but you can disable it by setting the variable
INTERACTION_CAPTURE_MODE
to0
or specify the desired capture mode for the platform (see the interaction mode values for iOS and Android in the table below). SettingINTERACTION_CAPTURE_MODE
only controls capturing of webview interactions. If you setINTERACTION_CAPTURE_MODE
to0
, interactions with webviews will no longer be captured. However, interactions with native UI elements, such as UI Buttons under iOS, will still be captured, as they always are captured by the underlying native agent for each platform.phonegap cordova plugin add appd-plugin-eum-mobile --variable APP_KEY="<#EUM_APP_KEY#>" --variable INTERACTION_CAPTURE_MODE=<see modes in table below> --variable SCREENSHOTS_ENABLED=<true|false> --variable LOGGING_LEVEL=[0-6] --save
JSCapture Mode Value Description Capture None 0 No user interactions are captured. Button Pressed 1 Button presses are captured. Table Cell Selected 2 Table cell selections are captured. Text Field Selected 4 Text field selections are captured. Text View Selected 8 Text view selections are captured. All -1 All user interactions are captured. Capture Mode Value Description Capture None 0 No user interactions are captured. Button Pressed 1 Button presses are captured. Edit Text Selected 2 Selection of edited text is captured. List Item Selected 4 Selection of list item is captured. All -1 All user interactions are captured. By default, the Cordova Plugin will use
http://google.com
to test the connectivity of Cordova iOS applications You can, however, use a different URL to test the connectivity by setting the variableREACHABILITY_HOST
to the URL. In the example below, the Cordova Plugin is configured to usehttp://example.com
to test the connectivity of the Cordova iOS application.phonegap cordova plugin add appd-plugin-eum-mobile --variable APP_KEY="<#EUM_APP_KEY#>" --variable REACHABILITY_HOST=http://example.com --variable SCREENSHOTS_ENABLED=<true|false> --variable LOGGING_LEVEL=[0-6] --save
JS
Build the mobile app:
phonegap cordova build [android, ios]
JS
Customize the Cordova Application Instrumentation
See Customize the Cordova Application showing how to use the Cordova SDK through examples and brief explanations.
Update Cordova Agent Configurations
To update the configurations set when you first added the Cordova plugin to your application, the suggested practice is to remove the values for configuration values and then add new configuration values.
See the following examples:
Change the App Key
To change the app key for your Ionic or PhoneGap applications:
Remove the old value for the variable
APP_KEY
with theremove
command:cordova plugin remove --variable APP_KEY="old-app-key" appd-plugin-eum-mobile
BASHAdd new value for the variable
APP_KEY
with theadd
command. Be sure to include the variables that you set when you first added the plugin (represented by<variable_list>
below). For example, if you setREACHABILITY_HOST=http://example.com
when you first added the plugin, you will need to reset the variable when running theadd
command again.cordova plugin add --variable APP_KEY="new-app-key" <variable_list> appd-plugin-eum-mobile
BASH
Change the App Name
To change the name of your Ionic or PhoneGap applications:
Remove the old value for the variable
APP_NAME
with theremove
command:cordova plugin remove --variable APP_NAME="old-app-name" appd-plugin-eum-mobile
BASHAdd new value for the variable
APP_NAME
with theadd
command. Be sure to include the variables that you set when you first added the plugin (represented by<variable_list>
below). For example, if you setREACHABILITY_HOST=http://example.com/
when you first added the plugin, you will need to reset the variable when running theadd
command again.cordova plugin add --variable APP_NAME="new-app-name" <variable_list> appd-plugin-eum-mobile
BASH