Cordova File Download Plugin

Posted on by admin

A Cordova plugin provides a JavaScript interface to the native components. These plugins consist of various elements that are as follows: Common JavaScript Interface; A manifest file, i.e., xml; A native code; Basic Structure of Cordova Plugin. A basic structure of the Cordova plugin defines a hierarchy of the consisting directories from top to.

Cordova-plugin-file Installation Supported Platforms Where to Store Files File System Layouts iOS File System Layout Android File System Layout OS X File System Layout Windows File System Layout Android Quirks Android Persistent storage location Slow recursive operations for /androidasset Permisson to write to external storage when it's not. The cordova-plugin-file plugin gives us access to the users’s file system, and the cordova-plugin-file-opener2 plugin helps us with opening files using an external application (e.g word, excel, etc.). We are using the file-saver when we are running inside of the browser. Cordova-plugin-downloader Cordova plugin to download, store and unzip files with no cordova-file-transfer dependency. Cordova-file-transfer was recently depreciated. Inspired by cordova-plugin-fastrde-downloader but with less features. Compatibility Android 4.4+ iOS 10+ Cordova 5.0+ Installation cordova plugin add cordova-plugin-downloader. $ cordova plugin add plugins.value We'll be adding the cordova file plugin (for easy device storage access) and the camera plugin, which gives access to the device's camera to make photos and videos. $ cordova plugin add cordova-plugin-file cordova-plugin-camera -save Remember: using the -save argument writes your settings to the config.xml.

title: File Transfer

description: Upload and download files.

AndroidiOSWindows 8.1 StoreWindows 8.1 PhoneWindows 10 StoreTravis CI

This plugin allows you to upload and download files.

This plugin defines global FileTransfer, FileUploadOptions constructors. Although in the global scope, they are not available until after the deviceready event.

To get a few ideas, check out the sample at the bottom of this page or go straight to the reference content.

Report issues with this plugin on the Apache Cordova issue tracker

Reference

Installation

Supported Platforms

  • Amazon Fire OS
  • Android
  • BlackBerry 10
  • Browser
  • Firefox OS**
  • iOS
  • Windows Phone 7 and 8*
  • Windows

* Do not support onprogress nor abort()

** Do not support onprogress

The FileTransfer object provides a way to upload files using an HTTPmulti-part POST or PUT request, and to download files.

Properties

  • onprogress: Called with a ProgressEvent whenever a new chunk of data is transferred. (Function)

Methods

  • upload: Sends a file to a server.

  • download: Downloads a file from server.

  • abort: Aborts an in-progress transfer.

upload

Parameters:

  • fileURL: Filesystem URL representing the file on the device or a data URI. For backwards compatibility, this can also be the full path of the file on the device. (See Backwards Compatibility Notes below)

  • server: URL of the server to receive the file, as encoded by encodeURI().

  • successCallback: A callback that is passed a FileUploadResult object. (Function)

  • errorCallback: A callback that executes if an error occurs retrieving the FileUploadResult. Invoked with a FileTransferError object. (Function)

  • options: Optional parameters (Object). Valid keys:

    • fileKey: The name of the form element. Defaults to file. (DOMString)
    • fileName: The file name to use when saving the file on the server. Defaults to image.jpg. (DOMString)
    • httpMethod: The HTTP method to use - either PUT or POST. Defaults to POST. (DOMString)
    • mimeType: The mime type of the data to upload. Defaults to image/jpeg. (DOMString)
    • params: A set of optional key/value pairs to pass in the HTTP request. (Object, key/value - DOMString)
    • chunkedMode: Whether to upload the data in chunked streaming mode. Defaults to true. (Boolean)
    • headers: A map of header name/header values. Use an array to specify more than one value. On iOS, FireOS, and Android, if a header named Content-Type is present, multipart form data will NOT be used. (Object)
  • trustAllHosts: Optional parameter, defaults to false. If set to true, it accepts all security certificates. This is useful since Android rejects self-signed security certificates. Not recommended for production use. Supported on Android and iOS. (boolean)

