Add APK build and testing guide documentation
This commit is contained in:
416
APK-BUILD-AND-TESTING-GUIDE.md
Normal file
416
APK-BUILD-AND-TESTING-GUIDE.md
Normal file
@@ -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
|
||||
<?xml version='1.0' encoding='utf-8' standalone='yes' ?>
|
||||
<map>
|
||||
<string name="server_url">http://localhost:5001</string>
|
||||
</map>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 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
|
||||
<?xml version='1.0' encoding='utf-8' standalone='yes' ?>
|
||||
<map>
|
||||
<boolean name="offline_mode_enabled" value="false" />
|
||||
</map>
|
||||
```
|
||||
|
||||
**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)
|
||||
Reference in New Issue
Block a user