Skip to content

QUICK_START.md

Latest commit

 

History

History
186 lines (145 loc) · 4.59 KB

QUICK_START.md

File metadata and controls

186 lines (145 loc) · 4.59 KB

🚀 Quick Start Guide - Leaderboard Sync Fix

Immediate Actions Required

1. Rebuild the App

cd ZENITH-Frontend
flutter clean
flutter pub get
flutter run  # or flutter build apk

2. First Launch Checklist

  • Grant Health Connect permissions (Steps & Distance)
  • Grant Location permissions (While using app OR Always)
  • Accept Battery Optimization exemption dialog
  • Walk around to generate steps

3. Test Manual Sync

  1. Open app → Leaderboard
  2. Tap menu (⋮) → "Force Sync Steps"
  3. Should see: "Starting manual step sync..." toast
  4. Wait 2-3 seconds
  5. Should see: "Step sync completed!" toast
  6. Numbers should update

Debug Commands (Windows)

Monitor Logs in Real-Time

# Start monitoring
adb logcat -c
adb logcat | Select-String -Pattern "StepSync|BackgroundSync|BatteryOpt"

Check App Status

# Is app installed?
adb shell pm list packages | Select-String "zenith"

# Battery optimization status
adb shell dumpsys deviceidle whitelist | Select-String "zenith"

# Check background tasks
adb shell dumpsys alarm | Select-String "com.example.zenith"

Force Background Sync (for testing)

# Clear logs first
adb logcat -c

# Watch for sync activity
adb logcat | Select-String "StepSync"

Quick Troubleshooting

Issue Check Fix
No sync at all Battery optimization Settings → Apps → ZENITH → Battery → Unrestricted
Permission errors Health Connect Settings → Health Connect → ZENITH → Grant all
Location errors Location permission Settings → Apps → ZENITH → Permissions → Location → Always
Backend errors Auth token Re-login to app
No steps recorded Walking Actually walk around!

Expected Behavior

Automatic Background Sync

  • Frequency: Every 15 minutes
  • Trigger: WorkManager (Android)
  • Requirements: Network + Battery not low
  • Logs: Check for [StepSync] entries

Manual Sync

  • Trigger: Leaderboard menu → "Force Sync Steps"
  • Immediate: Runs right away
  • Feedback: Toast messages
  • Refresh: Auto-refreshes leaderboard after 2 seconds

Success Indicators

✅ Logs show:

[StepSync] >>> Step sync invoked with ID: ...
[StepSync] Health Connect permission: true
[StepSync] Fetched delta: steps=150, distance=0.1125
[StepSync] Location: 28.6139, 77.2090
[StepSync] Backend response: total_points=1268.3
[StepSync] ✅ Sync successful!

✅ Leaderboard updates:

  • Points increase
  • Distance increases
  • Rank changes (if applicable)

✅ Backend receives:

{
  "distance_delta_km": 0.1125,
  "steps_delta": 150,
  "latitude": 28.6139,
  "longitude": 77.2090,
  "sync_source": "health_connect",
  "sync_id": "uuid-here"
}

Files Changed

  • ✅ AndroidManifest.xml - Permissions
  • ✅ MainActivity.kt - Battery optimization
  • ✅ battery_optimization_service.dart - NEW
  • ✅ background_sync_service.dart - Enhanced
  • ✅ leaderboard_screen.dart - Manual sync
  • ✅ main.dart - Init battery opt

Testing Shortcuts

# Full test sequence
.\test_sync.bat

# Quick log check
adb logcat | Select-String "StepSync" | Select-Object -Last 20

# Force kill and restart background workers
adb shell am force-stop com.example.zenith
adb shell am start -n com.example.zenith/.MainActivity

Common Log Patterns

✅ Success

[StepSync] ✅ Sync successful!
[BackgroundSync] Step sync completed

❌ Auth Failed

[StepSync] No auth token, skipping sync

Fix: Re-login

❌ Permission Failed

[StepSync] Health Connect permission: false

Fix: Grant Health Connect permissions

❌ Location Failed

[StepSync] Location permission: LocationPermission.denied

Fix: Grant location permission

❌ Backend Failed

[StepSync] ❌ Failed: BackendException

Fix: Check backend server status, network, auth token

Pro Tips

💡 Use manual sync for immediate testing - Don't wait 15 minutes!

💡 Check logs BEFORE complaining - They tell you exactly what's wrong

💡 Walk at least 50+ steps - Small movements may not register

💡 Ensure device not in Doze mode - Charge device or keep screen on

💡 Network must be available - Background sync requires connectivity

Need Help?

  1. Check LEADERBOARD_SYNC_FIX.md - Full detailed documentation
  2. Run test_sync.bat - Automated testing script
  3. Monitor logs - adb logcat | Select-String "StepSync"
  4. Test in Postman - Verify backend is actually working

Last Updated: December 29, 2025 Status: ✅ Ready for testing