Example

Example with Upload Headers and Progress Events (Android and iOS only)

FileUploadResult

A FileUploadResult object is passed to the success callback of theFileTransfer object's upload() method.

Properties

  • bytesSent: The number of bytes sent to the server as part of the upload. (long)

  • responseCode: The HTTP response code returned by the server. (long)

  • response: The HTTP response returned by the server. (DOMString)

  • headers: The HTTP response headers by the server. (Object)

    • Currently supported on iOS only.

iOS Quirks

  • Does not support responseCode or bytesSent.

  • Does not support uploads of an empty file with chunkedMode=true and multipartMode=false.

Browser Quirks

  • withCredentials: boolean that tells the browser to set the withCredentials flag on the XMLHttpRequest

Windows Quirks

  • An option parameter with empty/null value is excluded in the upload operation due to the Windows API design.

  • chunkedMode is not supported and all uploads are set to non-chunked mode.

download

Parameters:

  • source: URL of the server to download the file, as encoded by encodeURI().

  • target: Filesystem url representing the file on the device. For backwards compatibility, this can also be the full path of the file on the device. (See Backwards Compatibility Notes below)

  • successCallback: A callback that is passed a FileEntry object. (Function)

  • errorCallback: A callback that executes if an error occurs when retrieving the FileEntry. Invoked with a FileTransferError object. (Function)

  • trustAllHosts: Optional parameter, defaults to false. If set to true, it accepts all security certificates. This is useful because Android rejects self-signed security certificates. Not recommended for production use. Supported on Android and iOS. (boolean)

  • options: Optional parameters, currently only supports headers (such as Authorization (Basic Authentication), etc).

Example

WP8 Quirks

  • Download requests is being cached by native implementation. To avoid caching, pass if-Modified-Since header to download method.

Browser Quirks

  • withCredentials: boolean that tells the browser to set the withCredentials flag on the XMLHttpRequest

abort

Aborts an in-progress transfer. The onerror callback is passed a FileTransferError object which has an error code of FileTransferError.ABORT_ERR.

Example

FileTransferError

A FileTransferError object is passed to an error callback when an error occurs.

Properties

  • code: One of the predefined error codes listed below. (Number)

  • source: URL to the source. (String)

  • target: URL to the target. (String)

  • http_status: HTTP status code. This attribute is only available when a response code is received from the HTTP connection. (Number)

  • body Response body. This attribute is only available when a response is received from the HTTP connection. (String)

  • exception: Either e.getMessage or e.toString (String)

Constants

  • 1 = FileTransferError.FILE_NOT_FOUND_ERR
  • 2 = FileTransferError.INVALID_URL_ERR
  • 3 = FileTransferError.CONNECTION_ERR
  • 4 = FileTransferError.ABORT_ERR
  • 5 = FileTransferError.NOT_MODIFIED_ERR

Windows Quirks

  • The plugin implementation is based on BackgroundDownloader/BackgroundUploader, which entails the latency issues on Windows devices (creation/starting of an operation can take up to a few seconds). You can use XHR or HttpClient as a quicker alternative for small downloads.

Backwards Compatibility Notes

Previous versions of this plugin would only accept device-absolute-file-paths as the source for uploads, or as the target for downloads. These paths would typically be of the form:

For backwards compatibility, these paths are still accepted, and if your application has recorded paths like these in persistent storage, then they can continue to be used.

These paths were previously exposed in the fullPath property of FileEntry and DirectoryEntry objects returned by the File plugin. New versions of the File plugin however, no longer expose these paths to JavaScript.

If you are upgrading to a new (1.0.0 or newer) version of File, and you have previously been using entry.fullPath as arguments to download() or upload(), then you will need to change your code to use filesystem URLs instead.

FileEntry.toURL() and DirectoryEntry.toURL() return a filesystem URL of the form:

