kiwix/kiwix-android-custom

Necessary data/tools for the Android custom apps

Kiwix Android Custom Apps

Kiwix Android custom apps are Android apps running Kiwix for Android against a pre-configured ZIM file.

Kiwix publishes more than a dozen of such apps. [Wikimed

• Offline Medical Wikipedia](https://play.google.com/store/apps/details?id=org.kiwix.kiwixcustomwikimed) and Wikivoyage - Offline Travel Guide being the most famous ones.

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.

Disclaimer

This document is for publishers who aim to publish new custom apps. If you are a developer and want to have an in-depth understanding about the custom apps, please read CONTRIBUTING.md.

Custom app folder

In the repository, each custom configuration is isolated in a so called custom app folder. If you need to create a new one for a new custom app, you can do that easily using Github UI. Go to https://github.com/kiwix/kiwix-android-custom/new/main, put the name of your app (no space, lowercase only) and add a slash at the end.

Description json file

The configuration of the custom app is handled using the info.json file which is in the custom app folder. Take example on an already existing one if you need to create a new custom app. The most important fields are:

• app_name, the title of the app
• zim_url, the ZIM online URL (to download to create the app)
• enforced_lang, the language code of the content (and the app UI)
• disable_sidebar, a boolean value, when set to true, it hides the sidebar
• disable_tabs, a boolean value, when set to true, it deactivates the multi-tabs feature
• disable_read_aloud, a boolean value, when set to true, it disable the text-to-speech feature
• disable_title, a boolean value, when set to true, it disable the app title and set the app icon to hamburger
• disable_external_links, a boolean value when set to true, it disables the external link popup and hides the external links preference from the settings.
• about_the_app, a URL, when it is set, it adds an About app_name app item to the sidebar app_name will be replaced with the actual app name. Clicking it opens the URL in an external web browser
• support_url, a URL, when it is set, it adds an Support app_name item to the sidebar app_name will be replaced with the actual app name. Clicking it opens the URL in an external web browser
• new, A boolean value, when set to true, it triggers the creation and storage of a dummy release Bundle during the current workflow run.
• upload_bundle A boolean value. When set to true, it uploads the bundle to the Play Store, Otherwise, it uploads the APK.

You can also create this new file using Github IO. Go to https://github.com/kiwix/kiwix-android-custom/new/main and type info.json.

Remark: If you make a simple update, just replace the zim_url with the latest available zim from download.kiwix.org/zim. Then comment your commit (e.g. "updated to YYYY-MM zim") and commit directly to main branch. You won't have to change anything more than this (just tagging the release, see below).

Icon master

The Icon master is file icon.png you find (or have to create) in the custom app folder. It is a square PNG file which is used as master to create the Icon set (see section below). This master has to match many constraints and you might even have to create an icon_foreground.png and icon_baground.png to achieve to do certain things. Look at the Android documentation about adaptive icons to know more.

Icon set

The Android custom app needs an Icon set to build properly. This Icon set is needed to properly show the app icon on user devices and is a list of bitmap pictures which are derivatives of an icon master.

To create this Icon set, follow these steps:

1. Create a new empty project with Android Studio (add no activity > next > finish)
2. 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
3. Delete MyApplication/app/src/main/res
4. 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)
5. For foreground layer Source Asset > Asset Type choose Image
6. For path click the folder icon and browse to the output of gen-std-icon.py
7. For background layer Source Asset > Asset Type choose Color
8. Click on the color box
9. 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
10. [Optional] go back to foreground layer and size the icon as appropriate with the slider
11. Next > Finish will generate a res folder with all the icons needed in the location where you previously deleted the res folder.
12. 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:

1. 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.
2. 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.
3. Otherwise the current date will be put (should be avoided).

Releasing

Simply tag the repo in git with the name of a custom app, for example:

git tag -f tunisie
git push -f origin tunisie

then Go to the release tab and click on "Draft a new release". As "tag version" use the custom app folder name (e.g. wikimedar). Publish by adding for example "WikiMed FA 2021-06" as title, no description is needed.

This triggers a Github action that will build an app Bundle using kiwix-android main branch and the illustrations/icons set/json defined in this repository.

The very first release has to be done manually. Put the new attribute so the release management action provides you the dummy first bundle to upload.

All other further releases (without the new attribute in the json.info) are then uploaded automatically to the Google Play app store as draft. Therefore, once released, go then to the Google Play Store Admin dashboard for the corresponding app and go to menu "Publication management" > "App version": under "Internal Testing", you can click on "Modify version". After a couple of hours the new version of the app should be listed in the public Play Store.

