Ketch

An Android File downloader library based on WorkManager with pause and resume support

About Ketch

Ketch is simple, powerful, customisable file downloader library for Android built entirely in Kotlin. It simplifies the process of downloading files in Android applications by leveraging the power of WorkManager. Ketch guarantees the download irrespective of application state.

High level design

Why use Ketch

Ketch can download any type of file. (jpg, png, gif, mp4, mp3, pdf, apk and many more)
Ketch guarantees file download unless cancelled explicitly or download is failed.
Ketch provide all download info including speed, file size, progress.
Ketch provide option to pause, resume, cancel, retry and delete the download file.
Ketch provide option to observe download items (or single download item) as Flow.
Ketch can download multiple files in parallel.
Ketch support large file downloads.
Ketch provide various customisation including custom timeout and custom notification.
Ketch is simple and very easy to use.
Ketch provide notification for each download providing download info (speed, time left, total size, progress).
Ketch includes option to pause, resume, retry and cancel download from notification.

High level design

How to use Ketch

Installation

To integrate Ketch library into your Android project, follow these simple steps:

Update your settings.gradle file with the following dependency.

dependencyResolutionManagement {
  repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
  repositories {
    google()
    mavenCentral()
    maven { url 'https://jitpack.io' } // this one
  }
}

Update your module level build.gradle file with the following dependency.

dependencies {
  implementation 'com.github.khushpanchal:Ketch:2.0.1' // Use latest available version
}

Usage

Simplest way to use Ketch:
- Create the instance of Ketch in application onCreate. (Ketch is a singleton class and instance will create automatically on first use)
```
  private lateinit var ketch: Ketch
  override fun onCreate() {
    super.onCreate()
    ketch = Ketch.builder().build(this)
  }
```
- Call the download() function, pass the url, fileName, path and observe the download status
```
  val id = ketch.download(url, fileName, path)
  lifecycleScope.launch {
    repeatOnLifecycle(Lifecycle.State.STARTED) {
      ketch.observeDownloadById(id)
        .collect { downloadModel -> 
          // use downloadModel
        }
    }
  }
```
Important Note: Add the appropriate storage permission based on API level or onFailure(error) callback will be triggered. Check out sample app for reference.

To cancel the download

  ketch.cancel(downloadModel.id) // other options: cancel(tag), cancelAll()

To pause the download

  ketch.pause(downloadModel.id) // other options: pause(tag), pauseAll()

To resume the download

  ketch.resume(downloadModel.id) // other options: resume(tag), resumeAll()

To retry the download

  ketch.retry(downloadModel.id) // other options: retry(tag), retryAll()

To delete the download

  ketch.clearDb(downloadModel.id) // other options: clearDb(tag), clearAllDb(), clearDb(timeInMillis)

Observing: Provides state flow of download items (Each item carries download info like url, fileName, path, tag, id, timeQueued, status, progress, length, speed, lastModified, metaData, failureReson, eTag)

//To observe from Fragment
viewLifecycleOwner.lifecycleScope.launch {
  repeatOnLifecycle(Lifecycle.State.STARTED) {
    ketch.observeDownloads()
      .collect { 
         //set items to adapter
      }
  }
}

To enable the notification:

Add the notification permission in manifest file.

<uses-permission android:name="android.permission.POST_NOTIFICATIONS"/>

Request permission from user (required from Android 13 (API level 33)). Check out sample app for reference.

Pass the notification config while initialization

ketch = Ketch.builder().setNotificationConfig(
      config = NotificationConfig(
        enabled = true,
        smallIcon = R.drawable.ic_launcher_foreground // It is required to pass the smallIcon for notification.
      )
    ).build(this)

Customisation

Provide headers with network request.

ketch.download(url, fileName, path,
headers = headers, //Default: Empty hashmap
)

Tag: Group various downloads by providing additional Tag. (This tag can be use to cancel, pause, resume, delete the download as well)
```
ketch.download(url, fileName, path,
tag = tag, //Default: null
)
```

Download config: Provides custom connect and read timeout

ketch = Ketch.builder().setDownloadConfig(
  config = DownloadConfig(
    connectTimeOutInMs = 20000L, //Default: 10000L
    readTimeOutInMs = 15000L //Default: 10000L
  )
).build(this)

Notification config: Provide custom notification config

ketch = Ketch.builder().setNotificationConfig(
  config = NotificationConfig(
    enabled = true, //Default: false
    channelName = channelName, //Default: "File Download"
    channelDescription = channelDescription, //Default: "Notify file download status"
    importance = importance, //Default: NotificationManager.IMPORTANCE_HIGH
    smallIcon = smallIcon, //It is required
    showSpeed = true, //Default: true
    showSize = true, //Default: true
    showTime = true //Default: true
  )
).build(this)

Blog

Check out the blog to understand working of Ketch (High Level Design): https://medium.com/@khush.panchal123/ketch-android-file-downloader-library-7369f7b93bd1

High level Design

Contact Me

Check out my blogs: https://medium.com/@khush.panchal123

If this project helps you, show love ❤️ by putting a ⭐ on this project ✌️

Contribute to the project

Feel free to provide feedback, report an issue, or contribute to Ketch. Head over to GitHub repository, create an issue or find the pending issue. All pull requests are welcome 😄

License

   Copyright (C) 2024 Khush Panchal

   Licensed under the Apache License, Version 2.0 (the "License");
   you may not use this file except in compliance with the License.
   You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.

khushpanchal / Ketch

readme