which can be used in place of the absolute file path in both download() and upload() methods.

Sample: Download and Upload Files

Use the File-Transfer plugin to upload and download files. In these examples, we demonstrate several tasks like:

File Video Download

Download a Binary File to the application cache

Use the File plugin with the File-Transfer plugin to provide a target for the files that you download (the target must be a FileEntry object). Before you download the file, create a DirectoryEntry object by using resolveLocalFileSystemURL and calling fs.root in the success callback. Use the getFile method of DirectoryEntry to create the target file.

Note For persistent storage, pass LocalFileSystem.PERSISTENT to requestFileSystem.

When you have the FileEntry object, download the file using the download method of the FileTransfer object. The 3rd argument to the download function of FileTransfer is the success callback, which you can use to call the app's readBinaryFile function. In this code example, the entry variable is a new FileEntry object that receives the result of the download operation.

If you just need to display the image, take the FileEntry to call its toURL() function.

Depending on your app requirements, you may want to read the file. To support operations with binary files, FileReader supports two methods, readAsBinaryString and readAsArrayBuffer. In this example, use readAsArrayBuffer and pass the FileEntry object to the method. Once you read the file successfully, construct a Blob object using the result of the read.

Once you read the file successfully, you can create a DOM URL string using createObjectURL, and then display the image.

As you saw previously, you can call FileEntry.toURL() instead to just display the downloaded image (skip the file read).

Upload a File

When you upload a File using the File-Transfer plugin, use the File plugin to provide files for upload (again, they must be FileEntry objects). Before you can upload anything, create a file for upload using the getFile method of DirectoryEntry. In this example, create the file in the application's cache (fs.root). Then call the app's writeFile function so you have some content to upload.

In this example, create some simple content, and then call the app's upload function.

Forward the FileEntry object to the upload function. To perform the actual upload, use the upload function of the FileTransfer object.

Download the uploaded file

To download the image you just uploaded, you will need a valid URL that can handle the request, for example, http://some.server.com/download.php. Again, the success handler for the FileTransfer.download method receives a FileEntry object. The main difference here from previous examples is that we call FileReader.readAsText to read the result of the download operation, because we uploaded a file with text content.

In the readFile function, call the readAsText method of the FileReader object.

README

This plugin gives you the ability to use the Dynatrace instrumentation in your hybrid application (Cordova, Ionic, Capacitor ..). 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 9
  • For JavaScript Agent: access to API of cluster
  • Android: Gradle > 5.0 (How to update?)
  • Node: > 10.x

Agent Versions

This agent versions are configured in this plugin:

  • iOS Agent: 8.229.1.1004
  • Android Agent: 8.229.1.1003

Quick Setup

Advanced Topics

  • Cordova configuration
  • Mobile Agent configuration
  • JavaScript Agent configuration
  • Manual instrumentation
  • Manual instrumentation - Mobile Agent
  • Native OneAgent debug logs
  • Troubleshooting and current restrictions

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

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 WebView 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 substituted 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:configdynatrace.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.

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 ..').

Cordova

Capacitor Instrumentation

To instrument your Ionic Capacitor app, you will need to follow the steps below:

  1. Install the Dynatrace Cordova Plugin via the following command:
  • npm install @dynatrace/cordova-plugin
  1. Go to your Dynatrace WebUI and select the menu point 'Deploy Dynatrace'. Choose to setup mobile monitoring and select Cordova. Click the Monitor the web view button if you have not already.
  2. Click the Download dynatrace.config.js button and move the downloaded file to the root of your capacitor project.
  3. Make sure you add 'http://localhost' (or something else if you have configured a different scheme) to the Android configuration domains in the dynatrace.config.js:
  1. Run the following commands (replace <platform> with ios or android):
  • ionic capacitor sync <platform>
  • ionic capacitor build <platform>
  1. Run your application

Note:Capacitor 3 has the addition of the ionic capacitor run <platform> command. Unfortunately, we cannot support this as the ionic hook available will not allow for us to instrument html files properly. We will continue the requirement of step 4 to properly instrument a capacitor app.

