Skip to content

Commit 7fad443

Browse files
MartinBraquetMartinBraquet
committed
Add android readme
1 parent 92a9720 commit 7fad443

File tree

1 file changed

+349
-0
lines changed

1 file changed

+349
-0
lines changed

‎android/README.md‎

Lines changed: 349 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,349 @@
1+
# Compass Android WebView App
2+
3+
This folder contains the source code for the Android application of Compass.
4+
A hybrid mobile app built with **Next.js (TypeScript)** frontend, **Firebase backend**, and wrapped as a **Capacitor WebView** for Android.
5+
Right now it's just a webview wrapper around the web application, but in the future it may
6+
contain native code as well.
7+
8+
This document describes how to:
9+
1. Build and run the web frontend and backend locally
10+
2. Sync and build the Android WebView wrapper
11+
3. Debug, sign, and publish the APK
12+
4. Enable Google Sign-In and push notifications
13+
14+
---
15+
16+
## 1. Project Overview
17+
18+
The app is a Capacitor Android project that loads the deployed Next.js site (`https://compassmeet.com`) inside a WebView.
19+
20+
During development, it can instead load the local frontend (`http://10.0.2.2:3000`) and backend (`http://10.0.2.2:8088`).
21+
22+
Firebase handles authentication and push notifications.
23+
Google Sign-In is supported natively in the WebView via the Capacitor Social Login plugin.
24+
25+
Project Structure
26+
27+
- `app/src/main/java/com/compass/app`: Contains the Java/Kotlin source code for the Android application.
28+
- `app/src/main/res`: Contains the resources for the application, such as layouts, strings, and images.
29+
- `app/build.gradle`: The Gradle build file for the Android application module.
30+
- `build.gradle`: The top-level Gradle build file for the project.
31+
- `AndroidManifest.xml`: The manifest file that describes essential information about the application.
32+
33+
---
34+
35+
## 2. Prerequisites
36+
37+
### Required Software
38+
| Tool | Version | Purpose |
39+
| -------------- | ------- | ---------------------------------- |
40+
| Node.js | 22+ | For building frontend/backend |
41+
| yarn | latest | Package manager |
42+
| Java | 21 | Required for Android Gradle plugin |
43+
| Android Studio | latest | For building and signing APKs |
44+
| Capacitor CLI | latest | Android bridge |
45+
| OpenJDK | 21 | JDK for Gradle |
46+
47+
### Environment Setup
48+
```bash
49+
sudo apt install openjdk-21-jdk
50+
sudo update-alternatives --config java
51+
# Select Java 21
52+
53+
export JAVA_HOME=/usr/lib/jvm/java-21-openjdk-amd64
54+
java -version
55+
javac -version
56+
````
57+
58+
---
59+
60+
## 3. Build and Run the Web App
61+
62+
```
63+
yarn install
64+
yarn build-web
65+
```
66+
67+
### Local mode
68+
69+
If you want the webview to load from your local web version of Compass, run the web app.
70+
71+
In root directory:
72+
```bash
73+
export NEXT_PUBLIC_LOCAL_ANDROID=1
74+
yarn dev # or prod
75+
```
76+
77+
* Runs Next.js frontend at `http://localhost:3000`
78+
* Runs backend at `http://10.0.2.2:8088`
79+
80+
### Deployed mode
81+
82+
If you want the webview to load from the deployed web version of Compass (like at www.compassmeet.com), no web app to run.
83+
84+
---
85+
86+
## 5. Android WebView App Setup
87+
88+
### Install dependencies
89+
90+
```
91+
cd android
92+
./gradlew clean
93+
```
94+
95+
Sync web files and native plugins with Android, for offline fallback. In root:
96+
```
97+
export NEXT_PUBLIC_LOCAL_ANDROID=1 # if running your local web Compass
98+
yarn build-web # if you made changes to web app
99+
npx cap sync android
100+
```
101+
102+
### Load from site
103+
104+
During local development, open Android Studio project and run the app on an emulator or your physical device.
105+
106+
```
107+
npx cap open android
108+
```
109+
110+
Building the Application:
111+
1. Open Android Studio.
112+
2. Click on "Open an existing Android Studio project".
113+
3. Navigate to the `android` folder in this repository and select it.
114+
4. Wait for Android Studio to index the project and download any necessary dependencies.
115+
5. Connect your Android device via USB or set up an Android emulator.
116+
6. Click on the "Run" button (green play button) in Android Studio to build and run the application.
117+
7. Select your device or emulator and click "OK".
118+
8. The application should now build and launch on your device or emulator.
119+
120+
---
121+
122+
## 6. Building the APK
123+
124+
### From Android Studio
125+
126+
- If you want to generate a signed APK for release, go to "Build" > "Generate Signed Bundle / APK..." and follow the prompts.
127+
- Make sure to test the application thoroughly on different devices and Android versions to ensure compatibility.
128+
129+
### Debug build
130+
131+
```bash
132+
cd android
133+
./gradlew assembleDebug
134+
```
135+
136+
Outputs:
137+
138+
```
139+
android/app/build/outputs/apk/debug/app-debug.apk
140+
```
141+
142+
### Install on emulator
143+
144+
```bash
145+
adb install -r app/build/outputs/apk/debug/app-debug.apk
146+
```
147+
148+
### Release build (signed)
149+
150+
1. Generate a release keystore:
151+
152+
```bash
153+
keytool -genkey -v -keystore release-key.keystore -alias compass \
154+
-keyalg RSA -keysize 2048 -validity 10000
155+
```
156+
2. Add signing config to `android/app/build.gradle`
157+
3. Build:
158+
159+
```bash
160+
./gradlew assembleRelease
161+
```
162+
163+
---
164+
## 9. Debugging
165+
166+
Client logs from the emulator on Chrome can be accessed at:
167+
```
168+
chrome://inspect/#devices
169+
```
170+
171+
Backend logs can be accessed from the output of `yarn prod / dev` like in the web application.
172+
173+
Java/Kotlin logs can be accessed via Android Studio's Logcat.
174+
```
175+
adb logcat | grep com.compass.app
176+
adb logcat | grep Capacitor
177+
adb logcat | grep console
178+
```
179+
180+
You can also add this inside `MainActivity.java`:
181+
182+
```java
183+
webView.setWebChromeClient(new WebChromeClient() {
184+
@Override
185+
public boolean onConsoleMessage(ConsoleMessage consoleMessage) {
186+
Log.d("WebView", consoleMessage.message());
187+
return true;
188+
}
189+
});
190+
```
191+
192+
---
193+
194+
## 10. Deploy to Play Store
195+
196+
1. Sign the release APK or AAB.
197+
2. Verify package name matches Firebase settings (`com.compass.app`).
198+
3. Upload to Google Play Console.
199+
4. Add Privacy Policy and content rating.
200+
5. Submit for review.
201+
202+
---
203+
204+
## 11. Common Issues
205+
206+
| Problem | Cause | Fix |
207+
| -------------------------------------- | -------------------------------------- | ------------------------------------------------------------------- |
208+
| `INSTALL_FAILED_UPDATE_INCOMPATIBLE` | Old APK signed with different key | Uninstall old app first |
209+
| `Account reauth failed [16]` | Missing or incorrect SHA-1 in Firebase | Re-add SHA-1 of keystore |
210+
| App opens in Firefox | Missing `WebViewClient` override | Fix `shouldOverrideUrlLoading` |
211+
| APK > 1 GB | Cached webpack artifacts included | Add `.next/` and `/public/cache` to `.gitignore` and build excludes |
212+
213+
---
214+
215+
## 13. Local Development Workflow
216+
217+
```bash
218+
# Terminal 1
219+
export NEXT_PUBLIC_LOCAL_ANDROID=1
220+
yarn dev # or prod
221+
222+
# Terminal 2: start frontend
223+
export NEXT_PUBLIC_LOCAL_ANDROID=1
224+
yarn build-web # if you made changes to web app
225+
npx cap sync android
226+
# Run on emulator or device
227+
```
228+
229+
---
230+
231+
## 14. Deployment Workflow
232+
233+
```bash
234+
# 1. Build web app for production
235+
yarn build-web
236+
237+
# 2. Sync assets to Android
238+
npx cap sync android
239+
240+
# 3. Build signed release APK in Android Studio
241+
```
242+
243+
---
244+
245+
## 15. Resources
246+
247+
* [Capacitor Docs](https://capacitorjs.com/docs)
248+
* [Firebase Android Setup](https://firebase.google.com/docs/android/setup)
249+
* [FCM HTTP API](https://firebase.google.com/docs/cloud-messaging/send-message)
250+
* [Next.js Deployment](https://nextjs.org/docs/deployment)
251+
252+
253+
# Useful Commands
254+
255+
- To build the project: `./gradlew assembleDebug`
256+
- To run unit tests: `./gradlew test`
257+
- To run instrumentation tests: `./gradlew connectedAndroidTest`
258+
- To clean the project: `./gradlew clean`
259+
- To install dependencies: Open Android Studio and it will handle dependencies automatically.
260+
- To update dependencies: Modify the `build.gradle` files and sync the project in Android Studio.
261+
- To generate a signed APK: Use the "Generate Signed Bundle / APK..." option in Android Studio.
262+
- To lint the project: `./gradlew lint`
263+
- To check for updates to the Android Gradle Plugin: `./gradlew dependencyUpdates`
264+
- To run the application on a connected device or emulator: `./gradlew installDebug`
265+
- To view the project structure: Use the "Project" view in Android Studio.
266+
- To analyze the APK: `./gradlew analyzeRelease`
267+
- To run ProGuard/R8: `./gradlew minifyRelease`
268+
- To generate documentation: `./gradlew javadoc`
269+
270+
# One time setups
271+
272+
Was already done for Compass, so you only need to do the steps below if you create a project separated from Compass.
273+
## Configure Firebase
274+
275+
### In Firebase Console
276+
277+
1. Add a **Web app** → obtain `firebaseConfig`
278+
2. Add an **Android app**
279+
280+
* Package name: `com.compass.app`
281+
* Add your SHA-1 and SHA-256 fingerprints (see below)
282+
* Download `google-services.json` and put it in:
283+
284+
```
285+
android/app/google-services.json
286+
```
287+
288+
### To get SHA-1 for debug keystore
289+
290+
```bash
291+
keytool -list -v \
292+
-keystore ~/.android/debug.keystore \
293+
-alias androiddebugkey \
294+
-storepass android \
295+
-keypass android
296+
```
297+
298+
Add both SHA-1 and SHA-256 to Firebase.
299+
300+
301+
## 7. Google Sign-In (Web + Native)
302+
303+
In Firebase Console:
304+
305+
* Enable **Google** provider under *Authentication → Sign-in method*
306+
* Add your **Android SHA-1**
307+
* Add your **Web OAuth client ID**
308+
309+
In your code:
310+
311+
```ts
312+
import { googleNativeLogin } from 'web/lib/service/android-push'
313+
```
314+
315+
316+
## 8. Push Notifications (FCM)
317+
318+
### Setup FCM
319+
320+
* Add Firebase Cloud Messaging to your project
321+
* Include `google-services.json` under `android/app/`
322+
* Add in `android/build.gradle`:
323+
324+
```gradle
325+
classpath 'com.google.gms:google-services:4.3.15'
326+
```
327+
* Add at the bottom of `android/app/build.gradle`:
328+
329+
```gradle
330+
apply plugin: 'com.google.gms.google-services'
331+
```
332+
333+
### Test notification
334+
335+
```ts
336+
const message = {
337+
notification: {
338+
title: "Test Notification",
339+
body: "Hello from Firebase Admin SDK"
340+
},
341+
token: "..."
342+
};
343+
initAdmin()
344+
await admin.messaging().send(message)
345+
.then(response => console.log("Successfully sent message:", response))
346+
.catch(error => console.error("Error sending message:", error));
347+
```
348+
349+
---

0 commit comments

Comments
 (0)