android-publisher

name	android-publisher
description	Workflow for building, testing, and publishing new Android app versions (PWA/TWA) using Bubblewrap to the Google Play Store. Use this when the user wants to build a new APK/AAB or release an update to Android.

Android Publisher Skill

This skill provides the procedural workflow for building and publishing updates to the Divemap Android app (PWA packaged via Bubblewrap).

Workflow

When asked to build or publish a new Android version, follow these steps exactly:

1. Update Version Name (Optional)

You only need to manually update the twa-manifest.json file if you are explicitly requested to change the public-facing version string. Bubblewrap will automatically handle incrementing the internal appVersionCode during the build process.

If requested to change the version string (e.g., to "1.1"):

1. Open divemap-android/twa-manifest.json
2. Update the "appVersionName" and "appVersion" strings to reflect the new public-facing version.
3. Do NOT manually increment "appVersionCode".

2. Build and Archive the Android App

Navigate to the project root and execute the custom Android build script. This script automatically runs Bubblewrap and renames the output files to include the version name and code, storing them in an archive folder so previous versions are not overwritten.

./scripts/build-android.sh

Note: The user will need to enter the Keystore password and Key password interactively during this build.

The script will generate versioned files in the divemap-android/releases/ directory:

• Divemap-v[versionName]-c[versionCode].apk (Used for local phone testing)
• Divemap-v[versionName]-c[versionCode].aab (Used for uploading to the Google Play Console)

3. Verify Digital Asset Links (Crucial for TWA)

If this is a new app or the signing keys have changed, verify that the assetlinks.json file is correctly configured.

1. Locate the frontend assetlinks.json file: frontend/public/.well-known/assetlinks.json
2. Ensure it contains the SHA-256 fingerprint generated by the Bubblewrap keystore.
3. Ensure it contains the Google Play App Signing SHA-256 fingerprint (found in Play Console -> Setup -> App Integrity), as Google re-signs the app before distribution.

If the file was modified, instruct the user to deploy the frontend before testing the Android app.

4. Local Testing

Instruct the user to test the APK on their physical Android device before uploading to Play Console.

• They must transfer the new divemap-android/releases/Divemap-v[versionName]-c[versionCode].apk to their phone.
• They must enable "Install from unknown sources" to install it.
• Verification Check: Ask the user to verify that the top browser address bar is completely hidden. (If it is visible, it means the assetlinks.json is not correctly deployed or cached).

5. Play Console Upload

Once testing is confirmed successful:

1. Instruct the user to log into the Google Play Console.
2. Navigate to their app -> Production (or Internal Testing) -> Create new release.
3. Instruct them to upload the new divemap-android/releases/Divemap-v[versionName]-c[versionCode].aab file.
4. Help the user draft concise release notes (under 500 characters) highlighting new features or bug fixes since the last release.

Troubleshooting

• 403 Forbidden on assetlinks.json: Check Nginx configuration (nginx/prod.conf). Nginx by default blocks hidden files (location ~ /\. { deny all; }). An explicit rule allowing location ^~ /.well-known/ { allow all; } must exist before the block rule.
• Address Bar is visible: This means Android's Digital Asset Link verification failed. Ensure https://divemap.gr/.well-known/assetlinks.json returns a 200 OK, has valid JSON, and contains the correct SHA-256 fingerprints.
• PWA not rotating to landscape: Ensure frontend/vite.config.mjs has orientation: 'any' in the PWA manifest plugin options.