Building health and fitness applications often requires coordinating real-time position updates with health metrics, weather data, and third-party biometric services. Combining individual packages for each provider can quickly result in complex permissions management and messy native integrations. The wellness_sdk Flutter package simplifies this process by presenting a single, unified API surface for both location tracking and wellness data ingestion across iOS and Android.

When to Use the wellness_sdk Flutter Package

The wellness_sdk package is ideal when your application needs to combine geospatial context with health or biometric metrics. Common use cases include:

  • Real-Time Activity Tracking: Enriching run or cycle tracking with concurrent environmental and weather context.
  • Context-Aware Meditation Apps: Adapting user audio or exercise routines based on ambient conditions and location.
  • Corporate Wellness Dashboards: Aggregating step counts and biometric metrics across diverse user devices into unified backend systems.
  • Personal Health Journals: Auto-synchronizing spatial and physical activity data in local or cloud stores.
  • Research Studies: Collecting continuous background location and health metrics under unified permission workflows.

Core Architectural Components

The package simplifies underlying complexity through three core classes:

  • LocationService: Handles background and foreground geolocation updates, emitting standardized stream events.
  • ApiConnector: Provides seamless connections to external health and wellness APIs without requiring low-level platform code.
  • DataCache: Manages transient local storage for offline support and batched backend synchronization.
Note: Always test continuous tracking scenarios in Sandbox Mode during early development to avoid exhausting API quotas or draining test device batteries.

Installation and Platform Configuration

To add the package to your project, run the following command in your terminal:

Code
flutter pub add wellness_sdk

Native Platform Setup

Because the SDK accesses platform-level geolocation and background processing features, native configuration files must be updated before running your app.

iOS Setup (Info.plist)

Add location and background usage descriptions to your ios/Runner/Info.plist file:

Code
<key>NSLocationWhenInUseUsageDescription</key>
<string>This app needs access to location when open to track fitness activities.</string>
<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>This app needs background location access to log your workouts contextually.</string>

Android Setup (AndroidManifest.xml)

Ensure the following permissions are requested in your android/app/src/main/AndroidManifest.xml:

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

Complete Code Example

The following example demonstrates initializing the wellness_sdk Flutter package and listening to location streams in a Flutter widget tree:

Dart / Flutter
import 'dart:async';
import 'package:flutter/material.dart';
import 'package:wellness_sdk/wellness_sdk.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  
  // Initialize the Wellness SDK with required third-party provider keys
  await WellnessSdk.initialize(
    apiKeys: {'googleFit': 'YOUR_KEY_HERE'},
  );
  
  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return const MaterialApp(
      home: Scaffold(
        body: WellnessHome(),
      ),
    );
  }
}

class WellnessHome extends StatefulWidget {
  const WellnessHome({super.key});

  @override
  State<WellnessHome> createState() => _WellnessHomeState();
}

class _WellnessHomeState extends State<WellnessHome> {
  StreamSubscription? _positionSub;
  String _status = 'Initializing SDK...';

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

  void _listenToLocationUpdates() {
    _positionSub = WellnessSdk.locationService.positionStream.listen(
      (position) {
        setState(() {
          _status = 'Lat: ${position.latitude}, Lon: ${position.longitude}';
        });
      },
      onError: (error) {
        setState(() {
          _status = 'Location Error: $error';
        });
      },
    );
  }

  @override
  void dispose() {
    _positionSub?.cancel();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Wellness SDK Integration')),
      body: Center(
        child: Padding(
          padding: const EdgeInsets.all(16.0),
          style: Theme.of(context).textTheme.titleMedium,
          child: Text(_status),
        ),
      ),
    );
  }
}

Common Pitfalls and Watch Outs

  • Android 12+ Permission Restrictions: Android 12 introduced explicit precise vs. approximate location permissions. Requesting background location permissions must be deferred until fine/coarse permissions have been explicitly granted by the user.
  • Battery Consumption: Continuous, high-precision background location tracking drains battery fast. Configure polling intervals conservatively for long-running workflows.
  • Increased App Binary Size: Native frameworks bundled inside third-party health libraries will increase your total app bundle size.

Package Alternatives

Depending on your architecture, individual packages can be used instead of a combined solution:

  • geolocator or location: Ideal if your app only requires raw location coordinates without health data integration.
  • health_kit / google_fit: Best suited if you need ecosystem-specific biometric data without custom location wrappers.
  • flutter_background_geolocation: Excellent for enterprise-grade geofencing and robust background battery optimization when health API integration is not needed.

Frequently Asked Questions

What is the primary benefit of using the wellness_sdk Flutter package?

It unifies background location tracking, third-party health API integrations, and local data caching into a single stream-based API for Flutter apps.

How do I handle Android 12+ permissions with wellness_sdk?

You must request foreground precise/coarse location permissions first before prompting the user for background location access, as required by Android 12 guidelines.

Can I use wellness_sdk without live health provider keys during development?

Yes, the SDK provides a sandbox mode that allows developers to test functionality and state updates without connecting live API keys.

Does the wellness_sdk Flutter package support state managers like BLoC or Provider?

Yes, core components like LocationService expose standard Dart Streams, making it straightforward to bind to BLoC, Riverpod, Provider, or Signal-based architectures.