BizGaze_Remote/mobile/ANDROID_SETUP.md

# Biz Connect — Android build & push setup

Step-by-step to go from this repo to a running Android app with working FCM push.
You have **Android Studio (Quail 2026.1.1)** installed — that bundles the Android SDK and a
JDK, so no separate Java install is needed.

> The app is a Capacitor shell that loads the live Connect UI (`server.url` in
> `capacitor.config.json`, default `https://remote.bizgaze.com`). The native side only adds
> push, camera/mic, status bar, and store packaging. App id / Android package:
> **`com.bizgaze.connect`** — this must match the Firebase app you create below.

---

## 1. One-time Android Studio setup
1. Launch Android Studio once and let it finish "SDK Components Setup" (downloads the
   Android SDK + platform-tools).
2. **More Actions → SDK Manager** → install **Android SDK Platform 34** (or latest) and
   **Android SDK Build-Tools**.
3. To test on an emulator: **More Actions → Virtual Device Manager** → create a Pixel device
   (any recent API ≥ 33 so you can test the notification permission prompt). Or enable
   **USB debugging** on a physical phone and plug it in.

## 2. Generate the native Android project
```bash
cd mobile
npm install
npm run assets          # builds icons/splash from resources/ (already provided)
npx cap add android     # creates mobile/android/  (gitignored)
npx cap sync            # copies config + web assets + plugins into the project
```

## 3. App permissions
Capacitor adds `INTERNET` automatically. Add the rest to
`mobile/android/app/src/main/AndroidManifest.xml` (inside `<manifest>`, above `<application>`).
A ready-to-paste copy is in [`android-permissions.xml`](android-permissions.xml):

```xml
<!-- Push (Android 13+ runtime prompt) -->
<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
<!-- Voice / video calls + camera from the web UI -->
<uses-permission android:name="android.permission.CAMERA" />
<uses-permission android:name="android.permission.RECORD_AUDIO" />
<uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />
<uses-feature android:name="android.hardware.camera" android:required="false" />
```
> WebRTC in the WebView: Capacitor grants `getUserMedia` to the page when the app holds the
> CAMERA/RECORD_AUDIO permissions, so the existing call/screen-share UI works once these are
> present and the user accepts the runtime prompts.

## 4. Firebase / FCM (push)
1. [Firebase console](https://console.firebase.google.com) → **Add project** (or reuse one).
2. **Add app → Android**. Package name: **`com.bizgaze.connect`**. Register.
3. Download **`google-services.json`** → place it in **`mobile/android/app/`**.
4. Add the Google Services Gradle plugin (Capacitor 6 template):
   - `mobile/android/build.gradle` → `buildscript { dependencies { ... } }`:
     ```gradle
     classpath 'com.google.gms:google-services:4.4.2'
     ```
   - **bottom** of `mobile/android/app/build.gradle`:
     ```gradle
     apply plugin: 'com.google.gms.google-services'
     ```
5. `npx cap sync` again.

That's the **client** half. The **server** half (already built) needs the matching credential:
- Firebase console → **Project settings → Service accounts → Generate new private key** →
  download the JSON.
- On the production server, set **`FCM_SERVICE_ACCOUNT`** to that file's path (or its inline
  JSON) and restart. See [../DEPLOY.md](../DEPLOY.md). With that set, `push.sendToUser`
  delivers to Android devices automatically; the app already registers its token via
  `POST /api/v1/devices` on launch (see `setupNativePush` in `server/public/home.html`).

## 5. Run it
```bash
npx cap open android     # opens the project in Android Studio → press Run ▶
# or headless:
npx cap run android
```
First launch will prompt for notifications (Android 13+); accept it, then check the server log
/ DB `device_tokens` shows a row for your user.

### Testing against a LOCAL dev server (optional)
The app points at `https://remote.bizgaze.com` by default. To hit your laptop instead, edit
`capacitor.config.json`:
```json
"server": { "url": "http://<your-LAN-IP>:8090", "cleartext": true, "androidScheme": "https" }
```
then `npx cap sync`. (`cleartext` is required for plain `http`.) Revert before shipping.

## 6. Build for the Play Store
1. Create an upload keystore (once):
   ```bash
   keytool -genkey -v -keystore biz-connect.keystore -alias bizconnect -keyalg RSA -keysize 2048 -validity 10000
   ```
2. Android Studio → **Build → Generate Signed App Bundle** → AAB → select the keystore.
   (Or `cd android && ./gradlew bundleRelease`.)
3. Upload the `.aab` to **Google Play Console** (one-time $25 developer account). Fill in the
   store listing, data-safety form (declare camera/mic/notifications), and roll out to
   internal testing first.

---

## Checklist
- [ ] Android Studio SDK + an emulator/device ready
- [ ] `npm install` → `npm run assets` → `npx cap add android` → `npx cap sync`
- [ ] Permissions added to AndroidManifest
- [ ] `google-services.json` in `android/app/` + Gradle plugin lines + `cap sync`
- [ ] App runs; notification permission accepted; `device_tokens` row appears
- [ ] Server `FCM_SERVICE_ACCOUNT` set in prod → end-to-end push works
- [ ] Signed AAB built and uploaded to Play (internal testing)