Ketch

An Android File downloader library based on WorkManager

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.

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 various callbacks like onQueue, onStart, onProgress, onSuccess, onFailure, onCancel.
• Ketch provide observable flow of download items.
• Ketch can download multiple files in parallel.
• Ketch support cancellation of downloads.
• 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) with cancel action.

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:1.0.0'
}

Usage

• Simplest way to use Ketch:

  • Inside Activity or Fragment, create the instance of Ketch

      private lateinit var ketch: Ketch
      override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        ketch = Ketch.init(this)
      }

  • Call the download() function, pass the url, and get callback

      val request = ketch.download(url,
        onQueue = {},
        onStart = { length -> },
        onProgress = { progress, speedInBytePerMs, length -> },
        onSuccess = { },
        onFailure = { error -> },
        onCancel = { }
      )

  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(request.id)

• 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.init(this,
               notificationConfig = NotificationConfig(
                   enabled = true,
                   smallIcon = R.drawable.ic_launcher_foreground // It is required to pass the smallIcon for notification.
               )
             )

Customisation

• Provide file name and path for download. (It is recommended to pass the fileName or library will assign random name)

  ketch.download(url,
   path, //Default path: Download directory
   fileName //Default fileName: Random UUID.
  )

• Provide headers with network request.

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

• Tag: Group various downloads by providing additional Tag. (This tag can be use to cancel the download as well)

  ketch.download(url,
   tag = tag, //Default: null
  )

• Cancellation: In addition to cancel by request id, provides cancellation by tag and cancel all downloads.

    ketch.cancel(tag)

    ketch.cancelAll()

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

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

    // To stop observing
    ketch.stopObserving()

• Download config: Provides custom connect and read timeout

    ketch = Ketch.init(this,
                downloadConfig = DownloadConfig(
                    connectTimeOutInMs = 20000L, //Default: 10000L
                    readTimeOutInMs = 15000L //Default: 10000L
                )
              )

• Notification config: Provide custom notification config

    ketch = Ketch.init(this,
                notificationConfig = 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
                )
              )

Blog

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

Contact Me

• LinkedIn
• Twitter
• Gmail

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.