From ef5eb5bca8629d990a58cfe627f9a3363fde39d7 Mon Sep 17 00:00:00 2001 From: MohitMaliFtechiz Date: Tue, 31 Dec 2024 14:41:55 +0530 Subject: [PATCH 1/4] Disabled the dependencies metadata for Singed APK. * Added comments in build.gradle.kts file of app module to inform devs why this is required and why we have disable this for APKs. --- app/build.gradle.kts | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/app/build.gradle.kts b/app/build.gradle.kts index 3ce7bbb88f..eb0ec5e9f4 100644 --- a/app/build.gradle.kts +++ b/app/build.gradle.kts @@ -87,6 +87,27 @@ android { java.srcDirs("$rootDir/core/src/sharedTestFunctions/java") } } + // By default, Android generates dependency metadata (a file containing information + // about all the dependencies used in the project) and includes it in both APKs and app bundles. + // This metadata is particularly useful for the Google Play Store, as it provides actionable + // feedback on potential issues with project dependencies. However, other platforms cannot + // utilize this metadata. For example, platforms like IzzyOnDroid, GitHub, and our website do not + // require or utilize the metadata. + // Since we only upload app bundles to the Play Store for kiwix app, dependency metadata + // is enabled for app bundles to leverage Google Play Store's analysis + // and feedback. For APKs distributed outside the Play Store, we exclude this metadata + // as they do not require this. + // See https://github.com/kiwix/kiwix-android/issues/4053#issuecomment-2456951610 for details. + dependenciesInfo { + // Disables dependency metadata when building APKs. + // This is for the signed APKs posted on IzzyOnDroid, GitHub, and our website, + // where dependency metadata is not required or utilized. + includeInApk = false + // Enables dependency metadata when building Android App Bundles. + // This is specifically for the Google Play Store, where dependency metadata + // is analyzed to provide actionable feedback on potential issues with dependencies. + includeInBundle = true + } } play { From 91a382a39a937672ae2acc36073373ca694661c5 Mon Sep 17 00:00:00 2001 From: MohitMaliFtechiz Date: Tue, 31 Dec 2024 16:28:48 +0530 Subject: [PATCH 2/4] Added the information about permissions used in the application in the README file to show users why and where we are using these permissions. --- README.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/README.md b/README.md index a707bfe627..cc65546388 100644 --- a/README.md +++ b/README.md @@ -61,6 +61,21 @@ Kiwix Android is written in [Kotlin](https://kotlinlang.org/) [![Public Chat](https://img.shields.io/badge/public-chat-green)](https://chat.kiwix.org) [![Slack](https://img.shields.io/badge/Slack-chat-E01E5A)](https://kiwixoffline.slack.com) +## App permissions + +Our application requests the following permissions, which are necessary for its functionality: + +- `ACCESS_FINE_LOCATION`: Required on devices running Android 12 and below to discover nearby + devices when transferring ZIM files. +- `NEARBY_WIFI_DEVICES`: Required on devices running Android 13 and above to discover nearby devices + for transferring ZIM files. +- `READ_EXTERNAL_STORAGE`: Required to access and read ZIM files stored on the device. +- `WRITE_EXTERNAL_STORAGE`: Required to download ZIM files, export bookmarks, save notes, etc. +- `POST_NOTIFICATIONS`: Required to display notifications for ongoing downloads, active hotspots, + and the read-aloud feature. +- `MANAGE_EXTERNAL_STORAGE`: Required on Android 11 and above to scan the storage and locate all + ZIM files. This permission is only available in the full version of the application. + ## Build instructions To build Kiwix Android, clone [this From b2e42748b42eaf8472b3db0d78f84096de88de66 Mon Sep 17 00:00:00 2001 From: MohitMaliFtechiz Date: Tue, 31 Dec 2024 16:47:22 +0530 Subject: [PATCH 3/4] Updated the outdated content of the README file. As now we have the file picker functionality in our PS variant, and README was showing that there is no file picker in PS variant. --- README.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index cc65546388..5c5295649c 100644 --- a/README.md +++ b/README.md @@ -17,7 +17,7 @@ with additional metadata. This is the version for Android, with [support versions ranging from 7.1 to 13](https://github.com/kiwix/kiwix-android/blob/main/buildSrc/src/main/kotlin/Config.kt). -**Important Note**: Starting from Android 11, the ZIM file picker +**Important Note**: Starting from Android 11, the storage scanning feature has been restricted in the [Play Store variant](https://play.google.com/store/apps/details?id=org.kiwix.kiwixmobile) due to Play Store policies. This means that users running Android 11 @@ -27,9 +27,11 @@ Google Play Store. This restriction is in place to comply with the Play Store policies. The Play Store variant of Kiwix does not require the `MANAGE_EXTERNAL_STORAGE` permission anymore, which is necessary to scan storage and access ZIM files at arbitrary locations. -Therefore, the storage scanning & file picking functionalities are not +Therefore, the storage scanning functionality is not available in this variant anymore. For already downloaded ZIM files, You can copy -them to the `Android/media/org.kiwix.kiwixmobile/` folder, and the application will read them. +them to the `Android/media/org.kiwix.kiwixmobile/` folder or you can use file picker to select the +ZIM files from storage and it will copy/move the ZIM files in this folder based on your choice +, and the application will read them. Before uninstalling the application, please ensure that you move all your ZIM files from this folder, as they will be automatically deleted when the application is uninstalled or if the application data is cleared. To use the full version of Kiwix From 7313a12005cc85d9e7c82569a5a5ecc8312941c0 Mon Sep 17 00:00:00 2001 From: Emmanuel Engelhart Date: Wed, 1 Jan 2025 14:40:32 +0100 Subject: [PATCH 4/4] Rephrase a bit the README --- README.md | 88 +++++++++++++++++++++++++++++-------------------------- 1 file changed, 46 insertions(+), 42 deletions(-) diff --git a/README.md b/README.md index 5c5295649c..de89d170c9 100644 --- a/README.md +++ b/README.md @@ -10,50 +10,14 @@ Kiwix is an offline reader for Web content. One of its main purposes is to make [Wikipedia](https://www.wikipedia.org/) available -offline. This is achieved by reading the content of a file in the -[ZIM](https://openzim.org) format, a highly compressed open format +offline. This is achieved by reading archives in the +[ZIM](https://openzim.org) file format, a highly compressed open format with additional metadata. This is the version for Android, with [support versions ranging from 7.1 -to 13](https://github.com/kiwix/kiwix-android/blob/main/buildSrc/src/main/kotlin/Config.kt). +to 15](https://github.com/kiwix/kiwix-android/blob/main/buildSrc/src/main/kotlin/Config.kt). -**Important Note**: Starting from Android 11, the storage scanning -feature has been restricted in the [Play Store -variant](https://play.google.com/store/apps/details?id=org.kiwix.kiwixmobile) -due to Play Store policies. This means that users running Android 11 -and above will not be able to load ZIM files from internal/external -storage directly within the app if they have downloaded Kiwix from the -Google Play Store. This restriction is in place to comply with the -Play Store policies. The Play Store variant of Kiwix does not require -the `MANAGE_EXTERNAL_STORAGE` permission anymore, which is necessary -to scan storage and access ZIM files at arbitrary locations. -Therefore, the storage scanning functionality is not -available in this variant anymore. For already downloaded ZIM files, You can copy -them to the `Android/media/org.kiwix.kiwixmobile/` folder or you can use file picker to select the -ZIM files from storage and it will copy/move the ZIM files in this folder based on your choice -, and the application will read them. -Before uninstalling the application, please ensure that you move all your ZIM files -from this folder, as they will be automatically deleted when the application is uninstalled -or if the application data is cleared. To use the full version of Kiwix -and benefit of the ZIM file picker feature, you can download it -directly from the [official -repository](https://download.kiwix.org/release/kiwix-android/) or use -[IzzyOnDroid](https://apt.izzysoft.de/fdroid/index/apk/org.kiwix.kiwixmobile). 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. - -Possible paths for play store version which supports for the scanning/reading ZIM files. - -| Storage path | Viewable outside kiwix(in File manager) | Could be scanned by Kiwix | -|-----------------------------------------------------------|-----------------------------------------|---------------------------| -| storage/0/Android/media/org.kiwix.kiwixmobile/ | Yes | Yes | -| storage/0/Android/data/org.kiwix.kiwixmobile/ | No | Yes | -| storage/sdcard-name/Android/media/org.kiwix.kiwixmobile/ | Yes | Yes | -| storage/sdcard-name/Android/data/org.kiwix.kiwixmobile/ | No | Yes | - -Kiwix Android is written in [Kotlin](https://kotlinlang.org/) +Kiwix Android is written in [Kotlin](https://kotlinlang.org/). [![Build Status](https://github.com/kiwix/kiwix-android/workflows/CI/badge.svg?query=branch%3Amain+workflow%3ANightly)](https://github.com/kiwix/kiwix-android/actions?query=workflow%3ACI+branch%3Amain) [![Nightly](https://github.com/kiwix/kiwix-android/actions/workflows/nightly.yml/badge.svg)](https://github.com/kiwix/kiwix-android/actions/workflows/nightly.yml) @@ -63,9 +27,49 @@ Kiwix Android is written in [Kotlin](https://kotlinlang.org/) [![Public Chat](https://img.shields.io/badge/public-chat-green)](https://chat.kiwix.org) [![Slack](https://img.shields.io/badge/Slack-chat-E01E5A)](https://kiwixoffline.slack.com) -## App permissions +## Important Notes + +Starting from Android 11, Google has introduced a new very restrictive +policy which concretly forbids Kiwix [Play Store +variant](https://play.google.com/store/apps/details?id=org.kiwix.kiwixmobile) +users to directly load ZIM files from internal/external storage. For +the same reason, and still only in the Play Store variant, the storage +scanning feature has been removed. + +Actualy, 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 | + +As a workaround, for ZIM files downloaded through third party apps, +Kiwix users can use the file picker (in Kiwix library) to select these +ZIM files... which then will be copied/moved to one of the the Kiwix +app public directories (see above). An operation which can also be +done manually. + +Be careful, before uninstalling Kiwix, if the user wants to keep its +ZIM files, he will have to move them outside of the app +directory. Otherwise, the ZIM file might be removed during the +process. + +To use the full version of Kiwix and avoid to suffer of this +restriction, you can download it directly from the [official +repository](https://download.kiwix.org/release/kiwix-android/) or use +[IzzyOnDroid](https://apt.izzysoft.de/fdroid/index/apk/org.kiwix.kiwixmobile). + +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. + +## Android permissions needed -Our application requests the following permissions, which are necessary for its functionality: +Kiwix requires the following permissions to fully work: - `ACCESS_FINE_LOCATION`: Required on devices running Android 12 and below to discover nearby devices when transferring ZIM files.