dewemoji/dewemoji-apk-companion-build-walkthrough.md

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:

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:

npm --prefix dewemoji-capacitor run build

4) Debug build and device install

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:

./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)

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:

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:

./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:

./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

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