npm package: @ngenux/react-native-background-downloader
Description: A React-Native library designed to facilitate file downloads.
Author: Sushil Shinde
Latest version: 0.1.4

# @ngenux/react-native-background-downloader

A React Native library designed to facilitate the downloading of large files on both iOS and Android, with the ability to perform downloads both in the foreground as well as background.
## Why it's useful?
To download large files on iOS, regardless of your app's state (whether it's running in the background or terminated by the OS), you need to utilize the system API known as  [NSURLSession](https://developer.apple.com/documentation/foundation/nsurlsession). This API manages downloads independently from your app and provides updates through delegates (Learn More: Background File Downloads).

On Android, we achieve a similar functionality using the system API known as  [DownloadManager](https://developer.android.com/reference/android/app/DownloadManager).

The primary challenge in using this approach is ensuring that your app's user interface remains synchronized with ongoing downloads that may continue even if your app restarts from scratch.

react-native-background-downloader offers a straightforward API for downloading large files and seamlessly reconnecting to those downloads when your app relaunches.
## Installation

```sh
npm install @ngenux/react-native-background-downloader
```
## Getting started
```sh
npm install @ngenux/react-native-background-downloader --save
```
### Mostly automatic installation
```sh
$ react-native link @ngenux/react-native-background-downloader
```
### Manual installation




#### Android

1. Open up `android/app/src/main/java/[...]/MainActivity.java`
  - Add `import com.ngenux.reactnativebackgrounddownloader.ReactNativeBackgroundDownloaderPackage;` to the imports at the top of the file
  - Add `new ReactNativeBackgroundDownloaderPackage()` to the list returned by the `getPackages()` method
2. Append the following lines to `android/settings.gradle`:
  	```
  	include ':react-native-background-downloader'
  	project(':react-native-background-downloader').projectDir = new File(rootProject.projectDir, 	'../node_modules/@ngenux/react-native-my-native-module/android')
  	```
3. Insert the following lines inside the dependencies block in `android/app/build.gradle`:
  	```
      compile project(':react-native-background-downloader')
  	```

# API

## `startDownload` Function

- **Description**: Initiates a file download in the background.
- **Parameters**:
  - `fileUrl` (string): The URL of the file to be downloaded.
  - `destinationPath` (string): The local destination path where the downloaded file will be stored.
- **Returns**: A promise that resolves to download information.

## `checkDownloadStatus` Function

- **Description**: Checks the status of a download using its unique `downloadId`.
- **Parameters**:
  - `downloadId` (string): The identifier for the download.
- **Returns**: A promise that resolves to the download status.

## `cancelDownload` Function

- **Description**: Cancels a download in progress using its `downloadId`.
- **Parameters**:
  - `downloadId` (string): The identifier for the download.
- **Returns**: A promise that resolves when the download is canceled.

## `stopService` Function

- **Description**: Stops the background service responsible for handling download progress on Android.
- **Returns**: A promise that resolves when the service is stopped.

## `deleteDownloadedFile` Function

- **Description**: Deletes a previously downloaded file.
- **Parameters**:
  - `downloadId` (string): The identifier for the download.
  - `url` (string): The URL of the downloaded file.
- **Returns**: A promise that resolves when the file is deleted.

## Event Listeners

These functions allow you to add listeners for specific events related to downloads:

- `addDownloadProgressListener`: Adds a listener for download progress events.
- `addDownloadCompleteListener`: Adds a listener for download completion events. Additionally, it stops the background service on Android after completion.
- `addDownloadFailedListener`: Adds a listener for download failure events.

## Usage

```js
import React, { useEffect, useState } from 'react';
import { View, Text, Button, StyleSheet } from 'react-native';
import {
  addDownloadCompleteListener,
  addDownloadFailedListener,
  addDownloadProgressListener,
  startDownload,
  cancelDownload,
  checkDownloadStatus,
  deleteDownloadedFile,
} from '@ngenux/react-native-background-downloader';

const App = () => {
  const [downloadInfo, setDownLoadInfo] = useState(null);
  const [progress, setProgress] = useState(0);
  useEffect(() => {
    // Add a download progress listener
    addDownloadProgressListener((event) => {
      // @ts-ignore
      setProgress(parseInt(event.progress, 10));
    });

    // Add a download complete listener
    addDownloadCompleteListener((event) => {
      setProgress(parseInt(event.progress, 10));
      setDownLoadInfo((prev) => ({
        // @ts-ignore
        ...prev,
        downloadLocation: `file://${event.downloadLocation}`,
      }));
    });

    // Add a download failed listener
    addDownloadFailedListener((event) => {
      console.log('Download failed:', event);
    });
  }, []);

  const handleStartDownload = async () => {
    try {
      const info = await startDownload(
        'https://commondatastorage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4',
        'DownloadedVideo.mp4'
      );
      setDownLoadInfo(info);
    } catch (error) {
      console.error('Error starting download:', error);
    }
  };
  // @ts-ignore

  const handleCheckDownloadStatus = async () => {
    try {
      // @ts-ignore
      const result = await checkDownloadStatus(downloadInfo?.downloadId);
      console.log('Download status:', result);
    } catch (error) {
      console.error('Error pausing download:', error);
    }
  };
  // @ts-ignore

  const handleCancelDownload = async () => {
    try {
      // @ts-ignore
      const result = await cancelDownload(downloadInfo?.downloadId);
      console.log('Download canceled:', result);
    } catch (error) {
      console.error('Error canceling download:', error);
    }
  };
  // @ts-ignore

  const handleDeleteFile = async () => {
    try {
      // @ts-ignore
      console.log(downloadInfo?.downloadLocation);
      const result = await deleteDownloadedFile(
        // @ts-ignore
        downloadInfo?.downloadId,
        // @ts-ignore
        downloadInfo?.downloadLocation.replace('file://', '')
      );
      console.log('File deleted:', result);
    } catch (error) {
      console.error('Error deleting file:', error);
    }
  };

  return (
    <View style={styles.container}>
      <Text>Background Download Example </Text>
      <Text>Progress : {progress} %</Text>
      {/*  @ts-ignore */}
      <Text>Location : {downloadInfo?.downloadLocation}</Text>
      {/*  @ts-ignore */}
      <Text>Id : {downloadInfo?.downloadId}</Text>

      <Button
        //   @ts-ignore
        style={styles.btn}
        title="Start Download"
        onPress={handleStartDownload}
      />
      <Button
        //   @ts-ignore
        style={styles.btn}
        title="Check Status"
        onPress={handleCheckDownloadStatus}
      />
      <Button
        //   @ts-ignore
        style={styles.btn}
        title="Cancel Download"
        onPress={handleCancelDownload}
      />
      <Button
        //   @ts-ignore
        style={styles.btn}
        title="Delete File"
        onPress={handleDeleteFile}
      />
      <Button
        //   @ts-ignore
        style={styles.btn}
        title="Empty"
        onPress={() => setDownLoadInfo(null)}
      />
    </View>
  );
};
const styles = StyleSheet.create({
  container: {
    flex: 1,
    alignItems: 'center',
    justifyContent: 'space-around',
  },
  btn: { width: '90%' },
});
export default App;


```


---
## License
MIT

## Author


Developed by [ng-sushil](https://github.com/ng-sushil) of [@ngenux](https://www.ngenux.com/)