6cdc8f23d4
* The getExternalFilesDirs method only returns the USB path for devices running Android 9 (API 28) and below. * On Android 10 (API 29) and above, this method returns null when accessing external storage like USB sticks. * To work around this limitation, we previously appended the /mnt/media_rw/ path manually. While this worked in most cases, it was unreliable across different devices, as the mounted path could vary. * To ensure accurate retrieval of external storage paths, we have switched to the StorageService API. * This API, introduced in Android 11 (API 30), directly provides the actual mount paths for all external storage devices, including SD cards, USB sticks, and external hard drives. * For Android 9 and below, getExternalFilesDirs continues to work as expected, so we use it where applicable. * This improvement ensures that USB and SD card paths are retrieved correctly on modern Android devices. * Added debugging logs to capture errors when opening a file in the reader. * These logs will help us diagnose issues when users share a diagnostic report.
Kiwix Android
Kiwix is an offline reader for Web content, primarily designed to make Wikipedia available offline. It reads archives in the ZIM file format, a highly compressed open format with additional metadata. This is the Android version of Kiwix, with support versions ranging from 7.1 to 15. The app is written in Kotlin.
Important Notes
Starting from Android 11, Google introduced a restrictive policy that affects the Kiwix Play Store variant. Users can no longer directly load ZIM files from internal or external storage. The storage scanning feature has also been removed in the Play Store variant.
Actually, Kiwix Play Store variant can only directly scan/read ZIM files in reserved app directories:
| Directory name | Storage path | Readable by File manager |
|---|---|---|
| Internal public | storage/0/Android/media/org.kiwix.kiwixmobile/ |
Yes |
| Internal private | storage/0/Android/data/org.kiwix.kiwixmobile/ |
No |
| External public | storage/sdcard-name/Android/media/org.kiwix.kiwixmobile/ |
Yes |
| External private | storage/sdcard-name/Android/data/org.kiwix.kiwixmobile/ |
No |
Workaround
For ZIM files downloaded through third-party apps, users can use the file picker in Kiwix to select and move these files to one of the Kiwix app's public directories (see above). This operation can be also done manually.
Be careful: Before uninstalling Kiwix, move ZIM files outside the app directory to avoid deletion.
To use the full version of Kiwix and avoid facing this restriction, you can download it directly from the official repository or use IzzyOnDroid.
We understand that this restriction may cause inconvenience, but it is necessary to comply with the Play Store policies and ensure a smooth user experience. We recommend using the official version of the app available on our website to access the complete set of features.
App variants
Starting from version 3.12.0, Kiwix is available in two variants:
- Google Play version using application id
org.kiwix.kiwixmobile - Full version using application id
org.kiwix.kiwixmobile.standalone
Differences
Google Play version: Limited to scanning and opening ZIM files from reserved app directories. Full version: Can load ZIM files from any storage location using the file picker.
Why two variants?
To avoid confusion between the Google Play version and the full version, we introduced dedicated application ids (one for each variant). Using the same application id for both versions caused conflicts with the Google Play Store, as it treated them as the same app. This resulted in scenarios where Google Play would prompt updates for the full version. If users updated through the Play Store, they would lose advanced file management capabilities (such as scanning storage or directly opening ZIM files using the file picker).
This separation ensures clarity for users and prevents undesirable behavior.
How to move content between two variants?
Bookmarks: Export and reimport them via the "Settings" menu.
ZIM files: Move them to or from the reserved app directories Android/media/org.kiwix.kiwixmobile/ or
Android/data/org.kiwix.kiwixmobile/. This might have to be done for both internal storage and SD card. Kiwix can detect automatically all ZIM files available in your storage. You just need to swipe down in the local "Library" screen and
it will scan your storage and recognize all your ZIM files.
Android permissions needed
Kiwix requires the following permissions to fully work:
ACCESS_FINE_LOCATION: For device discovery on Android 12 and below.NEARBY_WIFI_DEVICES: For device discovery on Android 13 and above.READ_EXTERNAL_STORAGE: To access ZIM files.WRITE_EXTERNAL_STORAGE: To download ZIM files and export bookmarks.POST_NOTIFICATIONS: For notifications.MANAGE_EXTERNAL_STORAGE: For storage scanning on Android 11 and above (full version only).
Build instructions
- Clone this repository.
- Import the project with Android Studio.
- Set the Gradle JDK to Java 17.
- Run ./gradlew build from the root directory.
Kiwix Android is a multi-module project, in 99% of scenarios you will want to build the app module in the debug configuration. If you are interested in our custom apps, they have their own repo kiwix-android-custom.
Release
We have an automatic version code generation system based on the current date. However, you can override this by setting the environment variable KIWIX_ANDROID_RELEASE_DATE to a specific date in the YYYY-MM-DD format. This will use the provided date for the version code calculation instead of the current date.
Libraries Used
- 📚 Libkiwix - Kotlin/Java binding for the core Kiwix library.
- 🗡️ Dagger 2 - Dependency injector for Android and Java.
- 🔄 Retrofit - Turns REST API into a Java interface.
- 🌐 OkHttp - HTTP client for Android and Java.
- 🎭 Mockito - Mocking framework for unit tests.
- ⚡ RxJava - Reactive Extensions for the JVM.
- 🗃️ ObjectBox - Reactive NoSQL Database.
- 🐒 MockK - Kotlin mocking library.
- 🧪 JUnit5 - Next-generation JUnit.
- 📥 Fetch - File download manager library for Android.
- 🧪 AssertJ - Fluent assertions for test code.
- 📷 ZXing - Barcode scanning library for Java, Android.
Contributing
Before contributing check out the CONTRIBUTION. We have automated Unit & Integration tests that run locally and on pull requests.
Communication
- Slack: #android channel Get an invite
For more information, please refer to https://wiki.kiwix.org/wiki/Communication.
Support
If you're enjoying using Kiwix, drop a ⭐️ on the repo!