{"id":15018488,"url":"https://github.com/nativescript/nativescript-background-http","last_synced_at":"2025-04-07T18:13:22.144Z","repository":{"id":57308422,"uuid":"41672178","full_name":"NativeScript/nativescript-background-http","owner":"NativeScript","description":"Background Upload plugin for the NativeScript framework","archived":false,"fork":false,"pushed_at":"2021-04-13T05:11:58.000Z","size":66366,"stargazers_count":102,"open_issues_count":31,"forks_count":50,"subscribers_count":28,"default_branch":"master","last_synced_at":"2024-10-29T15:51:52.088Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/NativeScript.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-08-31T11:38:55.000Z","updated_at":"2024-08-30T11:46:46.000Z","dependencies_parsed_at":"2022-09-09T23:12:05.290Z","dependency_job_id":null,"html_url":"https://github.com/NativeScript/nativescript-background-http","commit_stats":null,"previous_names":[],"tags_count":18,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NativeScript%2Fnativescript-background-http","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NativeScript%2Fnativescript-background-http/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NativeScript%2Fnativescript-background-http/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NativeScript%2Fnativescript-background-http/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/NativeScript","download_url":"https://codeload.github.com/NativeScript/nativescript-background-http/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247704571,"owners_count":20982298,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-09-24T19:52:01.619Z","updated_at":"2025-04-07T18:13:22.121Z","avatar_url":"https://github.com/NativeScript.png","language":"TypeScript","readme":"## NativeScript 7\n\n* Use `@nativescript/background-http`: `~5.0.0`\n* [Source managed here](https://github.com/NativeScript/plugins)\n\n## If using 6 and below, see the following:\n\n# Background Upload NativeScript plugin [![Build Status](https://travis-ci.org/NativeScript/nativescript-background-http.svg?branch=master)](https://travis-ci.org/NativeScript/nativescript-background-http)\n\nA cross platform plugin for [the NativeScript framework](http://www.nativescript.org), that provides background upload for iOS and Android.\n\n[There is a stock NativeScript `http` module that can handle GET/POST requests that work with strings and JSONs](http://docs.nativescript.org/ApiReference/http/HOW-TO). It however comes short in features when it comes to really large files.\n\nThe plugin uses [NSURLSession with background session configuration for iOS](https://developer.apple.com/library/ios/documentation/Foundation/Reference/NSURLSessionConfiguration_class/index.html#//apple_ref/occ/clm/NSURLSessionConfiguration/backgroundSessionConfigurationWithIdentifier:); and [a fork](https://github.com/NativeScript/android-upload-service) of the [gotev/android-upload-service](https://github.com/gotev/android-upload-service) library for Android.\n\n## Installation\n\n```bash\ntns plugin add nativescript-background-http\n```\n\n## Usage\n\nThe below attached code snippets demonstrate how to use `nativescript-background-http` to upload single or multiple files.\n\n### Uploading files\n\nSample 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):\n\n```JavaScript\n\n// file path and url\nvar file =  \"/some/local/file/path/and/file/name.jpg\";\nvar url = \"https://some.remote.service.com/path\";\nvar name = file.substr(file.lastIndexOf(\"/\") + 1);\n\n// upload configuration\nvar bghttp = require(\"nativescript-background-http\");\nvar session = bghttp.session(\"image-upload\");\nvar request = {\n        url: url,\n        method: \"POST\",\n        headers: {\n            \"Content-Type\": \"application/octet-stream\"\n        },\n        description: \"Uploading \" + name\n    };\n```\n\nFor a single file upload, use the following code:\n\n```JavaScript\nvar task = session.uploadFile(file, request);\n```\n\nFor multiple files or to pass additional data, use the multipart upload method. All parameter values must be strings:\n\n```JavaScript\nvar params = [\n   { name: \"test\", value: \"value\" },\n   { name: \"fileToUpload\", filename: file, mimeType: \"image/jpeg\" }\n];\nvar task = session.multipartUpload(params, request);\n```\n\nIn order to have a successful upload, the following must be taken into account:\n\n- 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.\n- 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.\n\n### Upload request and task API\n\nThe request object parameter has the following properties:\n\nName | Type | Description\n--- | --- | ---\nurl | `string` | The request url (e.g.`https://some.remote.service.com/path`).\nmethod | `string` | The request method (e.g. `POST`).\nheaders | `object` | Used to specify additional headers.\ndescription | `string` | Used to help identify the upload task locally - not sent to the remote server.\nutf8 | `boolean` | (Android only/multipart only) If true, sets the charset for the multipart request to UTF-8. Default is false.\nandroidDisplayNotificationProgress | `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. https://developer.android.com/about/versions/oreo/background\nandroidNotificationTitle | `string` | (Android only) Used to set the title shown in the Android notifications center.\nandroidAutoDeleteAfterUpload | `boolean` | (Android only) Used to set if files should be deleted automatically after upload.\nandroidMaxRetries | `number` | (Android only) Used to set the maximum retry count. The default retry count is 0. https://github.com/gotev/android-upload-service/wiki/Recipes#backoff\nandroidAutoClearNotification | `boolean` | (Android only) Used to set if notifications should be cleared automatically upon upload completion. Default is false. Please note that setting this to true will also disable the ringtones.\nandroidRingToneEnabled | `boolean` | (Android only) Used to set if a ringtone should be played upon upload completion. Default is true. Please note that this flag has no effect when `androidAutoClearNotification` is set to true.\nandroidNotificationChannelID | `string` | (Android only) Used to set the channel ID for the notifications.\n\nThe task object has the following properties and methods, that can be used to get information about the upload:\n\nName | Type | Description\n--- | --- | ---\nupload | `number` | Bytes uploaded.\ntotalUpload | `number` | Total number of bytes to upload.\nstatus | `string` | One of the following: `error`, `uploading`, `complete`, `pending`, `cancelled`.\ndescription | `string` | The description set in the request used to create the upload task.\ncancel()| `void` | Call this method to cancel an upload in progress.\n\n### Handling upload events\n\nAfter the upload task is created you can monitor its progress using the following events:\n\n```JavaScript\ntask.on(\"progress\", progressHandler);\ntask.on(\"error\", errorHandler);\ntask.on(\"responded\", respondedHandler);\ntask.on(\"complete\", completeHandler);\ntask.on(\"cancelled\", cancelledHandler); // Android only\n```\n\nEach event handler will receive a single parameter with event arguments:\n\n```JavaScript\n// event arguments:\n// task: Task\n// currentBytes: number\n// totalBytes: number\nfunction progressHandler(e) {\n    alert(\"uploaded \" + e.currentBytes + \" / \" + e.totalBytes);\n}\n\n// event arguments:\n// task: Task\n// responseCode: number\n// error: java.lang.Exception (Android) / NSError (iOS)\n// response: net.gotev.uploadservice.ServerResponse (Android) / NSHTTPURLResponse (iOS)\nfunction errorHandler(e) {\n    alert(\"received \" + e.responseCode + \" code.\");\n    var serverResponse = e.response;\n}\n\n\n// event arguments:\n// task: Task\n// responseCode: number\n// data: string\nfunction respondedHandler(e) {\n    alert(\"received \" + e.responseCode + \" code. Server sent: \" + e.data);\n}\n\n// event arguments:\n// task: Task\n// responseCode: number\n// response: net.gotev.uploadservice.ServerResponse (Android) / NSHTTPURLResponse (iOS)\nfunction completeHandler(e) {\n    alert(\"received \" + e.responseCode + \" code\");\n    var serverResponse = e.response;\n}\n\n// event arguments:\n// task: Task\nfunction cancelledHandler(e) {\n    alert(\"upload cancelled\");\n}\n```\n\n## Testing the plugin\n\nIn 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. `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:\n\n```bash\ncd demo-server\nnpm i\nnode server 8080\n```\n\nThe 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.\n\n\u003eNote: 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, `http://10.0.2.2:8080` should be used instead.\n\n## Contribute\n\nWe love PRs! Check out the [contributing guidelines](CONTRIBUTING.md). If you want to contribute, but you are not sure where to start - look for [issues labeled `help wanted`](https://github.com/NativeScript/nativescript-background-http/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22).\n\n## Get Help\n\nPlease, use [github issues](https://github.com/NativeScript/nativescript-background-http/issues) strictly for [reporting bugs](CONTRIBUTING.md#reporting-bugs) or [requesting features](CONTRIBUTING.md#requesting-new-features). For general questions and support, check out [Stack Overflow](https://stackoverflow.com/questions/tagged/nativescript) or ask our experts in [NativeScript community Slack channel](http://developer.telerik.com/wp-login.php?action=slack-invitation).\n\n## License\n\nApache License Version 2.0, January 2004\n![](https://ga-beacon.appspot.com/UA-111455-24/nativescript/nativescript-background-http?pixel)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnativescript%2Fnativescript-background-http","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnativescript%2Fnativescript-background-http","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnativescript%2Fnativescript-background-http/lists"}