From a98a358978bf3cab8fddf74ba017336b6114aca4 Mon Sep 17 00:00:00 2001 From: root Date: Fri, 19 Jun 2026 00:34:11 +0200 Subject: [PATCH] docs: add PWA installation guide for Android and iOS sideloading --- PWA-INSTALL.md | 80 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 80 insertions(+) create mode 100644 PWA-INSTALL.md diff --git a/PWA-INSTALL.md b/PWA-INSTALL.md new file mode 100644 index 0000000..c603be8 --- /dev/null +++ b/PWA-INSTALL.md @@ -0,0 +1,80 @@ +# 📲 Install Falah as a Mobile App (PWA) + +## What is a PWA? + +Falah is a **Progressive Web App (PWA)** — it runs in your browser but can be installed on your phone just like a native app. Once installed, it launches from your home screen, works offline for basic features, and takes full advantage of your screen without browser chrome. + +--- + +## 📱 Android + +### Option A: Install via Chrome (Recommended — 1 tap) + +1. Open **Chrome** and go to **https://falahos.my/mobile** +2. Sign in to your account +3. You'll see a banner at the bottom: **"Add Falah to Home Screen"** + - Tap **"Install"** or **"Add"** +4. If no banner appears: + - Tap the **⋮ menu** (three dots, top-right) + - Tap **"Install app"** or **"Add to Home screen"** +5. Confirm — Falah will appear on your home screen with its ☪️ icon + +**That's it.** Falah opens like any other app, with your account signed in. + +### Option B: Side-load APK (for offline distribution) + +Use **PWABuilder** to generate a real APK: + +1. Go to **https://pwabuilder.com** +2. Enter **https://falahos.my/mobile** and click **"Start"** +3. Click **"Package for Stores"** +4. Under **Android**, click **"Generate Package"** +5. Download the `.apk` or `.aab` file +6. On your Android phone, open the downloaded file and tap **"Install"** + - *If blocked: go to Settings → Security → toggle "Install from unknown apps" for your file manager* + +> **Note:** The APK wraps the PWA — all future updates are automatic. You only need to side-load once. + +--- + +## 🍎 iOS (iPhone / iPad) + +### Install via Safari (Standard way) + +1. Open **Safari** and go to **https://falahos.my/mobile** +2. Sign in to your account +3. Tap the **Share button** 📤 (the square with arrow, bottom-center of the screen) +4. Scroll down and tap **"Add to Home Screen"** ➕ +5. Edit the name (default: "Falah") and tap **"Add"** (top-right) +6. Falah now appears on your home screen with its icon + +**Opening the app:** Just tap the Falah icon on your home screen — it launches full-screen, no browser tabs. + +### Important iOS notes +- **Push notifications:** iOS doesn't support web push for home-screen apps yet. You'll see badges only when you open the app. +- **Updates:** iOS updates the PWA automatically in the background. No manual action needed. +- **Offline:** The app caches recent pages for offline reading. +- **iPad:** Same process as iPhone. The app adapts to the larger screen. + +--- + +## 🛠️ Troubleshooting + +| Issue | Fix | +|-------|-----| +| **"Add to Home Screen" doesn't appear** | Make sure you're using **Chrome** (Android) or **Safari** (iOS). Third-party browsers like Firefox or Edge may not support PWA installation. | +| **App opens but shows a white screen** | Close the app completely and reopen. This happens once after the first install. | +| **"Not secure" warning** | Ensure you're visiting **https://** (the S matters). Our site uses HTTPS automatically. | +| **Can't sign in after install** | The app shares your browser session. Sign in once in the browser, and the installed app remembers you. | +| **App feels slow on first load** | The service worker caches assets on first visit. Give it 10–20 seconds. Subsequent loads are instant. | + +--- + +## ✅ After installation + +- **Icon:** ☪️ with a crescent moon design on a dark background +- **Launch:** Full-screen, no browser address bar +- **Notifications:** Available if your device/browser supports them +- **Updates:** Automatic — you always get the latest version when you open the app + +Questions or feedback? Use the **Report Issue** button in any Falah error card, or contact the Falah team.