Background Upload plugin for the NativeScript framework
Clone or download
elena-p Merge pull request #192 from NativeScript/lini/update-5-1
chor: update dependencies for 5.1 release
Latest commit 2a6757f Dec 13, 2018

Background Upload NativeScript plugin Build Status

A cross platform plugin for the NativeScript framework, that provides background upload for iOS and Android.

There is a stock NativeScript http module that can handle GET/POST requests that work with strings and JSONs. It however comes short in features when it comes to really large files.

The plugin uses NSURLSession with background session configuration for iOS; and the alexbbb/android-upload-service library for Android.


tns plugin add nativescript-background-http


The below attached code snippets demonstrate how to use nativescript-background-http to upload single or multiple files.

Uploading files

Sample code for configuring the upload session. Each session must have a unique id, but it can have multiple tasks running simultaneously. The id is passed as a parameter when creating the session (the image-upload string in the code bellow):

// file path and url
var file =  "/some/local/file/path/and/file/name.jpg";
var url = "";
var name = file.substr(file.lastIndexOf("/") + 1);

// upload configuration
var bghttp = require("nativescript-background-http");
var session = bghttp.session("image-upload");
var request = {
        url: url,
        method: "POST",
        headers: {
            "Content-Type": "application/octet-stream"
        description: "Uploading " + name

For a single file upload, use the following code:

var task = session.uploadFile(file, request);

For multiple files or to pass additional data, use the multipart upload method. All parameter values must be strings:

var params = [
   { name: "test", value: "value" },
   { name: "fileToUpload", filename: file, mimeType: "image/jpeg" }
var task = session.multipartUpload(params, request);

In order to have a successful upload, the following must be taken into account:

  • the file must be accessible from your app. This may require additional permissions (e.g. access documents and files on the device). Usually this is not a problem - e.g. if you use another plugin to select the file, which already adds the required permissions.
  • the URL must not be blocked by the OS. Android Pie or later devices require TLS (HTTPS) connection by default and will not upload to an insecure (HTTP) URL.

Upload request and task API

The request object parameter has the following properties:

Name Type Description
url string The request url (e.g.
method string The request method (e.g. POST).
headers object Used to specify additional headers.
description string Used to help identify the upload task locally - not sent to the remote server.
utf8 boolean (Android only/multipart only) If true, sets the charset for the multipart request to UTF-8. Default is false.
androidDisplayNotificationProgress boolean (Android only) Used to set if progress notifications should be displayed or not. Please note that since API26, Android requires developers to use notifications when running background tasks.
androidNotificationTitle string (Android only) Used to set the title shown in the Android notifications center.
androidAutoDeleteAfterUpload boolean (Android only) Used to set if files should be deleted automatically after upload.
androidMaxRetries number (Android only) Used to set the maximum retry count. The default retry count is 0.

The task object has the following properties and methods, that can be used to get information about the upload:

Name Type Description
upload number Bytes uploaded.
totalUpload number Total number of bytes to upload.
status string One of the following: error, uploading, complete, pending, cancelled.
description string The description set in the request used to create the upload task.
cancel() void Call this method to cancel an upload in progress.

Handling upload events

After the upload task is created you can monitor its progress using the following events:

task.on("progress", progressHandler);
task.on("error", errorHandler);
task.on("responded", respondedHandler);
task.on("complete", completeHandler);
task.on("cancelled", cancelledHandler); // Android only

Each event handler will receive a single parameter with event arguments:

// event arguments:
// task: Task
// currentBytes: number
// totalBytes: number
function progressHandler(e) {
    alert("uploaded " + e.currentBytes + " / " + e.totalBytes);

// event arguments:
// task: Task
// responseCode: number
// error: java.lang.Exception (Android) / NSError (iOS)
// response: net.gotev.uploadservice.ServerResponse (Android) / NSHTTPURLResponse (iOS)
function errorHandler(e) {
    alert("received " + e.responseCode + " code.");
    var serverResponse = e.response;

// event arguments:
// task: Task
// responseCode: number
// data: string
function respondedHandler(e) {
    alert("received " + e.responseCode + " code. Server sent: " +;

// event arguments:
// task: Task
// responseCode: number
// response: net.gotev.uploadservice.ServerResponse (Android) / NSHTTPURLResponse (iOS)
function completeHandler(e) {
    alert("received " + e.responseCode + " code");
    var serverResponse = e.response;

// event arguments:
// task: Task
function cancelledHandler(e) {
    alert("upload cancelled");

Testing the plugin

In order to test the plugin, you must have a server instance to accept the uploads. There are online services that can be used for small file uploads - e.g. However, these cannot be used for large files. The plugin repository comes with a simple server you can run locally. Here is how to start it:

cd demo-server
npm i
node server 8080

The above commands will start a server listening on port 8080. Remember to update the URL in your app to match the address/port where the server is running.

Note: If you are using the iOS simulator then http://localhost:8080 should be used to upload to the demo server. If you are using an Android emulator, should be used instead.


We love PRs! Check out the contributing guidelines. If you want to contribute, but you are not sure where to start - look for issues labeled help wanted.

Get Help

Please, use github issues strictly for reporting bugs or requesting features. For general questions and support, check out Stack Overflow or ask our experts in NativeScript community Slack channel.


Apache License Version 2.0, January 2004