@dynatrace/cordova-plugin
This plugin gives you the ability to use the Dynatrace instrumentation in your hybrid application (Cordova, Ionic, ..). It uses the Mobile Agent, the JavaScript Agent. The Mobile Agent will give you all device specific values containing lifecycle informat
$ cnpm install @dynatrace/cordova-plugin 
SYNC missed versions from official npm registry.

N|Solid

Dynatrace Cordova Plugin

This plugin gives you the ability to use the Dynatrace instrumentation in your hybrid application (Cordova, Ionic, ..). It uses the Mobile Agent and the JavaScript Agent. The Mobile Agent will give you all device specific values containing lifecycle information and the JavaScript Agent will allow you to manually instrument your JavaScript/TypeScript code out of the box (TypeScript definitions included). The JavaScript Agent will cover the network calls (depending on your used libraries) and will automatically detect them.

Versioning

The dynatrace-cordova-plugin is the old version of this plugin. Consider it deprecated. Only use @dyntrace/cordova-plugin from now on, if you want to have the newest version. If you are upgrading from the old version have a look at our migration guide which is explaining what has changed. The versioning changed as well, the old 7.2.x was based on the versions of the Mobile Agents used. Now the plugin has its own versioning. The version of the used Mobile Agent can be seen here.

Requirements

  • For Linux users: Bash (Only a requirement if you are using Linux)
  • For Android users: Minimum SDK version 15
  • For iOS users: Minimum iOS 8
  • For JavaScript Agent: access to API of cluster
  • Android: Gradle > 5.0 (How to upgrade?)

Agent Versions

This agent versions are configured in this plugin:

  • iOS Agent: 8.189.1.1008
  • Android Agent: 8.189.1.1001

Quick Setup

  1. Installation of the plugin
  2. Configuration with Dynatrace
  3. Make a build
  4. Validate instrumentation

Advanced Topics

Quick Setup

1. Installation of the plugin

To install the plugin in your Cordova based project you must enter the following command in the root directory of your cordova based project. E.g. :

cordova plugin add @dynatrace/cordova-plugin --save

2. Configuration with Dynatrace

If you want to instrument your Cordova application just go to your Dynatrace WebUI and select the menu point "Deploy Dynatrace". Choose to setup mobile monitoring and select Cordova. Afterwards it is possible for you to add the Web part (JavaScript Agent) automatically and download the dynatrace.config.js file.

This file should be placed in the root of your project (same place where the package.json is stored). If the file is not available the instrumentation will not work.

Ionic Webview for Cordova: If you are using the Ionic Web View for Cordova (cordova-plugin-ionic-webview) you need to make sure you set correct cookie domain.

3. Make a build

After starting the Cordova or Ionic build, with ionic cordova build android or cordova build android the instrumentation will be handled by the plugin. Of course android can be substitued with ios platform. If you have trouble with not finding the .gradle, .plist or dynatrace.config.js file you can specify those via custom arguments. E.g. cordova build android --config=C:\config\dynatrace.config.js is a valid command and will try to use the configuration stored in the \config folder.

4. Validate instrumentation

This section should explain what data should be visible after applying the plugin. The most important aspect is that there should be a combined session. We talk about a combined session when there are Mobile and Web actions within one session.

N|Solid

This screen shows what a combined sample user session should roughly look like. The session contains a Mobile action and some Web(Load, XHR) actions. Those first two actions should always be visible in your application session. The first one defines the native application startup ("Loading EasyTravel"). The second one defines the first load of the index.html of your hybrid application ("Loading of page ..").

Advanced Topics

Cordova configuration

module.exports = {
    cordova : {
        debug : false,
		autoUpdate : true,
		cspURL: "http://..."
	},
	...
}

Auto update

The default value for autoUpdate is true. This means with every build the plugin will try to download a new JS Agent version. If you set this to false, the JS Agent will not be updated by the plugin, even if there is a newer configuration available.

Content-Security-Policy url

There is flag for updating the CSP (Content Security Policy). By default this value is set and the plugin will modify the CSP. The URL in the cspURL property will be placed into a CSP configuration (if available) in your index.html. This will allow/unblock connections to the Dynatrace server. If you don't want to use this feature, remove the cspURL property and the plugin will not modify the CSP configuration.

Debug

The default value is false. This property generates more log output and is sometimes necessary if you need to find the cause for a non-working plugin.

Native configuration (iOS & Android)

module.exports = {
    android : {
		config : `...`
    },

    ios : {
        config : `...`
    }  
}

The native configuration contain all the settings which are necessary for the Mobile Agent(s). You can find all the available properties in the documentation of the mobile agent.

The content of the ios.config property will be directly copied to the plist file. The content of the android.config property will be directly copied to the gradle file.

Hybrid related configuration

Here we list the configuration which is especially important if you are instrumenting a Hybrid application.

