# 📲 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.