Cordova configuration

Cookie Proxy

Issues with cookies are somehow a persistent companion in Ionic or Capacitor applications. Therefor we provide a proxy script which is wrapping the document.cookie API and are storing the cookies which are important for the Dynatrace Agents in the session storage. Of course this wrapping is still calling the original API.

Per default the cookie proxy is turned off. To make use of this proxy you need to enable it in the cordova configuration in the dynatrace.config.js:

The true in the cookieProxy property will insert a dt-cookie-proxy.js script in the index.html.

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 property

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.

Mobile Agent configuration

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.

  • 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. There are three available properties:

  • url - Dynatrace API url to retrieve the JS agent script tag.
  • mode - Values can be numbers 0-4 depending on what JavaScript Agent code snippet you want to use.
  • allowanycert - Allows the plugin to ignore certificate issues when retrieving the JavaScript Agent.

JavaScript Agent Snippet Mode

Using a specific mode can allow you during build to insert any of the available JavaScript agent code snippet options that are offered.Click here for more details on the options listed below:

  • 0 - jsInlineScript
  • 1 - jsTagComplete
  • 2 - syncCS (Default)
  • 3 - asyncCS
  • 4 - jsTag

The above example will use mode option 2 and retrieve the synchronous code snippet of the JavaScript agent.

Cordova-plugin-file-transfer

Note:The default url value will be used if mode is not included in the dynatrace.config.js file or if mode exists and the value is not valid (i.e. not a number 0 through 4).

Allow any certificate

If you are having an issue retrieving the JavaScript Agent and see an error message relating to a 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 retrieve the JavaScript Agent snippet anyways. An example would look like this:

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 adding manual instrumentation. If you like to know more about the manual instrumentation, have a look into the Dynatrace 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 errors for this action before closing, see next section Report Error.

Report error

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

Identify user

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

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.

Typings file for JavaScript Agent API

If you are using typescript and want to use the manual instrumentation of the JSAgent you should install the typings. The typings are available under the package name @dynatrace/dtrum-api-types. External typings have the advantage that you can apply the version that is actually needed.

After installing the typings, they can be used by inserting the following line at the top of the file:

or including the typings in your tsconfig.json file:

Be aware if you are using typescript you need to prefix your dtrum calls with window. as the typings file is made for all web applications.

This means a call to enterAction might look like this:

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:

You can also use the dtrum API directly to end the session:

Note: This API is not available in the typings file as we add it for convenience at runtime. If you are using typescript you might want to use dynatraceMobile.endSession(...).

User Privacy Options

Specifies if the user has to opt-in for being monitored. When enabled, you must specify the privacy setting. The following in configuration is needed to be able to use the API.

Android

iOS

The privacy API methods allow you to dynamically change the is already defined, just add the path to the already defined ones.

If you still don't get types in your .ts file, please insert the following snippet at the top of your .ts file:

Native Webrequests

Attention: This feature requires a instrumented webserver with version 1.211.x

Within Cordova it is also possible to use libraries that are executing native web requests. Some examples are: cordova-plugin-advanced-http, @ionic-native/http, cordova-plugin-okhttp or Mobile First by IBM.

Those libraries are not executing the request within the JS scope but will rather call a JavaScript<->Native interface and will trigger the request natively. This means that our JavaScript OneAgent will not be able to detect the request. Additionally a resulting user action can be dropped as well. To prevent this behaviour you need to manually apply headers to your request.

Before using this feature you need to turn of web request instrumentation on iOS. You can do this by adding the following configuration to the dynatrace.config.js:

The following code will create a user action and a linked web request for you:

IBM Mobile First

Attention: This feature requires a instrumented webserver with version 1.211.x running at your Mobile First server. Also, only version >= 8.x.x is supported.

