# Android and iOS app

The same code as the website, packaged as an app with Capacitor. Release steps: [RELEASE.md](RELEASE.md).

## Requirements

| | version | where |
|---|---|---|
| Node | 22 | `nvm use 22` |
| JDK | 21 | `JAVA_HOME` |
| Android SDK | platform 36, build-tools 35.0.0 | Android Studio → SDK Manager (once, with a VPN: dl.google.com is blocked in Iran) |
| Gradle | 8.14.3 | downloaded by `gradlew` on the first build — do not install it yourself |
| Android Gradle Plugin | 8.13.0 | pinned in `android/build.gradle`; nothing to install |
| platform-tools | any recent | `adb`, needed by `cap run`, live reload and `chrome://inspect` |
| npm packages | from `package-lock.json` | `npm ci` once in the project folder |
| signing key | `android/keystore.properties` | [Signing](#signing): release builds stop without it, debug builds do not need it |

Add `--mirrors` to Android builds so Gradle downloads through maven.myket.ir.

Gradle only sees two environment variables — check them before the first build:

```bash
node -v                          # v22.x
"$JAVA_HOME/bin/java" -version   # 21.x
echo "$ANDROID_HOME"            # the folder holding platforms/ and build-tools/
```

Android Studio installs all of this in one place: its bundled JDK is 21
(`File > Settings > Gradle > Gradle JDK`), and SDK Manager installs
`platforms;android-36`, `build-tools;35.0.0` and `platform-tools`. On Windows run
the `npm` commands from Git Bash or PowerShell; the `scripts/*.sh` checks in
[RELEASE.md](RELEASE.md) need Git Bash.

## Supported phones

Android 7.0 (API 24) and newer, with WebView (Chrome) 71 or newer. Older WebViews get an "update WebView" page. Built for Android 16 (API 36).

## Build options

| command | does |
|---|---|
| `npm run build:android -- --mirrors` | release APKs for every store → `build/native/artifacts/` |
| `… --channel bazaar` | one store only (`bazaar`, `myket`, `direct`) |
| `… --build-number 1` | same version, higher build number |
| `… --skip-web` | reuse the last web bundle (only Android code changed) |
| `… --aab` | App Bundles instead of APKs |
| `npm run build:android:debug` | debug APK, inspectable at `chrome://inspect` |
| `npm run android:open` | open the project in Android Studio |

Live reload on a phone on the same network:

```bash
npm run dev:native
npx cap run android --live-reload --host <this PC's IP> --port 3001
```

## Stores

| store | flavor | update button opens |
|---|---|---|
| Cafe Bazaar | `bazaar` | the Bazaar app |
| Myket | `myket` | the Myket app |
| website | `direct` | `app.rangook.ir/download/rangook-android.apk` |

All three have the same code, version and signing key. The package name `ir.rangook.app` can never change after the first upload.

## Signing

One key for every store, kept outside the repo in `E:\PishiStudio\rangook\signing\`; back it up. The build reads `android/keystore.properties` (gitignored):

```
storeFile=E:/PishiStudio/rangook/signing/rangook-upload.jks
storePassword=...
keyAlias=rangook
keyPassword=...
```

On a build server, set `RANGOOK_KEYSTORE_FILE`, `RANGOOK_KEYSTORE_PASSWORD`, `RANGOOK_KEY_ALIAS` and `RANGOOK_KEY_PASSWORD` instead.

## Keep as is

- `androidScheme: "https"` in `capacitor.config.ts`: IranHLS videos only play on `https:` pages.
- The WebView minimum (71) lives in three places that must match: `browserslist` in `package.json`, `.babelrc`, and `minWebViewVersion` in `capacitor.config.ts`.
- API CORS: if it is ever restricted, allow `https://localhost` (Android) and `capacitor://localhost` (iOS).
- After paying, the backend shows the result (`/api/v1/payment/verify` for the website, `/verify/app` for the app). Its button leads back to the website or to `rangook://payment/result`.

## Device features

Steps, health and the like: declare the feature in `src/lib/platform/capabilities/registry.ts` and wrap its screen in `<CapabilityGate>` (example at the top of `src/components/platform/capability-gate.tsx`).

## iOS (once, on a Mac)

Needs a Mac with Xcode 26+ and Node 22 (Capacitor 8's floors: Xcode 26, iOS 15
as the deployment target). Confirm the current numbers in Capacitor's
environment-setup page before the first build.

1. `npm i @capacitor/ios && npx cap add ios`, then `npm run build:ios`.
2. URL scheme `rangook` in `Info.plist`.
3. Page routing like `StaticExportWebViewClient.java`: `/route/` → `route/index.html`, else `/404/index.html`.
4. Port `RangookAppPlugin` to Swift: `getBuildInfo`, `openExternal`, `openAppSettings`.
5. Safe areas: `viewport-fit=cover` and `env(safe-area-inset-*)` padding, in the app build only.
6. A store that accepts Iranian developers (e.g. Sibche, Sibapp): add it as a channel in `src/lib/platform/channels.ts` and `scripts/app-update.js`.

## Icons

Replace the files in `assets/`, then run `npm run app-icons` ([assets/README.md](assets/README.md)).

## Troubleshooting

| problem | check |
|---|---|
| no update prompt | `app-update.json` uploaded? `latestBuild` above the installed build for that store? "Later" hides it for 24 h |
| `Node … is too old` | `nvm use 22` |
| Gradle can't reach dl.google.com | add `--mirrors` |
| a reload shows the wrong page | `MainActivity` installs the routing client |
| debugging | debug APK, then `chrome://inspect` in desktop Chrome with the phone on USB |
