@dynatrace/cordova-plugin
Advanced tools
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
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.
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.
This agent versions are configured in this 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
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.
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.
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.
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 ..").
module.exports = {
cordova : {
debug : false,
autoUpdate : true,
cspURL: "http://..."
},
...
}
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.
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.
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.
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.
Here we list the configuration which is especially important if you are instrumenting a Hybrid application.
module.exports = {
android : {
config : `
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.
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.
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
},
}
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.
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);
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!');
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");
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.
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.
The Mobile Agent interface will be provided by the Mobile Agent, so it can be used everywhere in your application by simply calling dynatraceMobile.
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!");
});
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.
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.
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
The differences to the old dynatrace-cordova-plugin are very small. There are three differences:
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 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';
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".
1.191.0
FAQs
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
The npm package @dynatrace/cordova-plugin receives a total of 243 weekly downloads. As such, @dynatrace/cordova-plugin popularity was classified as not popular.
We found that @dynatrace/cordova-plugin demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 0 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
A malicious npm package disguised as a WhatsApp client is exploiting authentication flows with a remote kill switch to exfiltrate data and destroy files.
Security News
PyPI now supports digital attestations, enhancing security and trust by allowing package maintainers to verify the authenticity of Python packages.
Security News
GitHub removed 27 malicious pull requests attempting to inject harmful code across multiple open source repositories, in another round of low-effort attacks.