module.exports = {
    android : {
		config : `
		dynatrace{
			configurations {
				defaultConfig{
					autoStart{
						...
					}
					hybridWebView{
						enabled true
						domains '.example.com', '.dynatrace.com'
					}
				}
			}
		}
		`
    },

    ios : {
		config : `
		<DTXHybridApplication>true</DTXHybridApplication>
		<DTXSetCookiesForDomain>.example.com,dynatrace.com</DTXSetCookiesForDomain>
		`
    }  
}
  • DTXHybridApplication or hybridWebView.enabled : Set to true if you have a Hybrid application. The default value is false.

  • DTXSetCookiesForDomain or hybridWebView.domains : For hybrid applications using the JavaScript agent, cookies need to be set for each instrumented domain or server the application communicates with. You can specify domains, host or IP addresses. Domains or sub-domains must start with a dot. Separate the list elements with a comma.

JavaScript Agent configuration

Basically all needed properties for the JavaScript Agent are predefined by the downloadable dynatrace.config.js. The three available properties are url and allowanycert, which is ignoring certificate issues when downloding the JavaScript Agent.

Allow any certificate

If you have got an issue with downloading the JavaScript Agent and see an error messages with a certificate issue like this:

Could not download the JavaScript Agent! - Could not download agent optionsError: unable to verify the first certificate

You are able to bypass those errors at your OWN RISK by using allowanycert: true within the js property. This will ignore the fact that the SSL connection is not secure (e.g. because of invalid certificate) and will download the JavaScript Agent anyways. An example would look like this:

module.exports = {
    js : {
        url : `...`,
        allowanycert: true
    },
}

Manual instrumentation

The JavaScript Agent interface will be provided by the JavaScript Agent, it can be used everywhere in your application by simply calling dtrum.

This gives you the possibility to instrument your code even further by additional manual instrumentation. If you like to know more about the manual instrumentation have a look into the Dynatrace documentation. It is also possible to look into the definition file (plugins/dynatrace-cordova-plugin/typings/main.d.ts) to see the API documentation.

Create manual action

To create a manual action that is called "MyButton tapped" you just need to use the following code below. The leaveAction will close the action again. It is possible to report values for this action before closing, see next section Report Values.

"enterAction"(actionName: string, actionType: string, startTime?: number, sourceUrl?: string, sourceTitle?: string): number;

"leaveAction"(actionId: number, stopTime?: number, startTime?: number): void;
var action = dtrum.enterAction('simple action', 'click', null, 'http://whatever.com');
//do something here
dtrum.leaveAction(action);

Report error

For any open action you can report certain values. The following APIs are available on the Action:

reportError(error: Error | string, parentActionId?: number): void;

dtrum.reportError('Error: Hello World with AJAX!');

Identify user

It is possible to identify a user and tag the current session with a name. You need to do the following call:

dtrum.identifyUser("User XY");

More examples

The above functionalities are only a small part of how you can use the API. If you want to know more you can visit the Settings in the WebUI.

N|Solid

Typings file for API

To use the interface of the JavaScript Agent directly you must specify the typing definition file in the tsconfig.json. Add the following block to the tsconfig.json:

"files": ["plugins/dynatrace-cordova-plugin/typings/main.d.ts"] 

If "files" is already defined, just add the path to the already defined ones.

Manual instrumentation - Mobile Agent

The Mobile Agent interface will be provided by the Mobile Agent, so it can be used everywhere in your application by simply calling dynatraceMobile.

End session

In a hybrid scenario it is only possible for the mobile agent to end a session/visit. That's why we expose the endVisit function of the Mobile Agent.

The interface is available with the name dynatraceMobile (TypeScript definitions included). Calling dynatraceMobile.endVisit(successCallback, errorCallback) will end the session/visit. Example how this call looks like:

dynatraceMobile.endVisit(() => {
	// Success
	console.log("Visit was ended!");
}, () => {
	// Error
	console.log("Visit wasn't ended!");
});

Typings file for API

To use the interface of the Mobile Agent directly you must specify the typing definition file in the tsconfig.json. Add the following block to the tsconfig.json:

"files": ["plugins/dynatrace-cordova-plugin/typings/main.d.ts"] 

If "files" is already defined, just add the path to the already defined ones.

Ionic Web View for Cordova

The Mobile agent usually sets cookies on the correct domain but the cordova-plugin-ionic-webview uses different domains. Those domains need to be added in the configuration. If you defined a custom hostname you need to take this into account as well for choosing the correct domain. A sample configuration which takes care about the default domain for cordova-plugin-ionic-webview looks like the following:

module.exports = {
    android : {
		config : `
		dynatrace{
			configurations {
				defaultConfig{
					autoStart{
						...
					}
					hybridWebView{
						enabled true
						domains 'http://localhost', '.other-domain-you-want-to-specify.com'
					}
				}
			}
		}
		`
    },

    ios : {
		config : `
		<DTXHybridApplication>true</DTXHybridApplication>
		<DTXSetCookiesForDomain>ionic://localhost,.other-domain-you-want-to-specify.com</DTXSetCookiesForDomain>
		`
    }  
}

Download older plugin version

The version can be used like in any other npm package. You just have to use the @ sign if you want to specify a certain version:

cordova plugin add @dynatrace/cordova-plugin@1.191.1 --save

This will download the version 1.191.1 of our plugin. In general we recommend you to always use the latest version.

