mirror of
https://github.com/zoriya/react-native-background-downloader.git
synced 2026-06-08 12:00:49 +00:00
update README
This commit is contained in:
Elad Gil
@@ -3,6 +3,17 @@
|
||||
|
||||
A library for React-Native to help you download large files on iOS and Android both in the foreground and most impotently in the background.
|
||||
|
||||
### Why?
|
||||
On iOS, if you want to download big files no matter the state of your app, wether it's in the background or terminated by the OS, you have to use a system API called `NSURLSession`.
|
||||
|
||||
This API handles your downloads separately from your app and only keeps it informed using delegates.
|
||||
|
||||
On Android we are simulating this process with a separate service dedicated to just downloading to make sure your downloads don't stop even if your main activity is.
|
||||
|
||||
The real challenge using this method it making sure the app's UI if always up-to-date with the downloads that are happening in another process because your app might startup from scratch while the downloads are still running.
|
||||
|
||||
`react-native-background-download` gives you an easy API to both downloading large files and re-attaching to those downloads once your app launches again.
|
||||
|
||||
## ToC
|
||||
|
||||
- [Usage](#usage)
|
||||
@@ -25,7 +36,7 @@ A library for React-Native to help you download large files on iOS and Android b
|
||||
1. In XCode, in the project navigator, right click `Libraries` ➜ `Add Files to [your project's name]`
|
||||
2. Go to `node_modules` ➜ `react-native-background-download` and add `RNBackgroundDownload.xcodeproj`
|
||||
3. In XCode, in the project navigator, select your project. Add `libRNBackgroundDownload.a` to your project's `Build Phases` ➜ `Link Binary With Libraries`
|
||||
4. Run your project (`Cmd+R`)<
|
||||
4. Run your project (`Cmd+R`)
|
||||
|
||||
#### Android
|
||||
|
||||
@@ -47,15 +58,17 @@ In your `AppDelegate.m` add the following code:
|
||||
```objc
|
||||
...
|
||||
#import <RNBackgroundDownload.h>
|
||||
|
||||
...
|
||||
...
|
||||
|
||||
- (void)application:(UIApplication *)application handleEventsForBackgroundURLSession:(NSString *)identifier completionHandler:(void (^)())completionHandler
|
||||
{
|
||||
[RNBackgroundDownload setCompletionHandlerWithIdentifier:identifier completionHandler:completionHandler];
|
||||
}
|
||||
|
||||
...
|
||||
```
|
||||
Failing to add this code will result in cancled background downloads.
|
||||
Failing to add this code will result in canceled background downloads.
|
||||
|
||||
## Usage
|
||||
|
||||
@@ -73,12 +86,12 @@ let task = RNBackgroundDownload.download({
|
||||
}).progress((percent) => {
|
||||
console.log(`Downloaded: ${percent * 100}%`);
|
||||
}).done(() => {
|
||||
console.log('Downlaod is done!');
|
||||
console.log('Download is done!');
|
||||
}).error((error) => {
|
||||
console.log('Download canceled due to error: ', error);
|
||||
});
|
||||
|
||||
// Puase the task
|
||||
// Pause the task
|
||||
task.pause();
|
||||
|
||||
// Resume after pause
|
||||
@@ -92,9 +105,9 @@ task.stop();
|
||||
|
||||
This is the main selling point of this library (but it's free!).
|
||||
|
||||
What happens to your downloads after the OS stopped your app? Well, they are still there, we just need to selvage them.
|
||||
What happens to your downloads after the OS stopped your app? Well, they are still running, we just need to re-attach to them.
|
||||
|
||||
Add this code in your app's init stage, and you'll never lose a download again!
|
||||
Add this code to app's init stage, and you'll never lose a download again!
|
||||
|
||||
```javascript
|
||||
import RNBackgroundDownload from 'react-native-background-download';
|
||||
@@ -126,13 +139,13 @@ Download a file to destination
|
||||
|
||||
An object containing options properties
|
||||
|
||||
| Property | Type | Required | Platforms | Info |
|
||||
| ------------- | --------------- | :------: | :-------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `id` | String | ✅ | All | Unique ID you give to this download. This ID will help identifying the download task when it is returned to you when the app re-launches |
|
||||
| `url` | String | ✅ | All | URL to file you want to download |
|
||||
| `destination` | String | ✅ | All | Where to copy the file to once the download is done |
|
||||
| `priority` | [Priority (enum)](#priority-enum---android-only) | | Android | The priority of the download. On Android, simultaneous downloads is limited to 4 and the rest are queued, priority helps picking the next download. **Default:** Priority.MEDIUM |
|
||||
| `network` | [Network (enum)](#network-enum---android-only) | | Android | Give your the ability to limit the download to WIFI only. **Default:** Network.ALL |
|
||||
| Property | Type | Required | Platforms | Info |
|
||||
| ------------- | ------------------------------------------------ | :------: | :-------: | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `id` | String | ✅ | All | A Unique ID to provide for this download. This ID will help to identify the download task when the app re-launches |
|
||||
| `url` | String | ✅ | All | URL to file you want to download |
|
||||
| `destination` | String | ✅ | All | Where to copy the file to once the download is done |
|
||||
| `priority` | [Priority (enum)](#priority-enum---android-only) | | Android | The priority of the download. On Android, downloading is limited to 4 simultaneous instances where further downloads are queued. Priority helps in deciding which download to pick next from the queue. **Default:** Priority.MEDIUM |
|
||||
| `network` | [Network (enum)](#network-enum---android-only) | | Android | Give your the ability to limit the download to WIFI only. **Default:** Network.ALL |
|
||||
|
||||
**returns**
|
||||
|
||||
@@ -165,7 +178,7 @@ All callback methods return the current instance of the `DownloadTask` for chain
|
||||
|
||||
| Function | Callback Arguments | Info |
|
||||
| ---------- | --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `begin` | expectedBytes | Called when the first byte is received. 💡: this is good place to check the device has enough storage space for this download |
|
||||
| `begin` | expectedBytes | Called when the first byte is received. 💡: this is good place to check if the device has enough storage space for this download |
|
||||
| `progress` | percent, bytesWritten, totalBytes | Called at max every 1.5s so you can update your progress bar accordingly |
|
||||
| `done` | | Called when the download is done, the file is at the destination you've set |
|
||||
| `error` | error | Called when the download stops due to an error |
|
||||
@@ -185,7 +198,7 @@ Stops the download for good and removes the file that was written so far
|
||||
|
||||
### `documents`
|
||||
|
||||
And absolute path to the app's documents directory, a good path to download files to.
|
||||
An absolute path to the app's documents directory. It is recommended that you use this path as the target of downloaded files.
|
||||
|
||||
### Priority (enum) - Android only
|
||||
|
||||
|
||||
Reference in New Issue
Block a user