vk_location_sharing

A powerful and flexible Flutter package for implementing real-time location sharing with both foreground streams and periodic background updates. It provides a clean, unified API to handle permissions and location tracking with ease.

✨ Features

✅ Single Initialize Function: Call initialize() once in your main.dart to set up everything
🎯 Unified Location Sharing: Simple shareLocation() method that handles all permissions and starts tracking
📍 Real-time Foreground Stream: Live location updates as the user moves
🔄 Periodic Background Updates: Regular location tracking even when app is backgrounded (via Workmanager)
🔀 Flexible Stream Handling: Choose to handle foreground and background updates separately or combined
🎛️ Custom Callbacks: Execute custom code with each location update (e.g., send to backend)
🔐 Built-in Permission Handling: Automatic permission request and verification
⚙️ Highly Configurable: Customize accuracy, distance filters, update frequency, and more
📱 Battery Optimized: Uses distance filters to minimize battery drain
🧪 Well Tested: Comprehensive unit tests with mocking support

📦 Installation

Add vk_location_sharing to your pubspec.yaml:

dependencies:
  vk_location_sharing: ^1.0.2

Then run:

flutter pub get

🔧 Platform Setup

iOS

Add the following keys to your Info.plist file (or use Xcode UI):

<key>NSLocationWhenInUseUsageDescription</key>
<string>This app needs access to your location to share it with others.</string>
<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>This app needs access to your location at all times to share it with others.</string>
<key>NSLocationAlwaysUsageDescription</key>
<string>This app needs access to your location at all times to share it with others.</string>

For background location tracking, add to Info.plist:

<key>UIBackgroundModes</key>
<array>
  <string>location</string>
  <string>fetch</string>
</array>

Android

⚠️ CRITICAL: Background location setup is complex on Android. Follow ALL steps below.

1. Add Required Permissions to `android/app/src/main/AndroidManifest.xml`:

<!-- Foreground location permissions -->
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />

<!-- REQUIRED: Background location permission (most restrictive) -->
<uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />

<!-- REQUIRED for Android 12+: Foreground service permissions -->
<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_LOCATION" />

<!-- Recommended: For sending locations to backend -->
<uses-permission android:name="android.permission.INTERNET" />

2. Update `android/app/build.gradle`:

android {
  compileSdkVersion 34  // ⚠️ Must be 33+ for Android 12+ support
  targetSdkVersion 34   // ⚠️ Set to 33+ for foreground service support

  defaultConfig {
    minSdkVersion 21    // Workmanager requires API 21+
  }
}

3. CRITICAL - Runtime Permissions:

The ACCESS_BACKGROUND_LOCATION permission must be requested separately:

// First, request standard location permission
final permission = await Permission.location.request();

// Then, request background location permission
if (permission.isGranted) {
  final bgPermission = await Permission.locationAlways.request();
  // bgPermission will be granted if user allows "Always" access
}

Note: Users must grant "Allow all the time" (not "Allow only while using the app") for background location to work. This is an OS-level requirement on Android 10+.

4. Test on Physical Device:

⚠️ Background location does NOT work on Android emulator
Must test on a real Android device with location services enabled
Ensure battery optimization is disabled for your app in Settings

5. Troubleshooting Android Background Location:

Problem: Background location updates not being received

Check that user has granted "Always allow" permission:

adb shell dumpsys package com.yourapp.name | grep android.permission.ACCESS_BACKGROUND_LOCATION

Verify app is not restricted by battery optimization:
```
adb shell dumpsys deviceidle whitelist
```
Check if Workmanager is scheduling tasks (debug logs):
```
adb logcat | grep "BG_SERVICE"
```
Ensure device has GPS signal (some indoor locations won't work)

⚠️ Compatibility

Flutter: 3.10.0 or higher
Dart: 3.1.0 or higher
Android: API 21+ (Workmanager requirement), compileSdk 33+ (Android 12+ foreground service)
iOS: 11.0+
Physical Device: Required for Android background location testing (not supported on emulator)

🚀 Quick Start

Basic Usage

import 'package:flutter/material.dart';
import 'package:vk_location_sharing/vk_location_sharing.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  runApp(const MyApp());
}

class MyHomePage extends StatefulWidget {
  @override
  State<MyHomePage> createState() => _MyHomePageState();
}

class _MyHomePageState extends State<MyHomePage> {
  final _vkLocation = VkLocationSharing();
  Position? _currentPosition;
  bool _isSharing = false;

