Ketch

Ketch: An Easy-to-Use File Downloader for Android

Overview of Ketch

Ketch is an Android library designed to simplify file downloading within mobile applications. Developed in Kotlin, it leverages the capabilities of WorkManager to enable reliable downloads in various states of app usage. It ensures downloads are completed unless explicitly canceled or they fail.

Features of Ketch

• Versatile Download Support: Ketch can handle a variety of file types including images (jpg, png, gif), videos (mp4), audio (mp3), documents (pdf), and many others.
• Reliability: Once initiated, downloads are assured until manual cancellation or failure, providing a robust download management experience.
• Detailed Information: During a download, users receive detailed information such as speed, file size, and progress.
• Control Over Downloads: Users have the flexibility to pause, resume, cancel, retry, or delete downloads.
• Parallel Downloads: Ketch supports the simultaneous download of multiple files, enhancing efficiency.
• Support for Large Files: Even large files can be managed and downloaded seamlessly.
• Customizations: Users can customize timeouts, utilize a custom OkHttpClient, and create personalized notifications.
• Ease of Use: The library is designed to be straightforward, making it user-friendly even for those new to Android development.
• Notifications: Users receive notifications about their downloads which include speed, estimated time remaining, file size, and progress.

Getting Started with Ketch

To start using Ketch in an Android project, follow these steps:

Installation

1. Update your settings.gradle file to include the JitPack repository.

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

2. Add the Ketch dependency to your project's build.gradle file.

   dependencies {
     implementation 'com.github.khushpanchal:Ketch:2.0.2'
   }
   

Basic Usage

• Initialization: Initialize Ketch in your application's onCreate method.

  private lateinit var ketch: Ketch
  override fun onCreate() {
    super.onCreate()
    ketch = Ketch.builder().build(this)
  }
  

• Downloading Files: Call the download() method with the file URL, name, and path. You can also observe download status using Kotlin’s Flow.

  val id = ketch.download(url, fileName, path)
  lifecycleScope.launch {
    repeatOnLifecycle(Lifecycle.State.STARTED) {
      ketch.observeDownloadById(id)
        .flowOn(Dispatchers.IO)
        .collect { downloadModel -> 
          // handle the download model
        }
    }
  }
  

• Control Options: Easily pause, resume, retry, or cancel downloads using provided methods.

  ketch.cancel(downloadModel.id)
  ketch.pause(downloadModel.id)
  ketch.resume(downloadModel.id)
  ketch.retry(downloadModel.id)
  

• Customization and Notifications: Customize download settings such as network request headers, download configuration, and notification settings.

  ketch = Ketch.builder().setNotificationConfig(
    config = NotificationConfig(
      enabled = true,
      smallIcon = R.drawable.ic_launcher_foreground
    )
  ).build(this)
  

Permissions

To ensure full functionality, make sure to add necessary permissions like FOREGROUND_SERVICE_DATA_SYNC, WAKE_LOCK, and INTERNET in your project.

Customization Options

Ketch offers various customization possibilities:

• Headers and Tags: Add headers to your network requests and group downloads with tags.
• Download Config: Set custom connection and read timeouts.
• Use a Custom OkHttpClient: Integrate a tailored OkHttpClient for more control over network settings.
• Notification Customization: Tailor the download notifications to better suit your app’s needs.

Conclusion

Ketch is a powerful tool for developers looking to implement file download capabilities in Android apps efficiently. Its ease of use, coupled with extensive customization options, makes it a versatile choice for both novice and experienced developers. Whether you are dealing with large files or multiple simultaneous downloads, Ketch provides a seamless, reliable solution.

For more in-depth details, conceptual diagrams, and usage examples, refer to the developer's GitHub repository or explore the blog post explaining the high-level design of Ketch.