Revision control
Copy as Markdown
# [Android Components](../../../README.md) > Feature > Downloads
Feature implementation for apps that want to use [Android downloads manager](https://developer.android.com/reference/android/app/DownloadManager).
## Usage
### Setting up the dependency
Use Gradle to download the library from [maven.mozilla.org](https://maven.mozilla.org/) ([Setup repository](../../../README.md#maven-repository)):
```Groovy
implementation "org.mozilla.components:feature-downloads:{latest-version}"
```
The `AbstractFetchDownloadService` also requires extra permissions needed to post notifications and to start downloads
- `android.permission.POST_NOTIFICATIONS`
- `android.permission.FOREGROUND_SERVICE`
- `android.permission.FOREGROUND_SERVICE_MEDIA_PLAYBACK`
The implementing service in the client app also needs to declare `dataSync` as `foregroundServiceType` in the manifest for
Android 14 compatibility. Adding the `FOREGROUND_SERVICE_DATA_SYNC` permission in the app manifest is not needed since it is declared in feature-downloads module.
### DownloadsFeature
Feature implementation for proving download functionality for the selected session.
```kotlin
//This will be called before starting each download in case you don't have the right permissions
// or if the user removed your permissions.
val onNeedToRequestPermissions = {
session: Session, download: Download ->
//request permission e.g (WRITE_EXTERNAL_STORAGE)
// After you get granted the permissions, remember to call downloadsFeature.onPermissionsGranted()
// to start downloading the pending download.
}
//This will be called after every download is completed.
val onDownloadCompleted = {
download: Download, downloadId: Long ->
//Show some UI to let user know the download was completed.
}
val downloadsFeature =
DownloadsFeature(context,
onNeedToRequestPermissions /*Optional*/,
onDownloadCompleted /*Optional*/,
fragmentManager /*Optional, if it is provided, before every download a dialog will be shown*/,
dialog /*Optional, if it is not provided a simple dialog will be shown before every download, with a positive button and negative button.*/,
sessionManager = sessionManager)
//Starts observing the selected session for new downloads and forward it to
// the download manager
downloadsFeature.start()
//Stop observing the selected session
downloadsFeature.stop()
```
### DownloadDialogFragment
This is general representation of a dialog meant to be used in collaboration with `DownloadsFeature`
to show a dialog before a download is triggered. If `SimpleDownloadDialogFragment` is not flexible enough for your use case you should inherit for this class.
```kotlin
class FocusDialogDownloadFragment : DownloadDialogFragment() {
/*Creating a customized the dialog*/
override fun onCreateDialog(bundle: Bundle?): AlertDialog {
//DownloadsFeature will add these metadata before calling show() on the dialog.
val fileName = arguments?.getString(KEY_FILE_NAME)
//Not used, just for the sake you can use this metadata
val url = arguments?.getString(KEY_URL)
val contentLength = arguments?.getString(KEY_CONTENT_LENGTH)
val builder = AlertDialog.Builder(requireContext())
builder.setCancelable(true)
builder.setTitle(getString(R.string.download_dialog_title))
val inflater = activity!!.layoutInflater
val dialogView = inflater.inflate(R.layout.download_dialog, null)
builder.setView(dialogView)
dialogView.download_dialog_icon.setImageResource(R.drawable.ic_download)
dialogView.download_dialog_file_name.text = fileName
dialogView.download_dialog_cancel.text = getString(R.string.download_dialog_action_cancel)
dialogView.download_dialog_download.text =
getString(R.string.download_dialog_action_download)
dialogView.download_dialog_warning.text = getString(R.string.download_dialog_warning)
setCancelButton(dialogView.download_dialog_cancel)
setDownloadButton(dialogView.download_dialog_download)
return builder.create()
}
private fun setDownloadButton(button: Button) {
button.setOnClickListener {
//Letting know DownloadFeature that can proceed with the download
onStartDownload()
TelemetryWrapper.downloadDialogDownloadEvent(true)
dismiss()
}
}
private fun setCancelButton(button: Button) {
button.setOnClickListener {
TelemetryWrapper.downloadDialogDownloadEvent(false)
dismiss()
}
}
}
//Adding our dialog to DownloadsFeature
val downloadsFeature = DownloadsFeature(
context(),
sessionManager = sessionManager,
fragmentManager = fragmentManager,
dialog = FocusDialogDownloadFragment()
)
downloadsFeature.start()
```
### SimpleDownloadDialogFragment
A confirmation dialog to be called before a download is triggered.
SimpleDownloadDialogFragment is the default dialog if you don't provide a value to DownloadsFeature.
It is composed by a title, a negative and a positive bottoms. When the positive button is clicked the download is triggered.
```kotlin
//To use the default behavior, just provide a fragmentManager/childFragmentManager.
downloadsFeature = DownloadsFeature(
requireContext(),
sessionManager = components.sessionManager,
fragmentManager = fragmentManager /*If you're inside a Fragment use childFragmentManager '*/
)
downloadsFeature.start()
```
Customizing SimpleDownloadDialogFragment.
```kotlin
val dialog = SimpleDownloadDialogFragment.newInstance(
dialogTitleText = R.string.dialog_title,
positiveButtonText = R.string.download,
negativeButtonText = R.string.cancel,
cancelable = true,
themeResId = R.style.your_theme
)
downloadsFeature = DownloadsFeature(
requireContext(),
sessionManager = components.sessionManager,
fragmentManager = fragmentManager,
dialog = dialog
)
downloadsFeature.start()
```
## Facts
This component emits the following [Facts](../../support/base/README.md#Facts):
| Action | Item | Description |
|-----------|--------------|---------------------------------------------------|
| RESUME | notification | The user resumes a download. |
| PAUSE | notification | The user pauses a download. |
| CANCEL | notification | The user cancels a download. |
| TRY_AGAIN | notification | The user taps on try again when a download fails. |
| OPEN | notification | The user opens a downloaded file. |
| DISPLAY | prompt | A download prompt was shown. |
| CANCEL | prompt | A download prompt was canceled. |
## License
This Source Code Form is subject to the terms of the Mozilla Public
License, v. 2.0. If a copy of the MPL was not distributed with this