Awesome
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 appzim_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 totrue
, it hides the sidebardisable_tabs
, a boolean value, when set totrue
, it deactivates the multi-tabs featuredisable_read_aloud
, a boolean value, when set totrue
, it disable the text-to-speech featuredisable_title
, a boolean value, when set totrue
, it disable the app title and set the app icon to hamburgerdisable_external_links
, a boolean value when set totrue
, 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 anAbout app_name app
item to the sidebarapp_name
will be replaced with the actual app name. Clicking it opens the URL in an external web browsersupport_url
, a URL, when it is set, it adds anSupport app_name
item to the sidebarapp_name
will be replaced with the actual app name. Clicking it opens the URL in an external web browsernew
, A boolean value, when set totrue
, 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:
- 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 chooseProject
, 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, clickNew>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
chooseImage
- For
path
click the folder icon and browse to the output ofgen-std-icon.py
- For
background layer
Source Asset > Asset Type
chooseColor
- Click on the color box
- This should present the color chooser, the box in the top right
with the label
#
should be auto selected. TypeFFFFFF
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
- iswikipedia_en_all_maxi_2018-10.zim
then it will be2018-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, 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.
Releasing in your organisation
If you want to publish the application in your organization(Play store account), kiwix requires a service account JSON file to automatically publish your app on play store.
How to create Service Account
-
You need a GCP(Google Cloud Platform) account for this.
-
Create a project for your application in the GCP.
-
Enable the AndroidPublisher API for that GCP project.
-
Create a service account and key
- Make sure you're in the GCP project you used above (check the
project
query param in the URL) - Select
New service account
- Give it a name and the Project Owner role.
- After creating the service account, find it in the list of all service accounts and use the 3
dots menu to
Manage keys
- From there, create a new key using the
Add key
menu (leave JSON selected).
- Make sure you're in the GCP project you used above (check the
-
Give your service account permissions to publish apps on your behalf.
- Click
Invite new user
- Copy/paste the service account email (you can find it in the JSON credentials)
- Don't touch the roles
- Give the
Release apps to testing tracks
permission <img alt="Minimum Service Account permissions" src="assets/min-perms.png" width="66%" />
- Click
-
We required that JSON file which was downloaded from the GCP for publishing your application.
Initial Play Store upload
The first app bundle needs to be uploaded via the Google Play Console because registering the app with the Play Store cannot be done using the Play Developer API. After the initial upload, the application will be automatically uploaded by our CD process.