Android App Creation Guide

⚠️⚠️⚠️ This is an initial draft. ⚠️⚠️⚠️

Requirements

We need following information for Android App builder:

• a fully functioning APK:
  • proper package name and version
    • both are inspectable with aapt2 tool, download instruction: https://developer.android.com/tools/aapt2#download_aapt2
      • aapt2 dump badging myapp.apk
  • preferably good icon and application label
  • it is advised to test app from https://app-live.browserstack.com (allows to check it is properly functioning and check icon and application label)
• title (30 chars max)
• description (80 chars max)
• square icon (at least 48x48 ; at least a bit bigger is good, but beware the icon must be readable / recognizable at this low res)

We also need presentation information:

• ideally, an HTML presentation page to be used on the hotspot (self-contained, with all its resources)
• or at least a presentation text, unlimited length and paragraphs (usually it is hard for the customer to provide, in which case we will reuse a "default" layout)

Sample package containing the presentation page and APK: https://drive.offspot.it/f-droid/org.ligi.survivalmanual_428.zip

Note that if you want to support multiple language, we will have to create one package per language so that the app is properly listed in all languages in the imager service and the hotspot. Consequence is that we need the title, description and presentation in all languages obviously.

Configuration

If not already provided, build the package with presentation page and APK (see https://drive.offspot.it/f-droid/org.ligi.survivalmanual_428.zip as an example).

Beware that the structure must be without wrapping folder (i.e. with index.html at the root), and without hidden files. The ZIP file should not be compressed.

Typical command to use (from inside the folder where the files are present):

zip -0 -r ../af_and_rica_ar.zip ./* -x '**/.*' -x '**/__MACOSX'

You can check zip content with unzip -l af_and_rica_ar.zip

Archive:  af_and_rica_ar.zip
  Length      Date    Time    Name
---------  ---------- -----   ----
        0  12-06-2024 08:26   assets/
    16367  12-06-2024 08:22   assets/icon.png
    27558  01-10-2024 12:37   assets/main.css
    32652  01-10-2024 12:34   assets/roboto.ttf
        0  12-16-2024 14:27   download/
 46429593  12-16-2024 14:05   download/com.AfRica.DCX_1.0.0.apk
     1714  12-16-2024 14:33   index.html
---------                     -------
 46507884                     7 files

Then upload both the illustration and the ZIP package to drive.offspot.it

Finally, configure the package in the catalog: make a PR to modify https://github.com/offspot/offspot-config/blob/main/src/offspot_config/catalog.json (do not forget to update the CHANGELOG as well).

Sample good configuration:

    {
        "ident": "org.ligi.survivalmanual.offspot.kiwix.org",
        "domain": "org.ligi.survivalmanual",
        "kind": "files",
        "title": "Survival Manual",
        "description": "Downloadable Android APK. Learn how to survive",
        "languages": [
            "eng"
        ],
        "tags": [
            "android"
        ],
        "icon_url": "https://drive.offspot.it/f-droid/org.ligi.survivalmanual.png",
        "download_url": "https://drive.offspot.it/f-droid/org.ligi.survivalmanual_428.zip",
        "download_size": 5528415,
        "download_checksum": {
            "algo": "md5",
            "value": "620510a857da1655b931081c2f85e33a"
        },
        "via": "zip"
    }