You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
The best way to understand how to use the plugin is to study the demo app included in this repo. You can see plugin being used in a TypeScript application by looking at `apps/demo/src/plugin-demos/downloader.ts`.
37
+
The best way to understand how to use the plugin is to study the demo app included in this repo. You can see how the plugin is used in a TypeScript application page by looking at `apps/demo/src/plugin-demos/nativescript-downloader.ts`.
3. The only required option is the URL to be downloaded. You can also pass other options as listed in DownloadOptions before starting the download. You can listen to events emitted by the download during operation in case you want to update a download status message/indicator or handle an error. Upon success, the plugin will return a File reference to the downloaded file located in the app cache directory for Android and the app document's directory for iOS, which can then be used directly by the dev without extra permissions for any other operations on the file.
The only required option is the URL to be downloaded. You can also pass other options as listed in [DownloadOptions](#supported-downloader-options) below before starting the download.
56
+
57
+
You can listen to events emitted by the download during operation in case you want to update a download status message/indicator or handle an error. Upon success, the plugin will return a File reference to the downloaded file located in the app cache directory for Android and the app document's directory for iOS, which can then be used directly by the dev without extra permissions for any other operations on the file.
request?: RequestOptions; //request header strings to be passed to the https connection
78
86
destinationPath?: string; //must be a valid path for app to create a new file (existing directory with valid filename)
79
87
destinationFilename?: string; //must be a string like XXXX[].[YYYYYY] without any path preceding
80
-
copyPicker?: boolean; //present user with UI to choose destination directory
81
-
copyGallery?: boolean; //iOS only, if download has a recognized image/video file name extension, saved to iOS Photos, ignored on Android
82
-
copyDownloads?: boolean; //Android only, uses legacy DIRECTORY_DOWNLOADS, or MediaStore for 29+
88
+
copyPicker?: boolean; //present user with UI to choose destination directory to save a copy of download
89
+
copyGallery?: boolean; //iOS only, if download has a recognized image/video file name extension, save a copy to iOS Photos, ignored on Android
90
+
copyDownloads?: boolean; //Android only, adds a copy to device Downloads directory using legacy DIRECTORY_DOWNLOADS, or MediaStore for 29+
83
91
notification?: boolean; //Android-only. Show system notification for download success/failure. defaults to false
84
92
}
85
93
```
@@ -100,8 +108,11 @@ By default, the plugin disabled Android system notifications of downloads, which
100
108
101
109
You can choose to enable these notifications which will show the user progress and completion/failure notifications.
102
110
103
-
Android version of the plugin supports two destination copy approaches. First, `copyPicker` will first download the file to the default cache directory, and then present the user with a picker UI so that they select where they'd like a copy saved. This approach avoids permission requirements since the user is involved in the destination choice.
104
-
Second, `copyDownloads` will save a copy to the device's Download directory in case the user wants to use that file in another application from an easy to find location. API versions > 28 use MediaStore, and no extra permissions are necessary. For API versions 28 and below, you'll need to ensure you have Android Manifest permissions defined using:
111
+
Android version of the plugin supports two destination copy approaches:
112
+
113
+
1. `copyPicker` will first download the file to the default cache directory, and then present the user with a picker UI so that they select where they'd like a copy saved. This approach avoids permission requirements since the user is involved in the destination choice.
114
+
115
+
2. `copyDownloads` will save a copy to the device's Download directory in case the user wants to use that file in another application from an easy to find location. API versions > 28 use MediaStore, and no extra permissions are necessary. For API versions 28 and below, you'll need to ensure you have Android Manifest permissions defined using:
105
116
106
117
```xml
107
118
<manifest ...>
@@ -113,20 +124,21 @@ Second, `copyDownloads` will save a copy to the device's Download directory in c
113
124
114
125
iOS applications will download files by default to the application's documents directory, which is defined in Nativescript as `knownFolders.documents()` and does not require any extra permissions from the user. This also has the advantage of being the location where an application can make downloaded files visible to other apps once it has been configured as a document provider.
115
126
116
-
The iOS version of the plugin supports two destination copy approaches. First, `copyPicker` will first download the file to the application documents directory, and then present the user with a picker UI so that they can select where they'd like a copy saved. This approach avoids permission requirements since the user is involved in the destination choice. Note: This is only available on iOS 13+
127
+
The iOS version of the plugin supports two destination copy approaches:
128
+
1. `copyPicker` will first download the file to the application documents directory, and then present the user with a picker UI so that they can select where they'd like a copy saved. This approach avoids permission requirements since the user is involved in the destination choice. Note: This is only available on iOS 13+
117
129
118
-
Second,`copyGallery` will save a copy to the device's Photos Gallery in case the user wants to use that file in another application from an easy to find location. This approach requires the user to grant photo library permission first in order to save the downloaded file. Your app might be rejected from the Apple App Store if you do not provide a description about why you need this permission. The default message "Requires access to photo library." might not be enough for the App Store reviewers. You can customize it by editing the `app/App_Resources/iOS/Info.plist` file in your app and adding something like the following:
130
+
2.`copyGallery` will save a copy to the device's Photos Gallery in case the user wants to use that file in another application from an easy to find location. This approach requires the user to grant photo library permission first in order to save the downloaded file. Your app might be rejected from the Apple App Store if you do not provide a description about why you need this permission. The default message "Requires access to photo library." might not be enough for the App Store reviewers. You can customize it by editing the `app/App_Resources/iOS/Info.plist` file in your app and adding something like the following:
119
131
120
-
```xml
121
-
<key>NSPhotoLibraryUsageDescription</key>
122
-
<string>Requires access to save downloaded media to photo library.</string>
123
-
```
132
+
```xml
133
+
<key>NSPhotoLibraryUsageDescription</key>
134
+
<string>Requires access to save downloaded media to photo library.</string>
135
+
```
124
136
125
137
> **NOTE**: if you do use the perms plugin in a production app, make sure to read their README.md first, as using this plugin in production apps will require you to add all iOS Info.plist permission strings to avoid being rejected by automatic processing since the plugin includes code for all permission types.
126
138
127
139
## Acknowledgements
128
140
129
-
This plugin was inspired by https://github.com/tobydeh/nativescript-download-progress/.
141
+
This plugin was inspired by https://github.com/tobydeh/nativescript-download-progress
0 commit comments