From 27e4ec0a89981d2c91e0b193ae09025acf512e4e Mon Sep 17 00:00:00 2001 From: Daniel Elliott Date: Sun, 22 Feb 2026 00:41:32 -0800 Subject: [PATCH] Add APK build and testing guide documentation --- APK-BUILD-AND-TESTING-GUIDE.md | 416 +++++++++++++++++++++++++++++++++ 1 file changed, 416 insertions(+) create mode 100644 APK-BUILD-AND-TESTING-GUIDE.md diff --git a/APK-BUILD-AND-TESTING-GUIDE.md b/APK-BUILD-AND-TESTING-GUIDE.md new file mode 100644 index 000000000..0f25866a4 --- /dev/null +++ b/APK-BUILD-AND-TESTING-GUIDE.md @@ -0,0 +1,416 @@ +# APK Build & Testing Guide + +**Date:** February 22, 2026 +**APK Version:** v14 (CUSTOMIZED mode - EA URLs eliminated) +**Build Status:** โœ… SUCCESS +**Signature:** โœ… VERIFIED + +--- + +## ๐Ÿ“ฆ APK Build Information + +### Built APK +- **Filename:** `RR3-v14-NoEAURLs-signed.apk` +- **Size:** 103.92 MB +- **Location:** `E:\rr3\rr3-apk\RR3-v14-NoEAURLs-signed.apk` +- **Build Date:** February 22, 2026 + +### Configuration Changes Applied +1. โœ… **Nimble Mode:** Changed from `"live"` to `"customized"` +2. โœ… **EA URLs:** Eliminated from execution path +3. โœ… **Fallback URL:** Added `http://localhost:5001` to manifest +4. โœ… **Priority System:** SharedPreferences > Manifest > Never EA + +### Signature Information +- **Keystore:** `rr3-release.keystore` +- **Alias:** `rr3key` +- **v2 Scheme:** โœ… Verified +- **v3 Scheme:** โœ… Verified +- **Valid Until:** July 6, 2053 + +--- + +## ๐Ÿ”ง Build Process + +### Tools Used +1. **apktool 2.10.0** - APK decompilation/recompilation +2. **Java OpenJDK 21.0.10** - Build environment +3. **Android Build Tools 36.1.0** - Signing & verification +4. **apksigner** - APK signing with v2/v3 schemes + +### Build Commands +```powershell +# Build APK +java -jar E:\tools\apktool.jar b E:\rr3\rr3-apk -o RR3-v14-NoEAURLs-unsigned.apk + +# Sign APK +apksigner sign ` + --ks rr3-release.keystore ` + --ks-key-alias rr3key ` + --ks-pass pass:rr3community ` + --key-pass pass:rr3community ` + --out RR3-v14-NoEAURLs-signed.apk ` + RR3-v14-NoEAURLs-unsigned.apk + +# Verify signature +apksigner verify --verbose RR3-v14-NoEAURLs-signed.apk +``` + +### Build Output +``` +I: Using Apktool 2.10.0 with 12 thread(s) +I: Building resources... +I: Smaling smali_classes2 folder into classes2.dex... +I: Building apk file... +I: Copying unknown files/dir... +I: Built apk into: RR3-v14-NoEAURLs-unsigned.apk +``` + +--- + +## ๐Ÿ“ฑ Installation Methods + +### Method 1: ADB Install (Recommended) +```bash +# Connect device via USB with USB debugging enabled +adb devices + +# Install APK +adb install -r RR3-v14-NoEAURLs-signed.apk + +# Or if device already has RR3 installed +adb install -r -d RR3-v14-NoEAURLs-signed.apk +``` + +### Method 2: Drag & Drop +1. Start Android emulator +2. Drag `RR3-v14-NoEAURLs-signed.apk` onto emulator window +3. Wait for installation to complete + +### Method 3: File Transfer +1. Copy APK to device storage +2. Use file manager app to open APK +3. Allow installation from unknown sources +4. Install + +--- + +## ๐Ÿงช Testing Procedure + +### Phase 1: Installation & First Launch + +**Test 1: Clean Install** +```bash +# Ensure no previous RR3 installation +adb uninstall com.ea.games.r3_row + +# Install new APK +adb install RR3-v14-NoEAURLs-signed.apk + +# Monitor logcat during launch +adb logcat -c # Clear log +adb logcat | Select-String "RR3|Synergy|CommunityServer|ServerSetup" +``` + +**Expected Behavior:** +1. โœ… Game launches successfully +2. โœ… `ServerSetupActivity` appears on first launch +3. โœ… User prompted to enter server URL +4. โœ… No crashes or ANR (Application Not Responding) + +**Logcat Checkpoints:** +``` +โœ… "RR3_OfflineModeManager: Initializing OfflineModeManager" +โœ… "CommunityServerManager: Checking server URL" +โœ… "ServerSetupActivity: onCreate" +โœ… "SynergyEnvironmentImpl: ๐ŸŽฏ Using community server from SharedPreferences" +``` + +--- + +### Phase 2: Server URL Configuration + +**Test 2: Server URL Input** +1. Launch game (first time) +2. Enter server URL: `http://localhost:5001` +3. Click "Test Connection" +4. Click "Continue" + +**Expected Behavior:** +1. โœ… Input field accepts URL +2. โœ… Test button attempts connection +3. โœ… Continue button saves URL to SharedPreferences +4. โœ… Game restarts with new URL + +**Verify SharedPreferences:** +```bash +# Check if server URL was saved +adb shell cat /data/data/com.ea.games.r3_row/shared_prefs/rr3_community_server.xml +``` + +**Expected Content:** +```xml + + + http://localhost:5001 + +``` + +--- + +### Phase 3: Network Communication + +**Test 3: Director API Call** +```bash +# Monitor network requests +adb logcat | Select-String "director|http|Synergy" +``` + +**Expected Logcat:** +``` +โœ… "SynergyEnvironmentImpl: ๐ŸŽฏ Using community server from SharedPreferences" +โœ… "http://localhost:5001/director/api/android/getDirectionByPackage" +โœ… No references to "eamobile.com" +โœ… No references to "syn-dir" or "director-stage" +``` + +**Test 4: Verify EA URLs NOT Used** +```bash +# Search for EA domain access attempts +adb logcat | Select-String "eamobile.com" +``` + +**Expected:** ๐Ÿšซ No matches (EA URLs should never appear) + +--- + +### Phase 4: Configuration Verification + +**Test 5: Check Nimble Configuration** +```bash +# Extract app data +adb shell run-as com.ea.games.r3_row cat /data/data/com.ea.games.r3_row/shared_prefs/nimble_preferences.xml +``` + +**Verify:** +- โœ… Configuration mode: `CUSTOMIZED` (not `LIVE`) +- โœ… Server URL: User-configured URL +- โœ… No EA default URLs stored + +**Test 6: Clear SharedPreferences Test** +```bash +# Clear community server preferences +adb shell run-as com.ea.games.r3_row rm /data/data/com.ea.games.r3_row/shared_prefs/rr3_community_server.xml + +# Restart game +adb shell am force-stop com.ea.games.r3_row +adb shell am start -n com.ea.games.r3_row/com.firemint.realracing.MainActivity +``` + +**Expected Behavior:** +1. โœ… ServerSetupActivity appears again (no URL configured) +2. โœ… Falls back to manifest URL: `http://localhost:5001` +3. โœ… Does NOT attempt EA servers + +--- + +### Phase 5: Offline Mode + +**Test 7: Offline Mode Toggle** +```bash +# Check offline mode preferences +adb shell cat /data/data/com.ea.games.r3_row/shared_prefs/rr3_offline_settings.xml +``` + +**Expected Content:** +```xml + + + + +``` + +**Test:** Toggle offline mode in SettingsActivity and verify behavior. + +--- + +## ๐Ÿ› Common Issues & Solutions + +### Issue 1: Installation Failed +**Symptom:** `INSTALL_FAILED_UPDATE_INCOMPATIBLE` + +**Solution:** +```bash +# Uninstall existing app first +adb uninstall com.ea.games.r3_row + +# Then install +adb install RR3-v14-NoEAURLs-signed.apk +``` + +--- + +### Issue 2: App Crashes on Launch +**Check:** +1. Logcat for crash stacktrace +2. Missing native libraries +3. Architecture mismatch (armeabi-v7a vs arm64-v8a) + +**Debug:** +```bash +adb logcat -s AndroidRuntime:E +``` + +--- + +### Issue 3: ServerSetupActivity Not Appearing +**Possible Causes:** +1. SharedPreferences already exist (previous installation) +2. MainActivity not checking properly + +**Fix:** +```bash +# Clear all app data +adb shell pm clear com.ea.games.r3_row +``` + +--- + +### Issue 4: Network Requests Failing +**Check:** +1. Server is running on `http://localhost:5001` +2. Emulator/device can reach localhost +3. Use emulator's special address: `http://10.0.2.2:5001` + +**Fix:** +```bash +# Forward port from host to device +adb reverse tcp:5001 tcp:5001 +``` + +--- + +## ๐Ÿ“Š Logcat Filters + +### Filter 1: RR3 Application Logs +```bash +adb logcat | Select-String "RR3_|CommunityServer|ServerSetup|OfflineMode" +``` + +### Filter 2: Network Communication +```bash +adb logcat | Select-String "http|Synergy|director|eamobile" +``` + +### Filter 3: Errors Only +```bash +adb logcat *:E | Select-String "com.ea.games.r3" +``` + +### Filter 4: Crashes +```bash +adb logcat -s AndroidRuntime:E +``` + +--- + +## โœ… Success Criteria + +### Build Success โœ… +- [x] APK built without errors +- [x] APK signed with valid certificate +- [x] Signature verified (v2 & v3) +- [x] APK size reasonable (103.92 MB) + +### Configuration Success โœ… +- [x] Nimble mode set to CUSTOMIZED +- [x] EA URLs eliminated from execution path +- [x] Fallback URL added to manifest +- [x] Priority system verified in code + +### Installation Success (To Be Tested) +- [ ] APK installs on device/emulator +- [ ] No installation errors +- [ ] Package name correct: `com.ea.games.r3_row` +- [ ] Permissions requested appropriately + +### Runtime Success (To Be Tested) +- [ ] App launches without crashes +- [ ] ServerSetupActivity appears on first launch +- [ ] Server URL input works +- [ ] SharedPreferences saved correctly +- [ ] Network requests go to community server +- [ ] EA URLs never contacted + +--- + +## ๐Ÿš€ Next Steps + +### Immediate Testing +1. **Get working emulator or physical device** + - Android 8.0+ recommended + - USB debugging enabled + - Unknown sources allowed + +2. **Install APK** + ```bash + adb install -r RR3-v14-NoEAURLs-signed.apk + ``` + +3. **Monitor first launch** + ```bash + adb logcat -c + adb logcat | Select-String "RR3|Synergy" + ``` + +4. **Verify URL priority** + - Check ServerSetupActivity appears + - Enter server URL + - Verify SharedPreferences created + - Confirm community server used + +### After Successful Test +1. โœ… Document any issues found +2. โœ… Commit working APK to repository +3. โœ… Create release notes +4. โœ… Begin Phase 2 (Events Service) + +--- + +## ๐Ÿ“ Known Limitations + +1. **Emulator Issues** + - Android emulators on current system not starting properly + - Recommend physical device testing + - Alternative: WSA, Bluestacks, NOX, LDPlayer + +2. **SSL Validation** + - Still disabled in Http.java (ALLOW_ALL_HOSTNAME_VERIFIER) + - Security risk - needs fixing + - Accept any certificate currently + +3. **Localhost Access** + - From emulator: Use `10.0.2.2:5001` instead of `localhost:5001` + - Requires `adb reverse tcp:5001 tcp:5001` for port forwarding + +--- + +## ๐Ÿ” Security Notes + +### APK Signature +- Signed with rr3-release.keystore +- Valid until 2053 +- SHA256 fingerprint: A9:A0:08:7B:2F:C3:7A:0D:A4:EE:FE:53:53:05:BA:AF:A1:08:FC:C1:5B:50:1F:FA:5D:EA:E2:2E:98:7D:43:C7 + +### Network Security +- โš ๏ธ SSL validation disabled (needs fix) +- โœ… No EA server communication +- โœ… User-controlled server selection +- โœ… Community server prioritized + +--- + +**Build Status:** โœ… SUCCESS +**Ready for Testing:** โœ… YES +**Emulator Available:** โš ๏ธ Issues (use physical device) +**Next Phase:** Testing on device + Phase 2 (Events Service)