Flutter WorkoutBridge #

A comprehensive Flutter plugin for integrating with Apple WorkoutKit and HealthKit, enabling you to create custom workouts, schedule them to Apple Watch, and retrieve detailed workout data.

Features #

• ✅ Create custom structured workouts with intervals, warmup, and cooldown
• ⌚ Schedule workouts directly to Apple Watch via WorkoutKit
• 📊 Retrieve comprehensive workout data from HealthKit
• 🗺️ Access GPS route data and heart rate information
• 🔐 Handle HealthKit permissions seamlessly
• 📱 Native iOS integration with SwiftUI preview components

Requirements #

• iOS 17.0+
• Xcode 15+
• Flutter 3.0+
• Physical iPhone and Apple Watch for testing

Installation #

Add this to your package's pubspec.yaml file:

dependencies:
  flutter_workout_bridge: ^1.0.0

Setup #

iOS Permissions #

Add these permissions to your ios/Runner/Info.plist:

<key>NSHealthShareUsageDescription</key>
<string>This app needs access to read your workout data.</string>
<key>NSHealthUpdateUsageDescription</key>
<string>This app needs access to save workout data.</string>

HealthKit Entitlement #

Enable HealthKit in your iOS project:

1. Open ios/Runner.xcworkspace in Xcode
2. Select your project target
3. Go to "Signing & Capabilities"
4. Add "HealthKit" capability

Quick Start #

import 'package:flutter_workout_bridge/flutter_workout_bridge.dart';

// Request permissions
bool hasPermissions = await FlutterWorkoutBridge.requestPermissions();

// Create a workout
Map<String, dynamic> workout = WorkoutTemplates.intervalRun(
  name: "Morning Intervals",
  warmupMinutes: 5,
  intervalMinutes: 2,
  restMinutes: 1,
  intervals: 8,
  cooldownMinutes: 5,
);

// Schedule to Apple Watch
Map<String, dynamic> result = await FlutterWorkoutBridge.presentWorkout(workout);

// Get completed workouts
List<Map<String, dynamic>> workouts = await FlutterWorkoutBridge.getCompletedWorkouts(daysBack: 30);

API Reference #

Core Methods #

requestPermissions()

Request HealthKit permissions from the user.

presentWorkout(Map<String, dynamic> workout)

Schedule a workout to Apple Watch and show it in the Workout app.

getCompletedWorkouts({int daysBack = 7})

Retrieve workout data from HealthKit.

Workout Templates #

Pre-built workout templates for common activities:

// Interval running workout
WorkoutTemplates.intervalRun(name: "Sprint Intervals");

// Cycling workout
WorkoutTemplates.cyclingWorkout(name: "Morning Ride");

// Yoga session
WorkoutTemplates.yogaSession(name: "Evening Flow");

// Strength training
WorkoutTemplates.strengthWorkout(name: "Upper Body");

Custom Workout Builder #

final workout = WorkoutBuilder("Custom Run")
    .addWarmup(durationType: DurationType.time, duration: 300)
    .addInterval(name: "Main Set", durationType: DurationType.distance, duration: 5000)
    .addCooldown(durationType: DurationType.time, duration: 300)
    .build();

Platform Support #

Note: This plugin is iOS-only due to its integration with Apple's WorkoutKit and HealthKit frameworks.

Example App #

See the /example folder for a complete implementation showing:

• Permission handling
• Workout creation and scheduling
• Data visualization
• Error handling

Troubleshooting #

Common Issues #

Workout not appearing on Apple Watch:

• Ensure iPhone and Watch are paired and nearby
• Check that both devices have sufficient battery
• Verify WorkoutKit permissions are granted

HealthKit permission denied:

• Guide users to Settings > Privacy & Security > Health
• Explain why permissions are needed
• Handle graceful fallbacks

Build errors:

• Ensure minimum iOS 17.0 deployment target
• Verify HealthKit capability is enabled
• Check that all required frameworks are linked

Contributing #

Contributions are welcome! Please read our contributing guidelines and submit pull requests to our GitHub repository.

License #

This project is licensed under the MIT License - see the LICENSE file for details.

Author #

Shayan Khan

Building bridges between Flutter and native iOS capabilities