If you are using IBM Mobile First you might take a look at our dynatraceMobile.getMobileFirstNetworkInterceptor(). This interceptor gives you the option to make the request going to Mobile First more visible. The Mobile First library is doing native mobile web requests, that's why those request can't be linked with user actions happening in the web part.

This interceptor is creating wrapping actions according to the user input that happened right before the request. By this modification you will be able to see the request in the user session linked with user actions.

Before using this feature you need to turn of web request instrumentation on iOS. You can do this by adding the following configuration to the dynatrace.config.js:

After Mobile First has been initialized make the following call:

It is also possible to deactivate the interceptor again. This will reset the modifications to the WLResourceRequest:

Ionic WebView 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:

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:

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

Note:Custom arguments will not work with Capacitor based projects.

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

  • --gradle=C:MyCordovaAndroidProjectplatformsandroidbuild.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 all agent dependencies automatically for you and will update the configuration.
  • --plist=C:MyCordovaIOSProjectplatformsiosprojectNameprojectName-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:SpecialFolderForDynatracedynatrace.config.js - Used for if you have not added your config file in the root folder of the Cordova project but somewhere else.
  • --jsagent=C:MyCordovaProjectscriptsjsSnippet.txt - If you want to use a local script/text file that includes the JS Agent snippet downloaded from the WebUI or retrieved from using the Dynatrace API. Note that you can name the file whatever you want but the file and directory that you use needs to exist. The file downloaded from the WebUI will be named jsSnippet.txt by default.

Example:

If you use Ionic make sure to use -- :

Additional Note:For the local script file, we copy the specified file 1:1. It is best to download the JS agent snippet from the WebUI after selecting the desired JS agent format and clicking the Download link below the shown code snippet. To get to this page, go to your Web Application settings and then select Setup. The contents of the file will be copied 1:1 inside of the <head> tag of your Cordova applications platform based html files.

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

  • ProjectFolderandroidcordovalibbuildersProjectBuilder.js Contains the following line:

make sure you insert some other version like 5.4.1 here:

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

Cordova File Download Plugin Free

MavenCentral in top level gradle file

Because the Dynatrace Android agent now requires the MavenCentral repository, if either jcenter() or mavenCentral() is not added inside of ALL the repositories blocks via the top-level build.gradle, the build will fail.Below is an example of what a basic top-level build.gradle file should look like after adding mavenCentral() to all repository blocks:

The location of the top-level build.gradle should be:

  • Cordova/Ionic:
    • <rootOfProject>platformsandroidbuild.gradle
  • Ionic/Capacitor:
    • <rootOfProject>androidbuild.gradle

Note:JCenter has noted its sunset on May 1st. Though, JCenter is still syncing with Maven Central so havingjcenter() in your build.gradle file without the use of mavenCentral() will retrieve the Dynatrace Android Gradle Plugin no problem.

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. Please attach the mobile agent logs and the doctor dynatrace logs when opening a support ticket.

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):

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):

Official documentation

  • Android Agent: https://www.dynatrace.com/support/help/technology-support/operating-systems/android/
  • iOS Agent: https://www.dynatrace.com/support/help/technology-support/operating-systems/ios/

Doctor Dynatrace

Doctor dynatrace is a tool that will analyze your project and determine if there is something wrong with your current configuration and will also provide information and requirements based on features that are available when using our plugin.

To run this tool, open terminal in the root directory of your project and run the following command: npm run doctorDynatrace

The results will be generated in the terminal window as well as stored in log folder located in the following directories:

  • Cordova/Ionic => C:MyCordovaProjectpluginsdynatrace-cordova-pluginlogscurrentDoctorDynatrace.txt
  • Capacitor => C:[email protected]rentDoctorDynatrace.txt

The log file will also include a list of your package.jsondependencies and devDependencies which will be helpful when investigating possible issues that arise. Please add this doctor dynatrace log and mobile agent debug logs when opening a support ticket.

Troubleshooting and current restrictions

