Field Sales App Setup

This guide covers setting up the Open Core Field Sales App for development and production deployment.

Requirements

Development Environment

Requirement	Version	Notes
Flutter SDK	3.9.2+	Required minimum
Android SDK	API 26+	Android 8.0 minimum
iOS SDK	Latest	For iOS builds (macOS only)
Java	17+	Required for Android builds
NDK	Flutter default	Managed by Flutter Gradle plugin

Backend Requirements

• Open Core Business Suite backend running and accessible
• API endpoint URL (e.g., https://your-domain.com/api/V1/)
• Firebase project configured for push notifications
• FieldManager module enabled on backend

Device Requirements

The Field Sales App requires specific permissions for tracking:

• Location (Always): For background GPS tracking
• Activity Recognition: For movement detection
• Notifications: For real-time updates

Setup Steps

1. Clone Repository

git clone <repository-url>
cd apps/open_core_field_sales_app

2. Install Dependencies

flutter pub get

3. Configure Firebase

1. Create a Firebase project at Firebase Console
2. Add an Android app with package name com.opencore.open_core_field_sales_app
3. Download google-services.json
4. Place it in android/app/google-services.json
5. For iOS, download GoogleService-Info.plist and add to ios/Runner/

4. Configure API Base URL

Update the API base URL in lib/api/api_routes.dart:

class APIRoutes {
  // For local development
  static const String baseURL = 'http://192.168.1.x:8000/api/V1/';

  // For production
  // static const String baseURL = 'https://your-domain.com/api/V1/';
}

5. Configure Google Maps (Optional)

For map features, add your Google Maps API key:

Android (android/app/src/main/AndroidManifest.xml):

<meta-data
    android:name="com.google.android.geo.API_KEY"
    android:value="YOUR_GOOGLE_MAPS_API_KEY"/>

iOS (ios/Runner/AppDelegate.swift):

GMSServices.provideAPIKey("YOUR_GOOGLE_MAPS_API_KEY")

6. Generate Code

Generate MobX and Hive code:

dart run build_runner build --delete-conflicting-outputs

For continuous code generation:

dart run build_runner watch --delete-conflicting-outputs

7. Run the App

# Run in debug mode
flutter run

# Run on specific device
flutter run -d <device_id>

Android Permissions

The Field Sales App requires specific Android permissions for tracking. These are already configured in the manifest:

<!-- Location -->
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />

<!-- Background Service -->
<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_LOCATION" />
<uses-permission android:name="android.permission.WAKE_LOCK" />
<uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" />

<!-- Activity Recognition -->
<uses-permission android:name="android.permission.ACTIVITY_RECOGNITION" />
<uses-permission android:name="com.google.android.gms.permission.ACTIVITY_RECOGNITION" />

Production Build

Android APK

# Build release APK
flutter build apk --release

# Build split APKs by ABI
flutter build apk --release --split-per-abi

Android App Bundle

flutter build appbundle --release

iOS Build

flutter build ios --release
open ios/Runner.xcworkspace

App Flow

The Field Sales App follows a specific authentication and verification flow:

Splash Screen
    |
    v
Login Screen (if not logged in)
    |
    v
Device Verification (if not verified)
    |
    v
Permissions Screen (if permissions missing)
    |
    v
Home Screen (with lifecycle monitoring)

Device Verification

• Each device must be verified by an administrator
• Prevents unauthorized devices from accessing the system
• Device ID is registered on first login

Permission Management

• App checks permissions on every resume from background
• Automatically redirects to permissions screen if revoked
• All three permissions (location, activity, notifications) required

Customization

App Branding

1. App Name: Update in android/app/src/main/AndroidManifest.xml
2. Package Name: Update applicationId in android/app/build.gradle.kts
3. App Icons: Replace in android/app/src/main/res/

Tracking Settings

Default tracking settings can be configured:

• Distance Filter: 10-500 meters (default: 10m)
• Update Interval: Configurable from backend
• Offline Storage: Enable/disable offline tracking

Troubleshooting

Background Tracking Not Working

1. Ensure all permissions are granted (especially background location)
2. Check battery optimization settings - disable for this app
3. Verify foreground service is running
4. Check logs for permission errors

401 Unauthorized in Background

The app automatically reloads SharedPreferences before each API call in background service. If issues persist:

1. Check token expiry
2. Verify device is still verified
3. Re-login to refresh token

Offline Data Not Syncing

1. Check network connectivity
2. Use manual sync in tracking settings
3. Verify Hive boxes are initialized
4. Check backend API availability

Slider/Distance Filter Errors

• Minimum distance filter is 10 meters
• Values below 10m are automatically clamped

Backend Module Requirements

Ensure these modules are enabled on the backend:

Module	Purpose
FieldManager	Core field sales functionality
Attendance (GPS)	Location-based attendance
FieldTask	Task management (optional)
SalesTarget	Sales tracking (optional)
ProductOrder	Order management (optional)
PaymentCollection	Payment tracking (optional)

Next Steps

• Explore Features - Learn about app capabilities
• FieldManager Module - Backend configuration