172 lines
4.0 KiB
Markdown
172 lines
4.0 KiB
Markdown
# Dewemoji APK Companion Runbook
|
|
|
|
This is the single guide for APK build, release, direct distribution, and versioning.
|
|
|
|
## 1) Scope
|
|
|
|
The Android companion uses:
|
|
|
|
- local bundled UI (`dewemoji-capacitor/src` -> `dewemoji-capacitor/www`)
|
|
- native floating bubble launcher (copy/search workflow)
|
|
- direct APK update via hosted `version.json`
|
|
|
|
The bubble is not an IME and does not perform direct cross-app insertion.
|
|
|
|
## 2) Prerequisites
|
|
|
|
1. Node.js `20+`
|
|
2. JDK `17`
|
|
3. Android SDK / Android Studio
|
|
4. `adb`
|
|
5. optional signing toolchain (`apksigner`)
|
|
|
|
Install deps once:
|
|
|
|
```bash
|
|
cd /Users/dwindown/Developments/dewemoji
|
|
npm --prefix dewemoji-capacitor install
|
|
```
|
|
|
|
## 3) Source and build model
|
|
|
|
Do not edit `dewemoji-capacitor/www/*` directly.
|
|
|
|
- edit source in `dewemoji-capacitor/src/*`
|
|
- generate runtime assets via:
|
|
|
|
```bash
|
|
npm --prefix dewemoji-capacitor run build
|
|
```
|
|
|
|
## 4) Debug build and device install
|
|
|
|
```bash
|
|
cd /Users/dwindown/Developments/dewemoji
|
|
npm --prefix dewemoji-capacitor run build
|
|
cd dewemoji-capacitor
|
|
npx cap sync android
|
|
cd android
|
|
./gradlew assembleDebug
|
|
adb install -r app/build/outputs/apk/debug/app-debug.apk
|
|
```
|
|
|
|
## 5) Release build
|
|
|
|
From repo root:
|
|
|
|
```bash
|
|
./scripts/apk/build-release.sh
|
|
```
|
|
|
|
Script behavior:
|
|
|
|
1. read `versionCode` and `versionName` from `android/app/build.gradle`
|
|
2. rebuild web assets
|
|
3. run `cap sync android`
|
|
4. build release APK
|
|
5. sign if signing env vars are present
|
|
6. output artifact under `dewemoji-capacitor/dist/apk/`
|
|
|
|
Output naming:
|
|
|
|
- `dewemoji-v{versionName}-{versionCode}.apk`
|
|
|
|
## 6) Signing env (optional but recommended)
|
|
|
|
```bash
|
|
export ANDROID_KEYSTORE_PATH="/absolute/path/release.jks"
|
|
export ANDROID_KEYSTORE_PASSWORD="..."
|
|
export ANDROID_KEY_ALIAS="..."
|
|
export ANDROID_KEY_PASSWORD="..."
|
|
```
|
|
|
|
## 7) Direct release to Cloudflare R2
|
|
|
|
Required env:
|
|
|
|
```bash
|
|
export R2_ACCOUNT_ID="..."
|
|
export R2_ACCESS_KEY_ID="..."
|
|
export R2_SECRET_ACCESS_KEY="..."
|
|
export R2_BUCKET="dewemoji-downloads"
|
|
export R2_PUBLIC_BASE_URL="https://downloads.dewemoji.com"
|
|
```
|
|
|
|
Canonical update URLs used by app updater:
|
|
|
|
- `https://dewemoji.com/downloads/version.json`
|
|
- `https://dewemoji.com/downloads/dewemoji-latest.apk`
|
|
|
|
Publish:
|
|
|
|
```bash
|
|
./scripts/apk/publish-r2.sh \
|
|
--apk dewemoji-capacitor/dist/apk/dewemoji-v1.1.2-112.apk \
|
|
--version-name 1.1.2 \
|
|
--version-code 112 \
|
|
--min-supported-version-code 100 \
|
|
--notes "Bug fixes and update UX improvements" \
|
|
--force false
|
|
```
|
|
|
|
Verify:
|
|
|
|
```bash
|
|
./scripts/apk/verify-release.sh --base-url https://dewemoji.com/downloads
|
|
```
|
|
|
|
## 8) Versioning rules
|
|
|
|
1. `versionCode` must increase on every release.
|
|
2. `versionName` is user-facing label; ordering uses `versionCode`.
|
|
3. upload APK first, then publish/update `version.json`.
|
|
4. never compare update order using `versionName`.
|
|
|
|
Expected `version.json` fields:
|
|
|
|
- `versionName` (string)
|
|
- `versionCode` (number)
|
|
- `apkUrl` (string)
|
|
- `notes` (optional)
|
|
- `force` (optional bool)
|
|
|
|
## 9) Rollback
|
|
|
|
1. keep old versioned APK objects immutable
|
|
2. repoint latest artifact (`dewemoji-latest.apk`) to known good version
|
|
3. republish matching `version.json`
|
|
4. rerun verify script
|
|
|
|
## 10) High-value troubleshooting
|
|
|
|
### `cap sync android` failures
|
|
|
|
```bash
|
|
npm --prefix dewemoji-capacitor install
|
|
cd dewemoji-capacitor
|
|
npx cap sync android
|
|
```
|
|
|
|
### Bubble not appearing
|
|
|
|
1. confirm overlay permission
|
|
2. confirm notification permission (Android 13+)
|
|
3. remove OEM battery restrictions
|
|
|
|
### APK still shows old UI
|
|
|
|
Rebuild assets, sync, and reinstall debug APK.
|
|
|
|
## 11) Key files
|
|
|
|
- `dewemoji-capacitor/src/index.html`
|
|
- `dewemoji-capacitor/src/app.css`
|
|
- `dewemoji-capacitor/src/app.js`
|
|
- `dewemoji-capacitor/android/app/build.gradle`
|
|
- `dewemoji-capacitor/android/app/src/main/java/com/dewemoji/app/MainActivity.java`
|
|
- `dewemoji-capacitor/android/app/src/main/java/com/dewemoji/app/OverlayBubbleService.java`
|
|
- `dewemoji-capacitor/android/app/src/main/java/com/dewemoji/app/plugins/DewemojiOverlayPlugin.java`
|
|
- `scripts/apk/build-release.sh`
|
|
- `scripts/apk/publish-r2.sh`
|
|
- `scripts/apk/verify-release.sh`
|