Note:The Dynatrace Android Gradle plugin is hosted on Maven Central. JCenter has noted it's sunset on May 1st so Maven Central is the primary source of the Dynatrace Android Gradle plugin.

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 retrieve the JSAgent! 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 copied JS Agent code snippet from the WebUI manually to your index.html (in the source directory). To get to this page, go to your Web Application settings and then select Setup. Auto-Instrumentation with the Mobile Agent still takes place.
  • If you have problems retrieving the JavaScript Agent and you get error messages that the JavaScript Agent can not be retrieved, 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 use the cli and add the --jsagent= custom parameter and download the full Javascript Agent and add the path to the downloaded JS Agent file to the custom parameter value - With this the plugin will not retrieve the JS agent and will use the one that is specified.
  • If you are not seeing data when using Capacitor 3+, please make sure you follow the steps in the Capacitor Instrumentation section (more specifically step 4 for the proper commands). Please read the note at the bottom of that section for more information.
  • For Android, if you see an error like 'Gradle sync failed: Could not find com.dynatrace.tools.android:gradle-plugin:8.221.1.1005.', please see the MavenCentral section for an example and more information.

iOS Session Correlation Issues

iOS apps using ionic/capacitor have issues with passing cookies from the native layer to WkWebView layer. This issue is due to ionic and capacitor using their own default custom schemes (i.e. ionic:// or capacitor://) and the strict policy of Apple's WebKit not allowing cookies to be set in WkWebView with these custom schemes.

To resolve this issue and allow the Mobile and Web sessions to correlate properly, we inject the session information into local storage so that the JavaScript agent can use this info for the Web session it creates.

Requirements

  • iOS agent version 8.219.1.1004+ (already included in our plugin)
  • JavaScript agent version 1.219+
    • Any version lower will not check local storage and correlation of the mobile and web sessions will not occur.

Changelog

1.229.0

  • Adding SessionStorage values to Native web request instrumentation
  • Updated Android (8.229.1.1003) & iOS Agent (8.229.1.1004)

1.227.6

  • Added Cookie Proxy for Ionic & Capacitor
  • Fixed dynatraceMobile.applyUserPrivacyOptions for Android
  • Fixed wrong check for missing dtrum
  • Fixed incorrectly reading cspURL value
  • Fixed waiting for async hooks to complete
  • Updated Android (8.227.1.1002) & iOS Agent (8.227.1.1019)

1.225.1

  • Fixed doctor dynatrace plugin version check issue

1.225.0

  • Added doctor dynatrace command to check for problems
  • Removed check and adding of -ObjC linker for Capacitor apps
  • Added support for Capacitor 3
  • Enhanced user action creation/correlation for Native WR/MFP requests
  • Updated Android (8.223.1.1003) & iOS Agent (8.223.1.1006)
  • IBM MFP Wrapper is now passing all arguments
  • Removed JSAgent typings which are available via NPM

1.219.1

  • Fixed issue with older Android versions
  • Fix for custom CLI arguments not being checked issue
  • Updated iOS (8.219.1.1004)
  • Added support for MFP API sendFormParameters

1.217.1

Cordova File Download Plugin Free

  • Added support for native web requests
  • Added support for IBM Mobile First
  • Added UserPrivacyOptions API
  • End session available via dtrum API
  • Added support for ionic capacitor
  • Updated iOS (8.217.1.1003) and Android Agent (8.211.1.1010)

1.213.0

  • Added new custom parameter for cli to allow use of local js agent script file
  • Added mode option in the config file for using specific JSAgent code snippet
  • No longer store JS Agent file and only inject platform html
  • Added dtrum API that will prevent errors if JS agent is not loaded
  • Updated iOS (8.209.1.1003) and Android Agent (8.211.1.1010)
  • Skipping not readable files instead of throwing an exception

1.205.0

  • Updated iOS and Android agent

1.201.0

  • Updated iOS and Android agent

1.192.0

  • Fix for Installation/Removing issues

1.191.2

File Download Movie

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