License

GPLv3 or later, see LICENSE for more details.

kiwix-android-custom's Issues

Share and update custom APK without having to go through Google play

It would be nice to be able to generate a custom app (like we currently do here) but without going through the Playstore.

At the end of the process we would have a working apk that can be shared directly with users.

Which format works best for layout design files?

We've concluded the design contest for the Wiktionary app, and the designer asks if is it okay if she sends the XD file of these screens instead of PSD or Sketch.

@macgills Is there any significant difference for us between these file formats?

Complete Wikivoyage in German Play store description

Create Cricket app

There's the Cricket world cup coming up June 1st. Let's try and release Custom apps in English and Hindi.
Name: Cricketpedia
Image: https://commons.wikimedia.org/wiki/File:Cricketball.svg

What else do we need, except for a description text?

Update CONTRIBUTING.md with steps to make release without ZIM change

This seems to me really necessary to avoid relying on tech people for that special operation

Impossible to build custom apps with Kiwix Android 2.4

The CI fails to go through because the install version of NDK is not the right one (the same as in kiwix/kiwix-android). See https://github.com/kiwix/kiwix-android-custom/runs/2296262609?check_suite_focus=true

Execution failed for task ':custom:stripWikispeciesReleaseDebugSymbols'.
> No version of NDK matched the requested version 22.0.7026061. Versions available locally: 21.4.7075529, 21.4.7075529, 21.4.7075529

I believe the problem is that we should in kiwix-android-custom request to install the same NDK as for kiwix/kiwix-android... for the moment it just have the default version

Wikispecies ZIM file is too big

It should be split in 2 pieces with zim-split.

Generate Wikimed zim excluding biographies and companies

Some sort of RegExp that would exclude pages also belonging to projects Companies and/or Biography (and its subprojects) should help us get rid of a couple thousand unneeded articles.

WikiMed app- Credits#Contributors color on night mode

Hello,

On Android WikiMed app (I tired EN. & AR.), the blue color of (Contributors) links on Credits section on night mode appear painful for eyes and can't be read easily.

I notice that personally and from another friends (3) who using the app.

Thanks.

Release Ukrainian Wikimed app

Playstore entry has been created (https://play.google.com/console/u/0/developers/9116215767541857492/app/4972558197069908415/releases/overview) and the zim file needed is at https://download.kiwix.org/zim/wikipedia/wikipedia_uk_medicine_maxi_2023-02.zim

Create Kiwix-kids app with offline stuffs for kids.

• Let the app:

• Filter adult contents

• contain fun activities & exercises from Popular kids website

• Contain free resources for kids from Wikipedia just like Kiwix.
  & lots of other interesting stuffs!

Source image for app icon should be saved somewhere

We need that to easily/automatically recompute new adaptive icons which might need a new version of the master app icon.

New Wikimed mini has wrong logo

On my phone's screen it shows the Kiwi(x) logo rather than the light caducea (https://commons.wikimedia.org/wiki/File:Wikimed_mini_template.svg)

Publish custom apps “Wikivoyage” and “Chemistry & Physics simulations” in F-Droid

@4tip commented on Sep 23, 2019, 8:17 PM UTC:

A app called Kiwix, created by “Kiwix Team” is available in F-Droid and I wonder if someone could get two other apps by “Kiwix Team” to the F-Droid repo?? Or release the source code, that F-Droid workers can use to include the apps in F-Droid?
The names of the apps are “Wikivoyage” and “Chemistry & Physics simulations”.

App-Link: https://play.google.com/store/apps/details?id=org.kiwix.kiwixcustomwikivoyage 2

App-Link:https://play.google.com/store/apps/details?id=org.kiwix.kiwixcustomphet

This issue was moved by kelson42 from kiwix/overview#21.

Wikivoyage: Tapping on map marker number unhandled

App version: Wikivoyage 2018-12
Android version: 9, no Google Play Services

The markers are also always numbered 1.
See error at bottom of image

Generate Wiktionary Playstore entry

Should include a short description of the app and the usual shizzle.

Is it OK to submit the Wikivoyage app to F-Droid?

Many Android users don't have access to Google Play, for instance in China or LineageOS users.
Making the app available on F-Droid would allow these people to use the app.
The Wikivoyage community is also asking for this.

We could just take the source code and build/publish it, but F-Droid has a principle of asking app developers before doing it, so you just need to write "OK" here :-)

Thanks!

Custom app should be able to download zim from external URL

