Guides

Downloads

Learn how to manage file downloads, track download progress, get notification when download is completed, etc.

When user clicks a link that points to a resource that cannot be displayed in the browser (e.g. ZIP archive) or loads such a resource, the browser will suggest to download it. By default, a native save file dialog will be shown to the user. In this dialog the user can select the directory where the file will be saved or cancel the download.

Downloading a file

If you need to download a resource by URL independently whether the browser can display it or not, you can use the following approach:

import { app } from '@mobrowser/api';

// Create a new window.
const win = app.createWindow()

// Download the file.
win.browser.downloadUrl('https://example.com/file.zip')

If you prefer to download the file or cancel the download programmatically, without showing the save file dialog to the user, you can use the approach as described below.

Accepting a download

To handle the download, register the startDownload handler. In this handler you can programmatically accept the download and specify the target file path:

import {
  app,
  StartDownloadParams,
  StartDownloadAction
} from '@mobrowser/api';

// Create a new window.
const win = app.createWindow()

// Handle downloads.
win.browser.handle('startDownload',
  async (params: StartDownloadParams): Promise<StartDownloadAction> => {
    return 'path/to/directory/' + params.download.fileName
  }
)

// Download the file.
win.browser.downloadUrl('https://example.com/file.zip')

Important: Make sure that the application has sufficient permissions to save the file. If the target file already exists, the application will overwrite it. We recommend checking the permissions before accepting the file download.

To let the user decide whether to accept the download or not, use the default approach that shows the native save file dialog:

import {
  app,
  StartDownloadParams,
  StartDownloadAction
} from '@mobrowser/api';

// Create a new window.
const win = app.createWindow()

// Handle downloads.
win.browser.handle('startDownload',
  async (params: StartDownloadParams): Promise<StartDownloadAction> => {
    return 'prompt'
  }
)

// Download the file.
win.browser.downloadUrl('https://example.com/file.zip')

Controlling the download

In the startDownload handler you can access the Download instance and use it to control the download process:

import {
  app,
  StartDownloadParams,
  StartDownloadAction
} from '@mobrowser/api';

// Create a new window.
const win = app.createWindow()

// Handle downloads.
win.browser.handle('startDownload',
  async (params: StartDownloadParams): Promise<StartDownloadAction> => {
    const download: Download = params.download
    return 'path/to/directory/' + download.fileName
  }
)

// Download the file.
win.browser.downloadUrl('https://example.com/file.zip')

To pause the download use the pause() function:

download.pause()

To resume the paused download use the resume() function:

download.resume()

You can cancel the download anytime unless the download is in the terminated state. This includes the completed downloads, canceled downloads, and interrupted downloads that cannot be resumed.

To cancel the download use the cancel() function:

const canceled = download.isCanceled()
const finished = download.isFinished()
const interrupted = download.isInterrupted()
if (!(canceled || finished || interrupted)) {
  download.cancel()
}

Download events

You can track the download progress, get notifications when the download has been canceled, paused, interrupted, or finished.

To get notifications when the download has been canceled use the following event:

download.on('canceled', () => {
  console.log('Download canceled')
})

To get notifications when the download has been finished use the following event:

download.on('finished', () => {
  console.log('Download finished')
})

To get notifications when the download has been paused use the following event:

download.on('paused', () => {
  console.log('Download paused')
})

To track the download progress use the following event:

import {
  app,
  StartDownloadParams,
  StartDownloadAction,
  DownloadProgress
} from '@mobrowser/api';

// Create a new window.
const win = app.createWindow()

// Handle downloads.
win.browser.handle('startDownload',
  async (params: StartDownloadParams): Promise<StartDownloadAction> => {
    const download: Download = params.download
    download.on('progressChanged', (progress: DownloadProgress) => {
      console.log('Download progress: ', progress.percentComplete, '%')
    })
    return 'path/to/directory/' + download.fileName
  }
)

// Download the file.
win.browser.downloadUrl('https://example.com/file.zip')

To get notifications when the download has been interrupted for some reason use the following approach:

import {
  app,
  StartDownloadParams,
  StartDownloadAction,
  DownloadProgress
} from '@mobrowser/api';

// Create a new window.
const win = app.createWindow()

// Handle downloads.
win.browser.handle('startDownload',
  async (params: StartDownloadParams): Promise<StartDownloadAction> => {
    const download: Download = params.download
    download.on('interrupted', (reason: DownloadInterruptReason) => {
      if (reason === 'fileNoSpace') {
        console.log('Download interrupted: not enough space')
      }
    })
    return 'path/to/directory/' + download.fileName
  }
)

// Download the file.
win.browser.downloadUrl('https://example.com/file.zip')