Custom arguments for instrumentation script

Our scripts assumes that the usual react native project structure is given. The following arguments can be specified for our instrumentation script if the project structure is different.

  • --gradle=C:\MyReactAndroidProject\build.gradle - the location of the root build.gradle file. We will assume that the other gradle file resides in /app/build.gradle. This will add the whole agent dependencies automatically for you and will update the configuration.
  • --plist=C:\MyReactIOSProject\projectName\info.plist - Tell the script where your info.plist file is. The plist file is used for updating the configuration for the agent.
  • --config=C:\SpecialFolderForDynatrace\dynatrace.config.js - If you have not got your config file in the root folder of the React Native project but somewhere else.

Example:

cordova build android --config=C:\SpecialFolderForDynatrace\dynatrace.config.js

If you use Ionic make sure to use -- :

ionic cordova build android -- --config=C:\SpecialFolderForDynatrace\dynatrace.config.js

Migration from old plugin

The differences to the old dynatrace-cordova-plugin are very small. There are three differences:

  • The Android instrumentation is now executed via gradle. This makes the build way faster and more stable. The new plugin is now automatically modifying your gradle files.
  • The plugin raised the requirments for Gradle to version 5. This can easily be upgraded in your project by changing one line.
  • The format of the configuration changed from dynatrace.config to dynatrace.config.js. The new format can be downloaded via WebUI. If you had some custom settings in Android take a look in the detailed documentation. The format of iOS basically stayed the same.

Updating to Gradle 5

Updating Gradle only affects your Android build. To Update your project to Gradle 5 you have to modify one file in your Android folder.

  • ProjectFolder\android\cordova\lib\builders\ProjectBuilder.js Contains the following line:
var distributionUrl = process.env['CORDOVA_ANDROID_GRADLE_DISTRIBUTION_URL'] || 'https\\://services.gradle.org/distributions/gradle-4.3.10-all.zip';

make sure you insert some other version like 5.4.1 here:

var distributionUrl = process.env['CORDOVA_ANDROID_GRADLE_DISTRIBUTION_URL'] || 'https\\://services.gradle.org/distributions/gradle-5.4.1-all.zip';

If you having trouble with this option you can always set the global process property CORDOVA_ANDROID_GRADLE_DISTRIBUTION_URL :

process.env['CORDOVA_ANDROID_GRADLE_DISTRIBUTION_URL'] = 'https\\://services.gradle.org/distributions/gradle-5.4.1-all.zip';

Native OneAgent debug logs

If your application starts but you see no data (or the session is not merged), you probably need to dig deeper to find out why the OneAgents aren't sending any data. Opening up a support ticket is a great idea, but gathering logs first is even better.

Android

Add the following configuration snippet to your other configuration in dynatrace.config.js right under the autoStart block (the whole structure is visible, so you know where the config belongs):

android: {
  config: `
    dynatrace {
      configurations {
        defaultConfig {
          autoStart{
            ...
          }
          debug.agentLogging true
        }
      }
    }
  `
}

iOS

Add the following configuration snippet to your other configuration in dynatrace.config.js (the whole structure is visible, so you know where the config belongs):

ios: {
  config: `
  <key>DTXLogLevel</key>
  <string>ALL</string>
  `
}

Official documentation

Troubleshooting and current restrictions:

Basically if you have problems with the plugin please have a look into the logs. They will tell you what went wrong. The logs can be found in the plugins folder of your Cordova project. There is a directory called "Logs".

  • If you see a message like "Error: Could not download agent file: Error: self signed certificate in certificate chain" try to switch the JavaScript Agent configuration from HTTPS to HTTP.
  • If you use live reload (e.g. ionic cordova run android -l) be aware that Ionic/Cordova doesn't use files from the platform folder, so the JavaScript Agent injection will not take place, as we only instrument the temporary platform folder. You are still able to add the dtAgent.js manually by adding <script src="assets/dtAgent.js"> to your index.html (in the source directory). Auto-Instrumentation with the Mobile Agent still takes place.
  • If you have problems downloading the JavaScript Agent and you get error messages that the JavaScript Agent can not be downloaded you probably don't have access to the API or there is a certificate issue. If this is the certificate use the allowanycert feature. In any other case a workaround is possible to change autoUpdate to false (in dynatrace.config.js) and download the full Javascript Agent and copy it to files/dtAgent.js - With this the plugin will not download a new agent and will use the one that is in the files folder.

Changelog

1.192.0

  • Fix for Installation/Removing issues

1.191.2

  • Android Instrumentation changed to Gradle
  • New Mobile Agents (> 8.x)

Current Tags

  • 1.192.0                                ...           latest (a month ago)

4 Versions

  • 1.192.0                                ...           a month ago
  • 1.191.2                                ...           2 months ago
  • 1.191.1                                ...           2 months ago
  • 1.191.0                                ...           2 months ago
Downloads
Today 0
This Week 0
This Month 0
Last Day 0
Last Week 0
Last Month 14
Dependencies (4)
Dev Dependencies (12)
Dependents (0)
None

Copyright 2014 - 2017 © taobao.org |