Related pages:

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.

  1. Run the following command:

    (ionic) cordova platform add ios
    CODE

  2. Verify the log output returns:

    Using WkWebView
    CODE
  3. If the log output returns Using UIWebView, you must manually change it to Using 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.

  1. 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
    JS

    For on-prem deployments, replace the value for the variable COLLECTOR_URL with the URL to your EUM Server and the value for SCREENSHOT_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

  2. (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. 

    1. The interaction capture mode is on by default, but you can disable it by setting the variable INTERACTION_CAPTURE_MODE to 0 or specify the desired capture mode for the platform (see the interaction mode values for iOS and Android in the table below). Setting INTERACTION_CAPTURE_MODE only controls capturing of webview interactions. If you set INTERACTION_CAPTURE_MODE to 0, 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
      CPP
      Capture ModeValueDescription
      Capture None0No user interactions are captured.
      Button Pressed1Button presses are captured.
      Table Cell Selected2Table cell selections are captured.
      Text Field Selected4Text field selections are captured.
      Text View Selected8Text view selections are captured.
      All-1All user interactions are captured.
      Capture ModeValueDescription
      Capture None0 No user interactions are captured.
      Button Pressed1  Button presses are captured.
      Edit Text Selected2 Selection of edited text is captured.
      List Item Selected4Selection of list item is captured.
      All-1All user interactions are captured.

    2. 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 variable REACHABILITY_HOST to the URL. In the example below, the Cordova Plugin is configured to use http://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

  3. 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.

  1. 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
    JS

    For on-prem deployments, replace the value for the variable COLLECTOR_URL with the URL to your EUM Server and the value for SCREENSHOT_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

  2. (Optional) You can also set variables to enable user interaction capture mode (iOS/Android) and troubleshoot the network connectivity of Cordova iOS applications.

    1. The interaction capture mode is on by default, but you can disable it by setting the variable INTERACTION_CAPTURE_MODE to 0 or specify the desired capture mode for the platform (see the interaction mode values for iOS and Android in the table below). Setting INTERACTION_CAPTURE_MODE only controls capturing of webview interactions. If you set INTERACTION_CAPTURE_MODE to 0, 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
      JS
      Capture ModeValueDescription
      Capture None0No user interactions are captured.
      Button Pressed1Button presses are captured.
      Table Cell Selected2Table cell selections are captured.
      Text Field Selected4Text field selections are captured.
      Text View Selected8Text view selections are captured.
      All-1All user interactions are captured.
      Capture ModeValueDescription
      Capture None0 No user interactions are captured.
      Button Pressed1  Button presses are captured.
      Edit Text Selected2 Selection of edited text is captured.
      List Item Selected4Selection of list item is captured.
      All-1All user interactions are captured.

    2. 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 variable REACHABILITY_HOST to the URL. In the example below, the Cordova Plugin is configured to use http://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

  3. 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:

  1. Remove the old value for the variable APP_KEY with the remove command:

    cordova plugin remove --variable APP_KEY="old-app-key" appd-plugin-eum-mobile
    BASH

  2. Add new value for the variable APP_KEY with the add 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 set REACHABILITY_HOST=http://example.com when you first added the plugin, you will need to reset the variable when running the add 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:

  1. Remove the old value for the variable APP_NAME with the remove command:

    cordova plugin remove --variable APP_NAME="old-app-name" appd-plugin-eum-mobile
    BASH

  2. Add new value for the variable APP_NAME with the add 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 set REACHABILITY_HOST=http://example.com/ when you first added the plugin, you will need to reset the variable when running the add command again.

    cordova plugin add --variable APP_NAME="new-app-name" <variable_list> appd-plugin-eum-mobile
    BASH