Ketch
Release 2.0.2
Ketch is a 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.
To integrate Ketch library into your Android project, follow these simple steps:
dependencyResolutionManagement {
repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
repositories {
google()
mavenCentral()
maven { url 'https://jitpack.io' } // this one
}
}dependencies {
implementation 'com.github.khushpanchal:Ketch:2.0.2' // Use latest available version
}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)
.flowOn(Dispatchers.IO)
.collect { downloadModel ->
// use downloadModel
}
}
}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)
ketch.clearDb(downloadModel.id, false) // Pass "false" to skip the actual file deletion (only clear entry from DB)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, failureReason, eTag)
//To observe from Fragment
viewLifecycleOwner.lifecycleScope.launch {
repeatOnLifecycle(Lifecycle.State.STARTED) {
ketch.observeDownloads()
.flowOn(Dispatchers.IO)
.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)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)Custom OKHttp: Provides custom okhttp client
ketch = Ketch.builder().setOkHttpClient(
okHttpClient = OkHttpClient
.Builder()
.connectTimeout(10000L)
.readTimeout(10000L)
.build()
).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)Check out the blog to understand working of Ketch (High Level Design): https://medium.com/@khush.panchal123/ketch-android-file-downloader-library-7369f7b93bd1
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 ?
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.