  @override
  void initState() {
    super.initState();
    _initializeLocation();
  }

  Future<void> _initializeLocation() async {
    // Initialize the package once in your app
    await _vkLocation.initialize(
      config: LocationConfig(
        accuracy: LocationAccuracy.best,
        distanceFilter: 5, // Update every 5 meters
        backgroundUpdateFrequency: const Duration(minutes: 15),
      ),
    );

    // Listen to location updates
    _vkLocation.foregroundLocationStream.listen((position) {
      setState(() {
        _currentPosition = position;
      });
    });
  }

  Future<void> _toggleSharing() async {
    if (!_isSharing) {
      final success = await _vkLocation.shareLocation();
      if (success) {
        setState(() => _isSharing = true);
      }
    } else {
      await _vkLocation.stopSharing();
      setState(() => _isSharing = false);
    }
  }

  @override
  void dispose() {
    _vkLocation.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Location Sharing')),
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: [
            if (_currentPosition != null)
              Text('Lat: ${_currentPosition!.latitude}\nLng: ${_currentPosition!.longitude}')
            else
              const Text('No location data'),
            const SizedBox(height: 20),
            ElevatedButton(
              onPressed: _toggleSharing,
              child: Text(_isSharing ? 'Stop Sharing' : 'Start Sharing'),
            ),
          ],
        ),
      ),
    );
  }
}

📚 Advanced Usage

Separate Foreground and Background Streams

await _vkLocation.initialize(
  config: LocationConfig(
    handleForegroundAndBackgroundSeparately: true,
    accuracy: LocationAccuracy.best,
    distanceFilter: 5,
    backgroundUpdateFrequency: const Duration(minutes: 15),
  ),
);

// Listen to foreground updates
_vkLocation.foregroundLocationStream.listen((position) {
  print('Foreground: ${position.latitude}');
});

// Listen to background updates separately
_vkLocation.backgroundLocationStream.listen((position) {
  print('Background: ${position.latitude}');
});

Custom Location Handler

await _vkLocation.initialize(
  config: LocationConfig(
    accuracy: LocationAccuracy.best,
    onLocationUpdate: (position, {required isBackground}) async {
      // Send to your backend API
      if (isBackground) {
        await sendLocationToBackend(position, background: true);
      } else {
        await sendLocationToBackend(position, background: false);
      }
    },
  ),
);

// Start only foreground sharing
await _vkLocation.shareLocation(includeForeground: true, includeBackground: false);

// Start only background sharing
await _vkLocation.shareLocation(includeForeground: false, includeBackground: true);

// Stop only background sharing
await _vkLocation.stopSharing(stopForeground: false, stopBackground: true);

🔧 Debugging Background Location

Enable debug logging to diagnose background location issues:

// During initialization, set a detailed onLocationUpdate callback:
await _vkLocation.initialize(
  config: LocationConfig(
    accuracy: LocationAccuracy.best,
    backgroundUpdateFrequency: const Duration(minutes: 5), // Use shorter interval for testing
    onLocationUpdate: (position, {required isBackground}) async {
      final debugInfo = '''
        Location Update:
        - Background: $isBackground
        - Lat: ${position.latitude}
        - Lng: ${position.longitude}
        - Accuracy: ${position.accuracy}m
        - Timestamp: ${DateTime.now()}
      ''';
      print(debugInfo);

      // Send to backend or log for analysis
      // await sendLocationToBackend(position, isBackground);
    },
  ),
);

Debug Output Examples:

✅ Foreground working:

[BG_SERVICE] Background task triggered
I/flutter: Location Update:
   - Background: false
   - Lat: 37.7749
   - Lng: -122.4194
   - Accuracy: 10m

❌ Background not working:

No [BG_SERVICE] messages appear in logs
Solution: Check Android permissions and background limitations

❌ Callback not called:

Task triggers but callback doesn't execute
Solution: Ensure onLocationUpdate callback is properly registered during initialize()

🎯 Configuration Options

The LocationConfig class provides these customization options:

Parameter	Type	Default	Description
`handleForegroundAndBackgroundSeparately`	bool	false	If true, use separate streams for foreground/background. If false, all updates go to foreground stream.
`accuracy`	LocationAccuracy	high	Desired GPS accuracy (high, best, low, lowest)
`distanceFilter`	int	0	Minimum distance in meters between updates
`backgroundUpdateFrequency`	Duration	15 minutes	Frequency of background updates
`onLocationUpdate`	Function	null	Custom callback executed with each location update

📡 API Reference