Background HTTP

@nativescript/background-http #

A plugin that allows you to make background HTTP uploads.

Contents #

• Installation
• Use @nativescript/background-http
  • Handle upload task events
• API
  • init()
  • session()
    • uploadFile()
    • multipartUpload()
  • Upload request object
  • Task object
    • Task events
• Test the plugin locally
• License

Installation #

npm install @nativescript/background-http

Use @nativescript/background-http #

To make background HTTP calls, follow these steps:

1. Initialize a background HTTP service

Call the init() function to initialize an HTTP service that runs in the background. Call the method early in your application, in the main.ts file, before the app starts.

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

2. Upload files

   1. Create an upload session by calling the session() function and passing it the session's unique identifier string, image-upload for example.

   // 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,
   };
   

   2. Upload files
   • To initiate a simple upload request, call the session's uploadFile() method and pass it the file path and an Upload request object:

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

   • To initiate a multipart/form-data upload request or to pass additional data, call 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, you should ensure the following are met:

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

Handle upload task events #

Both uploadFile() and multipartUpload() initiate and return a Task instance.

After the upload task is initiated, you can monitor its progress using the following events.

For more information about the events objects, see Task 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 receives a single parameter containing the event data.

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 http 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:

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 #

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)

Gets or creates a background http session by id.

uploadFile() #

session.uploadFile(filePath, requestOptions)

A method of the session object that initiates a background task to upload the specified file encoded as application/x-www-form-urlencoded.

multipartUpload() #

session.multipartUpload()

A method of the session object that initiates a background task to upload the specified file encoded as multipart/form-data.

Upload request object #

The request object parameter has the following properties:

Task object #

The task object has the following properties and methods.

Task events #

The following are events emitted for different progress states of a background task:

• EventData

All the following task events extend the preceding EventData interface.

• ProgressEventData

• ResultEventData

• CompleteEventData

• ErrorEventData

Test the plugin locally #

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