Here is the scenario:

• We want to produce an app with an extremely large zim file (e.g. more than 2 Gb), so much so that going through the playstore is not a viable option;
• User would therefore download a "shell app" (ie Kiwix-custom") which would in turn download and install the target zim file after it's been installed;
• (maybe a separate ticket?): the app would check when there's a new zim available and flag it to the user one way or the other (for instance with an "update content" button in the settings that would be greyed out when no such new content is available; I'd be wary of automated updates as users often are in atypical connectivity configurations).

@macgills 1. Would that be possible? and 2. How many days of dev work do you reckon it would take to implement the "separate download" approach?

How can I build an android custom app for offline deployment

Users who have no internet connection can not get to the Google playstore, so Internet in a Box provides kiwix apks with embedded zims that can be loaded to an android phone directly from the server. In previous versions of the custom app builder the json file could be passed as an argument and this json file could have embed_zim: true. It could also have other parameters set to custom values. It looks like this is no longer supported.

The two wiki pages for this repo describe building apks for the Google playstore either with Travis or without using the json files in https://github.com/kiwix/kiwix-android-custom, all of which have embed_zim false.

What are the parameters to pass to build_custom_app.py to get an embedded zim, either built locally or built on Travis for upload to a public site or for download and not to upload to Google? Or is there an alternate method of obtaining an apk with embedded zim?

Replace icon/favicon.png in mini Wikimed

Finish generation Bollywood App

The play store entry for Bollywood offline App has been uploaded.
Please create the app itself (package Kiwix+zim file).
https://play.google.com/console/u/1/developers/9116215767541857492/app/4974884347233129305/main-store-listing

#14

Positive search result in Wikimed fails to send user to corresponding article.

From OTRS:
I'm using the wikimed app.
Version : 2017-08
Buid : 1172141

Whenever I type gongylonema pulchrum , I get the search results but when I tap on it.. nothing happens... It doesn't direct me to the content.

Update Wikivoyage apps

Last update is from December 2016...

Update arabic Wikimed app

Last zim is from January and the content on the app is probably older. We have many pings on that on the Arabic FB page. Thank you.

New landing page for German Wikivoyage app

https://de.wikivoyage.org/wiki/Benutzer:Stephane_(Kiwix)/Hauptseite

add readme

At this moment it is completely unclear what is in this repo. I got referred here with claim that it is source of https://play.google.com/store/apps/details?id=org.kiwix.kiwixcustomwikivoyage app

Also, such source code is not really useful without instruction how it can be used

Improve Google Play update script to allow updates without content change

From @mhutti1 on December 30, 2016 18:9

upload-apk.py should be updated to allow for uploading APKs with an existing expansion. For now this operation can only be achieved using the Google Play Admin Web UI.

Copied from original issue: kiwix/kiwix-xulrunner#407

Create new Maths custom app

Landing page can be found at https://en.wikipedia.org/wiki/Wikipedia:WikiProject_Mathematics/Offline

The corresponding zim should collate all articles related to WikiProject Mathematics but NOT those also in Wikiproject Biographies.

The icon file is

Last but not least the app should be less than 100 Mb.

Update Wikimed AR app logo

https://play.google.com/store/apps/details?id=org.kiwix.kiwixcustomwikimedar

Current logo include sentence (medical encyclopedia) without offline symbol
https://commons.wikimedia.org/wiki/File:Wikimed_Arabic_Logo.svg

New logo include sentence (Medical Wikipedia) + offline symbol
https://commons.wikimedia.org/wiki/File:Wikimed_Arabic_Logo_2.svg

Note: I updated the interface page of the app to appear on next release
https://w.wiki/Grh

Finish Generating Wiktionary Offline App (English)

Could you please help in finishing generating Wiktionary Offline App?
The play store entry has been uploaded.
Please create the app itself (package Kiwix+zim file).
https://play.google.com/console/u/1/developers/9116215767541857492/app/4972878495171866290/main-store-listing
The Zim file is:
https://download.kiwix.org/zim/wiktionary/wiktionary_en_all_maxi_2023-02.zim

#49

Space beneath every image

App version: Wikivoyage 2018-12
Android version: 9, no Google Play Services

Error message on reinstalling the medical app

The medical app was not working so I removed it and tried to reinstall it. The reinstall says "corrupted" and it will not open.

Update tagging release methodology

Currently we push a tag of a name eg phet to trigger a release of a custom app against master of kiwix-android

This leads to some confusion about what version of the app is published for a custom app.

