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.1

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

Add permissions to android/app/src/main/AndroidManifest.xml:

<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" />

For background services to work properly on Android 12+, add to your app's build.gradle:

android {
  compileSdkVersion 33
  // ...
}

⚠️ Compatibility

Flutter: 3.10.0 or higher
Dart: 3.1.0 or higher
Android: API 21+ (workmanager requirement)
iOS: 11.0+

🚀 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);

🎯 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