This project contains data and scripts needed to create specific custom Kiwix Android apps. It does not create the app, that's done separately by running the relevant Gradle command to build one or more custom apps.

Prerequisites

Python 3 for the scripts in Python. On Debian based GNU/Linux you can install it with:

apt-get install python3

Imagemagick is needed by gen-std-icon.py. On Debian based GNU/Linux you can install it with:

apt-get install imagemagick

Android studio is required to generate icon sets and can be downloaded from here.

On macOS, Homebrew allows to install the packages python3 and imagemagick.

Badges

Custom apps use to have icon with two small badges to help user understanding what the app is about:

One reprsenting the language of the content
One representing the stricked WiFi logo to emphasis its offline nature

The script gen-std-icon.py allows to add these two badges easily on a master icon. You can use it that way:

python3 gen-std-icon.py [custom_app_directory]/icon_master.png [optional language code]

The custom_app_directory needs to be one of the listed sub-folders e.g. phet. If this is a new custom app, you will have to create it.

The optional language code parameter for english would be en, if you omit this parameter then no language badge is added, this is desired in a few cases where the language is already clearly indicated by the master icon e.g. wikimedde.

Icon set

The Android custom app needs an Icon set to build properly. This Icon set is a list of bitmap pictures which are derivatives of the Icon master from the section above.

To create this Icon set, follow these steps:

Create a new empty project with Android Studio (add no activity > next > finish)
In the project view (top left) there should be a dropdown that says Android select that and choose Project, this will make the project view display accurately to the file system
Delete MyApplication/app/src/main/res
Right click MyApplication/app in android studio, click New>Image Asset to open Asset Studio (if this option is greyed out you will have to wait for indexing to finish, this shouldn't take longer than 2 minutes)
For foreground layer Source Asset > Asset Type choose Image
For path click the folder icon and browse to the output of gen-std-icon.py
For background layer Source Asset > Asset Type choose Color
Click on the color box
This should present the color chooser, the box in the top right with the label # should be auto selected. Type FFFFFF to supply white as the color, this is typically the color used
[Optional] go back to foreground layer and size the icon as appropriate with the slider
Next > Finish will generate a res folder with all the icons needed in the location where you previously deleted the res folder.
Cut and paste the res folder to kiwix-android-custom/whatever-directory-this-icon-set-is-for

These instructions are for a first time setup, you can reuse this project in the future for icon generation so many steps can be omitted.

Version name

The custom app will have a version name displayed on the Google Play store. This version name has to be a date in the format YYYY-MM (for example 2018-10. This version name should be the date of the content (neither the date of the Software nor the release date).

The app version name is determined in that order:

The date can be hardcoded in the json file at the key version_name. Considering that this needs maintenance and that the publisher can easily create a discrepency with the ZIM content date, this should probably be avoided in most of the time.
If nothing is specified in the json, then it tries to extract it from the ZIM file name. If the file - specified in zim_url - is wikipedia_en_all_maxi_2018-10.zim then it will be 2018-10.
Otherwise the current date will be put (should be avoided).

Releasing

Simply tag the repo in git with the name of a custom app eg wikimed. This triggers a Github action that will build an app using kiwix-android master branch and the icon set/json defined in this repository and then upload it to the Play Console in draft to alpha with an expansion file attached.

This will only work with app updates. To create a new custom app an app must be built manually and submit to the Google Play store

Building Locally

First of all the Kiwix Android needs to be cloned locally:

git clone https://github.com/kiwix/kiwix-android.git

Copy then a custom app directory to kiwix-android/custom/src. If using Android Studio this will add the build variant and you can install as you would any app.

Alternatively - if you are more export - you can run ./gradlew install[CustomAppNameWithFirstLetterCapitalised]Debug eg ./gradlew installPhetDebug from the kiwix-android folder

Testing locally

The custom app, as built and installed by the Gradle script currently does not include the ZIM file but it does prompt you to download the file if it doesn't find an .obb (this is the extension for ZIM files in custom app). So unless you need to test obb file reading you can stop here.

To test reading an .obb file you need the file to be on the device. Here's an overview of the steps involved. You may need to tweak these for your app, environment and device, etc.

Download first the ZIM file to your computer e.g. for PhET download the ZIM file specified in https://github.com/kiwix/kiwix-android-custom/blob/master/phet/info.json by the json key zim_url.

The Android obb dedicated directory is not always at the exact same place on the Android device, usually it can be found at /sdcard/Android/obb/. One time you will have found it, you will have to create a directory for your custom app based on its Android id, for example org.kiwix.kiwixcustomphet (org.kiwix.kiwixcustom + name of the app directory).

You have then to get the ZIM file onto the device custom app obb folder using the Android adb push command-line utility or more simply by using Device File Exlporer in Android Studio. The obb filename should be main.4. + app id + .obb. Here's an example:

adb push ~/Downloads/kiwix/phet_mul_2019-06.zim /sdcard/
adb shell
cd /sdcard/Android/obb/
mkdir org.kiwix.kiwixcustomphet
cd org.kiwix.kiwixcustomphet
mv /sdcard/phet_mul_2019-06.zim main.4.org.kiwix.kiwixcustomphet.obb

License

GPLv3 or later, see LICENSE for more details.