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 and the Javascript Bridge. The Mobile Agent will give you all device specific values con
npm install dynatrace-cordova-outsystems-plugin
cordova plugin add dynatrace-cordova-plugin --save
`
This will always download the latest version of the plugin.
The old version of the plugin didnt have any versioning as it downloaded the Mobile Agent on the fly. This has been changed now since update scripts are very inconvenient and Cordova plugins were not designed that way.
Now the version can be used like 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@7.0.6-1002 --save
`
The version in front (e.g. 7.0.6) is the version of the Mobile agent which is directly bundled with the plugin. The number at the end (1002) represents the build number, in this case the second build. This number will rise when we fix something in the plugin.
Configuration with Dynatrace
The plugin can be used with both Dynatrace or AppMon, but in this section it will be explained how to use it with Dynatrace (If you are using AppMon then click here).
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 (JSAgent) automatically and download the dynatrace.config file.
This file should be place in the root of your project (same place where the config.xml is stored). If the file is not available the instrumentation will not work. Be aware that a lot of values are containing a placeholder like Application ID where you must enter your Dynatrace data.
Example of a dynatrace.config file:
`
true
Application ID
Beacon Url
true
debug
ALL
https://XXX.com/api/v1/rum/jsInlineScript/APPLICATION-XXXXX?Api-Token=YOUR_TOKEN
..
`
In this example there are 3 different properties configured for the Mobile Agent (Native Agent). All properties which are available in the Mobile Agent can be used in the \
The properties DTXLogLevel, DTXBeaconURL and DTXApplicationId are defined as global properties (not within platform tag) and will therefore be applied to both platforms (Android and iOS). The property DTXHybridApplication is only set for the Android platform and will only be applied there. iOS will not be affected by DTXHybridApplication. In general, all properties which are defined in a platform tag are overriding a duplicate global value. If for example DTXApplicationId is defined as a global property as well as an Android platform property, always the platform property will have a higher priority.
After this the configuration is finished, you can skip to the section: "Make a Build".
Configuration with AppMon
The plugin can be used with both Dynatrace or AppMon, but in this section it will be explained how to use it with AppMon (If you are using Dynatrace then skip to the next chapter). This is a sample configuration for AppMon which you must insert in a file called dynatrace.config. This file name can not be changed. This file should be place in the root of your project (same place where the config.xml is stored). If the file is not available the instrumentation will not work. Be aware that a lot of values are containing a placeholder like http://agent.startup.path.com:PORT/ where you must enter your AppMon data.
`
true
http://agent.startup.path.com:PORT/
Application ID
true
debug
ALL
http://url.com:PORT/
Application Name
Profile Name
..
..
`
Basically the DTXAgentStartupPath is making the difference, because this property is only needed by AppMon. The script knows now that you want to use AppMon and will search for the AppMon configuration in the JavaScript Agent tag (\
In this example there are 4 different properties configured for the Mobile Agent (native agent). The 3 properties DTXLogLevel, DTXAgentStartupPath and DTXApplicationId are defined as global properties (not within platform tag) and will therefore be applied to both platforms (Android and iOS). The property DTXHybridApplication is only set for the Android platform and will only be applied there. iOS will not be affected by DTXHybridApplication. In general, all properties which are defined in a platform tag are overriding a duplicate global value. If for example DTXApplicationId is defined as a global property as well as an Android platform property, always the platform property will have a higher priority.
The properties DTXAgentStartupPath and DTXApplicationId are the minimum requirement if you want to configure the Mobile Agent for AppMon. If one of those two is not available, an instrumentation with the Mobile Agent will fail.
The JavaScript Agent tag contains the settings for downloading the JavaScript Agent. The url in the JSAGENT tag should be filled with the url and port of your AppmonServer where the REST API can be accessed. To check if http://url.com:PORT/ is correct, the following link should show you the documentation for the REST API:
`
http://url.com:PORT/api-docs/current/index.html
`
From the values in the JSAGENT tag we will construct a url which looks like this:
`
http://url.com:PORT/profiles/Your_Profile_Name/applications/Your_Application_Name/javascriptagent/initcode
`
All of these settings can be separated in an extra file outside the dynatrace.config (See Section: Configuration - Credentials). The JavaScript Agent should additionally be configured at the server to show web requests correctly. Under "System Profile" you will find a menu point called "User Experience". Select the correct application and activate the AngularJS feature for the JavaScript Agent. Additionally, you must configure the Agent location and the Monitor request path.
After this the configuration is finished, you can skip to the section: "Make a Build".
General - Properties
The general settings contains the AUTO_UPDATE property. If you set this to false, the JS Agent will not make an update, even if there is a newer configuration.
Additionally there is flag for updating the CSP (Content Security Policy). By default this is turned on and the plugin will modify the CSP to allow connections to the Dynatrace/AppMon server. If you don't like this option, just add into the tag:
`
false
`
Native - Properties
The native settings contain all the properties which are necessary for the Mobile Agent(s). You can find all the available properties in the documentation of the mobile agent, see the documentation.
Here we list the properties which are especially important if you are instrumenting a Hybrid application.
DTXHybridApplication* : Set to true if you have a Hybrid application. The default value is false.
`
true
`
DTXSetCookiesForDomain* : 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.
`
dynatrace.com,dynatrace.at
`
JavaScript Agent - Properties
Basically all properties for the JSAgent are given by the Dynatrace WebUI. Those are url and token. In AppMon you need to do this configuration yourself. As seen in the configuration part you need to define url, appName, profile, user and password for AppMon. Be aware that you can exclude those configs into a seperate file, this is explained in the next section.
$3
If you have got an issue with downloading the JSAgent and see an error messages with a certificate issue like this:
`
Could not download the JSAgent! - Could not download agent optionsError: unable to verify the first certificate
`
You are able to bypass those errors at your OWN RISK by using within the tag. This will ignore the fact that the SSL connection is not secure (e.g. because of invalid certificate) and will download the JSAgent anyways.
Configuration - Credentials
If you don't want to enter credentials in the dynatrace.config there is another way provided by the plugin. Just copy everything within the JavaScript Agent tag including the JavaScript Agent tag (\) to a file called dynatrace.credentials. This file should be stored in the root of the project (same place where the dynatrace.config is stored). The credentials will be taken from this file by the configuration script. This file can be easily added to a .gitignore. Therefore, no credentials will ever be committed.
Manual Instrumentation - JavaScript Agent
The JavaScript Agent interface will be provided by the JavaScript Agent, so it can be used everywhere in your application by simply calling dynaTrace (Or if you use AppMon you need to use dtrum.). A possible call might be:
`
// Dynatrace
dynaTrace.enterAction(..);
// AppMon
dtrum.enterAction(..);
`
This gives you the possibility to instrument your code even further by 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 (described below) to see the API documentation.
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
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!");
});
`
Make a build
After starting the Cordova or Ionic build, with cordova build android the instrumentation will be handled by the plugin. Of course android can be substitued with any other platform. Of course you can also use cordova run android.
$3
The final message of the Android build might look similiar to this:
`
Original: "C:\AndroidBuildFolder\outputs\apk\debug\app-debug.apk"
Instrumented: C:\AndroidBuildFolder\outputs\apk\debug\app-debug\dist\app-debug.apk
Instrumented and zipaligned: C:\AndroidBuildFolder\outputs\apk\debug\app-debug\dist\app-debug-zipaligned.apk
Instrumented, signed and zipaligned: C:\AndroidBuildFolder\outputs\apk\debug\app-debug\dist\app-debug-final.apk
``