Skip to content
Cordova plugin for background upload
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.
demo update demo url Apr 6, 2018
src restore ios server reponse if upload completed when app not running Jul 5, 2019
types added typescript definitions Apr 3, 2017
www Update FileTransferManager.js Jun 12, 2019
.gitignore initial commit Mar 27, 2017
.npmignore removed cheerio Apr 6, 2017
LICENSE initial commit Mar 27, 2017 added note for android 8+ Jun 20, 2019
plugin.xml bumped to v1.1.0 Jul 15, 2019

Background Upload Plugin for Cordova

This plugin provides a file upload functionality that can continue to run while in background. It also includes progress updates which is suitable for long-term transfer operations for large files. Currently only 1 concurrent upload is possible at any time.

Supported Platforms

  • iOS
  • Android


To install the plugin:

cordova plugin add cordova-plugin-background-upload --save

To uninstall this plugin:

cordova plugin rm cordova-plugin-background-upload

Sample usage

The plugin needs to be initialised before any upload. Ideally this should be called on application start. The uploader will provide global events which can be used to check the progress of the uploads.

 declare var FileTransferManager: any;

 var uploader = FileTransferManager.init();

 uploader.on('success', function(upload) {
     console.log("upload: " + + " has been completed successfully");


 uploader.on('progress', function(upload) {
     console.log("uploading: " + + " progress: " + upload.progress + "%");


 uploader.on('error', function(uploadException) {
     if ( {
         console.log("upload: " + + " has failed");
     } else {
         console.error("uploader caught an error: " + uploadException.error);

Adding an upload is done via the startUpload method. In case the plugin was not able to enqueue the upload, an exception will be thrown in the error event listener.

 var payload = {
     "id": "sj5f9"
     "filePath": "/storage/emulated/0/Download/Heli.divx",
     "fileKey": "file",
     "serverUrl": "",
     "showNotification": true,
     "notificationTitle" : "Uploading images",
     "headers": {
         "api_key": "asdasdwere123sad"
     "parameters": {
         "signature": "mysign",
         "timestamp": 112321321



  • id: the id of the file you want to upload (String). this will be used to track uploads
  • filePath: the absolute path for the file to upload
  • fileKey: the name of the key to use for the file
  • serverUrl: remote server url
  • headers: custom http headers
  • parameters: custom parameters for multipart data
  • showNotification: show progress notification on android (true by default)
  • notificationTitle: Notification title when file is being uploaded (Android only)

To remove/abort an upload:

uploader.removeUpload(uploadId, function(){
    //upload aborted
}, function(err){
    //could abort the upload


The plugin runs on ios 9.0 and above. The code was based on the following blog:

Internally it uses NSUrlSession to perform the upload in a background session. When an uploaded is initiated, it will continue until it has been completed successfully or if the user kills the application. If the application is terminated by the OS, the uploads will still continue. When the user relaunches the application, after calling the init method, the success and error events will be emitted with the ids of these uploads. If the user chose to kill the application by swiping it up from the multitasking pane, the uploads will not be continued. Upload tasks in background sessions are automatically retried by the URL loading system after network errors as decided by the OS.


The minimum api level require is 21 and the background file upload is handled by the android-upload-service library. If the application is killed while uploading, either by the user or the OS, all uploads will be stopped. When the app is relaunched, the ids of these uploads will be emitted to the error listener. If an upload is added when there is no network connection, it will be retried as soon as the network becomes reachable unless the app is already killed.

On android Oreo, there are more strict limits on background services and it's recommended to use a foreground service with an ongoing notification to get more time for service execution: Hence to prevent the service from be killed, an progress notification is needed on Android 8+.


If you have a web version also, you can use our javascript library designed to abstract the uploads. More info here:

cordova background upload


Cordova-plugin-background-upload is licensed under the Apache v2 License.


Cordova-plugin-background-upload is brought to you by Spoon Consulting.

You can’t perform that action at this time.