Skip to content

Commit

Permalink
Update README with plugin configuration options and better formatting
Browse files Browse the repository at this point in the history 
The commit makes the README more informative and readable. It introduces a new section on configuration options and restructures existing information for better clarity. The changes include organising data into tables, wrapping code blocks cleanly, and adjusting spacing for improved readability.
  • Loading branch information
@nvahalik
nvahalik committed Apr 19, 2024
1 parent 629dc3c commit c43ea96
Showing 1 changed file with 91 additions and 43 deletions.
134 changes: 91 additions & 43 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,15 +1,16 @@

# cordova-plugin-background-upload
This plugin provides a file upload functionality that can continue to run even while the app is in background. It includes progress updates suitable for long-term transfer operations of large files.

This plugin provides a file upload functionality that can continue to run even while the app is in background. It
includes progress updates suitable for long-term transfer operations of large files.

[![npm version](https://badge.fury.io/js/@spoonconsulting%2Fcordova-plugin-background-upload.svg)](https://badge.fury.io/js/@spoonconsulting%2Fcordova-plugin-background-upload)
[![Build Status](https://travis-ci.com/spoonconsulting/cordova-plugin-background-upload.svg?branch=master)](https://travis-ci.org/spoonconsulting/cordova-plugin-background-upload)

**Supported Platforms**

- iOS
- Android


**Installation**

To install the plugin:
Expand All @@ -19,28 +20,46 @@ cordova plugin add @spoonconsulting/cordova-plugin-background-upload --save
```

To uninstall this plugin:

```
cordova plugin rm @spoonconsulting/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. By default, the maximum number of parallel uploads allowed is set to 1. You can override it by changing the configuration on init.
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. By default, the maximum number of
parallel uploads allowed is set to 1. You can override it by changing the configuration on init.

```javascript
declare var FileTransferManager: any;
declare
var FileTransferManager: any;
var config = {};
var uploader = FileTransferManager.init(config, callback);
```

**Configuration Options**

| Option | Availability | Purpose |
|----------------------|--------------|-------------------------------------------------------------------------------|
| parallelUploadsLimit | iOS, Android | Sets the number of simultaneous uploads. |
| resourceTimeout | iOS | How long a given resource will retry until it fails. |
| requestTimeout | iOS | How long an individual attempt will wait until it fails to retry again later. |

**Methods**

### uploader.init(config, callback)
Initialises the uploader with provided configuration. To control the number of parallel uploads, pass `parallelUploadsLimit` in config.

Initialises the uploader with provided configuration. To control the number of parallel uploads,
pass `parallelUploadsLimit` in config.
The callback is used to track progress of the uploads
`var uploader = FileTransferManager.init({parallelUploadsLimit: 2}, event => {});`

### uploader.startUpload(payload)
Adds an upload. In case the plugin was not able to enqueue the upload, an error will be emitted in the global event listener.

Adds an upload. In case the plugin was not able to enqueue the upload, an error will be emitted in the global event
listener.

```javascript
var payload = {
id: "c3a4b4c7-4f1e-4c69-a951-773602e269fb",
Expand All @@ -58,19 +77,21 @@ var payload = {
};
uploader.startUpload(payload);
```
Param | Description
-------- | -------
id | a unique id of the file (UUID string)
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
notificationTitle | Notification title when file is being uploaded (Android only)

Param | Description
-------------------|---------------------------------------------------------------
id | a unique id of the file (UUID string)
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
notificationTitle | Notification title when file is being uploaded (Android only)

### uploader.removeUpload(uploadId, successCallback, errorCallback)

Cancels and removes an upload

```javascript
uploader.removeUpload(uploadId, function () {
//upload aborted
Expand All @@ -79,15 +100,16 @@ uploader.removeUpload(uploadId, function () {
});
```


### uploader.acknowledgeEvent(eventId)

Confirms event received and remove it from plugin cache

```javascript
uploader.acknowledgeEvent(eventId);
```


The uploader will provide global events which can be used to check the status of the uploads.

```javascript
FileTransferManager.init({}, function (event) {
if (event.state == 'UPLOADED') {
Expand All @@ -106,56 +128,82 @@ FileTransferManager.init({}, function (event) {

```

To prevent any event loss while transitioning between native and Javascript side, the plugin stores success/failure events on disk. Once you have received the event, you will need to acknowledge it else it will be broadcast again when the plugin is initialised. Progress events do not have eventId and are not persisted.
To prevent any event loss while transitioning between native and Javascript side, the plugin stores success/failure
events on disk. Once you have received the event, you will need to acknowledge it else it will be broadcast again when
the plugin is initialised. Progress events do not have eventId and are not persisted.

```javascript
if (event.eventId) {
uploader.acknowledgeEvent(event.eventId, function(){
uploader.acknowledgeEvent(event.eventId, function () {
//success
}, function (error){
}, function (error) {
//error
});
}
```
An event has the following attributes:

Property | Comment
-------- | -------
id | id of the upload
state | state of the upload (either `UPLOADING`, `UPLOADED` or `FAILED`)
statusCode | response code returned by server after upload is completed
serverResponse | server response received after upload is completed
error | error message in case of failure
errorCode | error code for any exception encountered
progress | progress for ongoing upload
eventId | id of the event

An event has the following attributes:

## iOS
The plugin runs on ios 10.0 and above and internally uses [AFNetworking](https://github.com/AFNetworking/AFNetworking). AFNetworking uses [NSURLSession](https://developer.apple.com/library/content/documentation/Cocoa/Conceptual/URLLoadingSystem/Articles/UsingNSURLSession.html#//apple_ref/doc/uid/TP40013509-SW44) under the hood to perform the upload in a background session. When an upload is initiated, it will continue until it has been completed successfully or until 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, events will be emitted with the ids of these uploads. If the user kills 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.
Property | Comment
----------------|------------------------------------------------------------------
id | id of the upload
state | state of the upload (either `UPLOADING`, `UPLOADED` or `FAILED`)
statusCode | response code returned by server after upload is completed
serverResponse | server response received after upload is completed
error | error message in case of failure
errorCode | error code for any exception encountered
progress | progress for ongoing upload
eventId | id of the event

## iOS

The plugin runs on ios 10.0 and above and internally uses [AFNetworking](https://github.com/AFNetworking/AFNetworking).
AFNetworking
uses [NSURLSession](https://developer.apple.com/library/content/documentation/Cocoa/Conceptual/URLLoadingSystem/Articles/UsingNSURLSession.html#//apple_ref/doc/uid/TP40013509-SW44)
under the hood to perform the upload in a background session. When an upload is initiated, it will continue until it has
been completed successfully or until 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, events will be
emitted with the ids of these uploads. If the user kills 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.

## Android
The minimum API level required is 21(Android 5) and the background file upload is handled by the WorkMananger library. If you have configured a notification to appear in the notifications area, the uploads will continue even if the user kills the app manually. 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 has already been killed.

On Android 12 and above, there are strict limitations on background services that does not allow to start a Foreground Service when the app is processing in background(https://developer.android.com/guide/components/foreground-services). Hence to prevent this on Android 12 and above, we have a classic notification. On Android 11 and below, we are still using foreground service along with WorkManager to start the notification.
The minimum API level required is 21(Android 5) and the background file upload is handled by the WorkMananger library.
If you have configured a notification to appear in the notifications area, the uploads will continue even if the user
kills the app manually. 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 has already been killed.

On Android 12 and above, there are strict limitations on background services that does not allow to start a Foreground
Service when the app is processing in background(https://developer.android.com/guide/components/foreground-services).
Hence to prevent this on Android 12 and above, we have a classic notification. On Android 11 and below, we are still
using foreground service along with WorkManager to start the notification.

## Migration notes for v2.0
- When v2 of the plugin is launched on an app containing uploads still in progress from v1 version, it will mark all of them as `FAILED` with `errorCode` 500 so that they can be retried.
- If an upload is cancelled, an event with status `FAILED` and error code `-999` will be broadcasted in the global callback. It is up to the application to properly handle cancelled callbacks.

- When v2 of the plugin is launched on an app containing uploads still in progress from v1 version, it will mark all of
them as `FAILED` with `errorCode` 500 so that they can be retried.
- If an upload is cancelled, an event with status `FAILED` and error code `-999` will be broadcasted in the global
callback. It is up to the application to properly handle cancelled callbacks.
- v2 removes the events `success`, `error`, `progress` and instead uses a single callback for all events delivery:
```javascript
uploader.on('event', function (event) {
//use event.state to handle different scenarios
});
```
- Events need to be acknowledged to be removed. Failure to do so will result in all saved events being broadcast on `init`.
-`showNotification` parameter has been removed (A notification will always be shown on Android during upload)

- Events need to be acknowledged to be removed. Failure to do so will result in all saved events being broadcast
on `init`.
-`showNotification` parameter has been removed (A notification will always be shown on Android during upload)

## README for v1.0
The README for the previous version can be found [here](https://github.com/spoonconsulting/cordova-plugin-background-upload/blob/eacce4385ae497188307a9944c2f353571a463a2/README.md).

The README for the previous version can be
found [here](https://github.com/spoonconsulting/cordova-plugin-background-upload/blob/eacce4385ae497188307a9944c2f353571a463a2/README.md).

## License

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

## Credits

cordova-plugin-background-upload is brought to you by [Spoon Consulting Ltd] (http://www.spoonconsulting.com/).

0 comments on commit c43ea96

Please sign in to comment.