We should update our workflow and tagging procedure so that we push the tag phet:3.3.4 on this repo to do a release of phet with 3.3.4 of kiwix-android

Generate Bollywood app

From @Popolechien on January 12, 2017 16:8

A Bollywood app would include articles listed in both Wikiproject Film and WikiProject India (see, e.g. https://en.wikipedia.org/wiki/Talk:List_of_Bollywood_films_of_2016).

Copied from original issue: openzim/mwoffliner#38

Update Phet Play store images

The Phet play store images are outdated. A few other apps might be as well. Maybe look into doing this automatically on release.

Generate Wikimed Mini app without images

Ultimately the goal is to save space, and quick survey showed that 9/10 images in the infoboxes are illustrative rather than informative.

Update Arabic Wikimed landing page

The new, updated landing page for Arabic Wikimed can be found here:

https://ar.wikipedia.org/wiki/%D9%88%D9%8A%D9%83%D9%8A%D8%A8%D9%8A%D8%AF%D9%8A%D8%A7:%D9%85%D8%B4%D8%B1%D9%88%D8%B9_%D9%88%D9%8A%D9%83%D9%8A_%D8%B7%D8%A8/%D9%85%D8%B1%D8%AC%D8%B9_%D8%A8%D8%AF%D8%A7%D9%8A%D8%A9_%D8%A7%D9%84%D8%AA%D8%B7%D8%A8%D9%8A%D9%82_%D8%A7%D9%84%D8%B7%D8%A8%D9%8A2

Remove images from WikiVoyage apps

As discussed in recent Foundation research, file size is paramount to user acceptance: images currently bring little value as they are not maps, and removing them could help gain a few hundred megabytes on the app's size.

Finish to update configuration file to new build system.

New build system using kiwix-build need the zim_url attribute.
There is no more need to version or content_version as it is automatically set by build system.

Update Arabic Wikimed app

Hello,

Last zim is from September 2018 and the content on the app is probably older. We have many pings on that on Arabic Wikipedia WikiProject Medicine and on Arabic Wikipedia official Facebook page. Thank you.

errors in zim url in json

some have a generic name, like "zim_url": "https://download.kiwix.org/zim/wikipedia_fr_medicine.zim", and others have a specific version,

like "zim_url": "http://download.kiwix.org/zim/wikipedia/wikipedia_en_medicine_nodet_2017-08.zim",

and at least one (ar) is the wiki, not the med wiki

"zim_url": "https://download.kiwix.org/zim/wikipedia_ar_all.zim",

Wikimed mini opens on empty/blank screen

The issue remains when I close/ reopen the app. Clicking on Home does not take me anywhere. Closing the currently open article brings me back to a blank screen as well.
Version 2018-08 build 1182421. Other than that the app works fine as far as I can tell.

Fix gen-std-icon to produce asset compatible with Andoid Asset Studio

From a plain logo an icon should be produced with transparent background and flag/offline icons centered at the bottom

Typo in this project's description

I don't have permission to edit the description otherwise I'd edit it directly. It currently says tols and should probably say tools.

Necessary data/tols for the Android custom apps

Remove "caption" string from Minimed infobox

(maybe this should go to mwoffliner/issues - let me know)
Wikimed mini removes images but keeps captions, which is kind of weird (see image).

The infobox string is
| image =
|caption = xyz
|nextfield = blablabla

I'd surmise a simple regexp would do the trick?

Update WikiVoyage apps

Both Wikivoyage apps (the regular one and the Europe one) were last updated in January 2020 and seem to describe Ukraine as a pleasant and funky destination o_0

Wikivoyage: Extraneous Wikipedia and Wikidata icons in listings

App version: Wikivoyage 2018-12
Android version: 9, no Google Play Services

These could either have the link or be hidden. As-is, they interrupt the flow of the text and mislead.

Target Android 11 before November 2021

More info at kiwix/kiwix-android#2516

All custom apps should have nice screenshots

At least as good as the one from wikimed (made with appure.io).

Fixes for build-custom-app

@kelson42 commented on Jun 26, 2017, 6:51 PM UTC:

• Explain how to install ruby
• Explain how to install travis (the travis doc is big)
• Talk about "hash -r"
• Put a word about "kiwix-android-custom" that people know where to modify things
• zim_url and zim_content should be merged (in zim?)
• remove version_code fron info.json
• add httpslib2 in the deps
• add google-api-python-client in the deps
• add space before "if you found it"

This issue was moved by kelson42 from kiwix/kiwix-android#1218.