From d20445c34540805b63dfbe5eadb8242058986893 Mon Sep 17 00:00:00 2001 From: Elad Gil Date: Tue, 29 May 2018 10:39:24 +0300 Subject: [PATCH] update README --- README.md | 45 +++++++++++++++++++++++++++++---------------- 1 file changed, 29 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index 841518f..f41b233 100644 --- a/README.md +++ b/README.md @@ -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 + ... -... + - (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