Background HTTP

@nativescript/background-http #

Installation #

npm install @nativescript/background-http

Usage #

Initializing HTTP background service #

Before calling any method from the plugin, you should initialize an HTTP background service by calling the init method in the main.ts file before the app starts.

import { init } from '@nativescript/background-http'
init()

Uploading files #

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

// file path and url
var file = '/some/local/file/path/and/file/name.jpg';
var url = 'https://some.remote.service.com/path';
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 multipartUpload 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)

For 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).
• 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.

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:

function progressHandler(e: ProgressEventData) {
  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: ErrorEventData) {
  alert('received ' + e.responseCode + ' code.')
  var serverResponse = e.response
}

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

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

// event arguments:
// task: Task
function cancelledHandler(e: EventData) {
  alert('upload cancelled')
}

API #

init() #

import { init } from '@nativescript/background-http'

init()

Initializes an HTTP background service.

session() #

import { session } from '@nativescript/background-http';
session: Session = session(id: string)

Gets or creates a background download/upload session by id.

Session Object #

The Session object has the following members:

• uploadFile(fileUri: string, options: Request): Task
• multipartUpload(params: Array<any>, options: Request): Task

Both methods initiate a new background file(s) upload task. uploadFile() is for a single file upload and multipartUpload() is for multiple files upload. fileUri is the path of the file to upload. The options parameter represents the Request object.

Upload Request Object #

The request object parameter has the following properties:

Note:- Android Notification titles/messages can be constructed with one of the following placeholders which will be replaced by the system.

Replaced with the current upload rate/speed [upload_rate]

Replaced with the current upload progress [upload_progress]

Replaced with the elapsed time [upload_elapsed_time]

Task object #

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

EventData #

All the task events extend the EventData interface.

ProgressEventData #

ResultEventData #

CompleteEventData #

ErrorEventData #

Testing the plugin #

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. http://httpbin.org/post 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.

License #

Apache License Version 2.0