docs: add PWA installation guide for Android and iOS sideloading

2026-06-19 00:34:11 +02:00
parent 1cf5426f13
commit a98a358978
1 changed files with 80 additions and 0 deletions
@@ -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.