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

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:

<!-- 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 → 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 { ... } }:

     classpath 'com.google.gms:google-services:4.4.2'
     

   • bottom of mobile/android/app/build.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. 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

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:

"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):

   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)