AboutSupport
Docs

File download

Suggest Edits

OpenFin gives application providers a security-first approach to seamlessly download files from within applications. Some of OpenFin’s APIs (such as launchExternalProcess()) offer greater access to the system than typical Web APIs, and our file download support has been designed with that in mind. This model ensures downloadable files are originating from known, trusted locations and reduces the risk of any content being downloaded that is not considered safe. It also reduces the number of steps an end-user performs to display the content.

Application providers can create streamlined workflows for their end-user, such as the following:

  • Download and launch files with a single click
  • Download and save files to a predefined location

OpenFin provides application developers with the necessary tools to do things like following:

  • Get and set download locations via API calls
  • Be notified of changes to the download location via an event
  • Determine rules for where files can be sourced
  • Determine rules for specific file types

Downloading files in your application

The methods involved in implementing file download workflows in your application are secured APIs. Using these methods requires you add the following to the manifest:

  • Declare your use of secured APIs. Desktop owners or users might still block your application from using these APIs; refer to API security for details.
  • Define locations to download from, allowed file types, and whether to prompt the user when downloading.

Secured APIs

The secured APIs you might want to use for file download workflows include the following:

📘

Note

The "Save As" dialog uses the default file download location, not the file download location set by setFileDownloadLocation.

📘

Note

The changes to the download settings are not persisted automatically by the setDomainSettings function. To persist the download settings, update the manifest accordingly.

The event file-download-location-changed indicates a change to the download location (starting in Runtime version 32). However, because the event is not a secured API, the event data does not contain the new download location. To obtain the new download location, you must use the getFileDownloadLocation() method.

Manifest properties for file downloads

The following manifest properties are used to manage the file download experience:

  • domainSettings (defaultDomainSettings in Runtime v34 and earlier) is the object that contains the file download rules. It can appear as an option for startup_app or platform, as appropriate to the application.
  • rules is an array of rule definition objects, each consisting of match, and options or behavior members.
  • match is an array of match patterns. Depending on where and how it is used, it can define URLs of domains that files can be downloaded from or file types that can be downloaded. Wildcards for subdomains are supported. You can also use <all_urls> to match all URLs.
  • options contains downloadSettings, which in turn contains a rules object defining file types to match, and behavior for matched file types.
  • behavior defines whether the end-user should be prompted with a Save As dialog from the operating system. Possible values are:
    • prompt: The default. A user is shown the default download dialog box from the operating system.
    • no-prompt: The file is downloaded automatically, without user intervention.

📘

Note

See Domain-based permissions for use of the domainSettings manifest object to control other sensitive areas of functionality.

Download configuration examples

In the following example subsets of a manifest, for all subdomains of example.com, PNG and JPEG files are downloaded without prompting the user.

Download rules in a platform manifest

{  "platform" :{
    "domainSettings": {
      "rules": [
        {
          "match": [
            "*/*.example.com"
          ],
          "options": {
            "downloadSettings": {
              "rules": [
                {
                  "match": [
                    "*://*/*.png", "*://*/*.jpg"
                  ],
                  "behavior": "no-prompt"
                }
              ]
            }
          }
        }
      ]
    }
  }
}

Download rules in an app manifest

{  "startup_app" :{
    "domainSettings": {
      "rules": [
        {
          "match": [
            "*/*.example.com"
          ],
          "options": {
            "downloadSettings": {
              "rules": [
                {
                  "match": [
                    "*://*/*.png", "*://*/*.jpg"
                  ],
                  "behavior": "no-prompt"
                }
              ]
            }
          }
        }
      ]
    }
  }
}

To get the current configuration (in Runtime v33 or later):

// Get the download configuration.

const domainSettings = await fin.System.getDomainSettings();

To set the download configuration (in Runtime v33 or later):

// Set the download configuration.

const newDomainSettings = {
  rules: [
    {
      match: [
        '*/*.example.com'
      ],
      options: {
        downloadSettings: {
          rules: [
            {
              match: [
                '*://*/*.png', '*://*/*.jpg'
              ],
              behavior: 'prompt'
            }
          ]
        }
      }
    }
  ]
}

await fin.System.setDomainSettings(newDomainSettings);

How to use the file download location APIs

Examples

The following code snippets demonstrate how to get and set the file download location and how to use the file-download-location-changed event, which is available in Runtime v32 and later.

To get the file download location:

// Get the file download location.

// Get the app object.
let app = fin.Application.getCurrentSync();

// Get the file download location for this app.
const fileDownloadDir = await app.getFileDownloadLocation();

To set the file download location:

// Set the file download location.

// Set a variable to the new download location.
const downloadLocation = 'C:\\dev\\temp';

// Get the app object.
const app = await fin.Application.getCurrent();

try {

  // Set the file download location for this app.
  await app.setFileDownloadLocation(downloadLocation);
  
  // Write a log entry for a successful change to the download location.
  console.log('File download location is set');

} catch(err) {

  // If an error occurs, log the error.
  console.error(err)
}

To update the download settings at runtime:

// Get the current domain settings so we can edit them
const domainRules = await fin.System.getDomainSettings();

// Change the behavior to "no-prompt" for a specific rule
domainRules.rules[0].options.downloadSettings.rules[0].behavior = 'no-prompt';

// Apply those new rules to skip prompts for the match pattern specified
await fin.System.setDomainSettings(domainRules);

To handle the file download location changed event:

// Create an event handler to be notified of a change to the download location.

// Add the event handler for the 'file-download-location-changed' event.
app.on('file-download-location-changed', async (evt) => {
  
  // Add your event handling logic here.
  console.log('location is changed');
  
  // The event data does not provide the new download location because it is secure data.
  // To obtain the new download location, you must call the getFileDownloadLocation function.
  const fileDownloadDir = await app.getFileDownloadLocation();
});

Updated 7 months ago

Related topics