rr3-apk/APK-BUILD-AND-TESTING-GUIDE.md

# 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)