apple_workout_scheduler

A Flutter plugin to schedule and push custom workouts to Apple Watch using HealthKit. Create structured interval workouts with distance or time-based goals, perfect for running, cycling, and other cardio activities.

Features

• 🏃 Schedule custom workout sessions on Apple Watch
• ⏱️ Support for time-based and distance-based workout goals
• 🔄 Create interval workouts with work and recovery periods
• 🔒 Request and check HealthKit authorization status
• 📅 Schedule workouts for specific dates and times
• 📱 Seamless integration with Apple Health ecosystem

Platform Support

iOS	macOS	Android	Web	Windows	Linux
✅	❌	❌	❌	❌	❌

Requirements

• iOS 14.0+
• HealthKit capabilities enabled
• Apple Watch paired with iPhone

Installation

Add apple_workout_scheduler to your pubspec.yaml:

dependencies:
  apple_workout_scheduler: ^0.0.1

Then run:

flutter pub get

Setup

iOS Configuration

1. Enable HealthKit Capability

   In Xcode, open your project and navigate to:

   • Select your target → Signing & Capabilities
   • Click "+ Capability" and add "HealthKit"

2. Update Info.plist

   Add the following keys to your ios/Runner/Info.plist:

   <key>NSHealthShareUsageDescription</key>
   <string>This app needs access to read your health data to schedule workouts</string>
   <key>NSHealthUpdateUsageDescription</key>
   <string>This app needs access to write workout data to your health profile</string>
   

Usage

Basic Example

import 'package:apple_workout_scheduler/apple_workout_scheduler.dart';
import 'package:apple_workout_scheduler/entities/workout_model.dart';
import 'package:apple_workout_scheduler/entities/auth_response_enum.dart';

final _appleWorkoutScheduler = AppleWorkoutScheduler();

// Request HealthKit authorization
Future<void> requestAuthorization() async {
  WorkoutAuthentication status =
      await _appleWorkoutScheduler.requestAuthorization();

  if (status == WorkoutAuthentication.authorized) {
    print('Authorization granted!');
  }
}

// Check current authorization status
Future<void> checkAuthorization() async {
  WorkoutAuthentication status =
      await _appleWorkoutScheduler.getAuthorization();
  print('Current status: ${status.name}');
}

// Schedule a simple workout
Future<void> scheduleWorkout() async {
  ExceriseModel workout = ExceriseModel(
    title: 'Morning Run',
    date: DateTime.now(),
    sessions: [
      SessionModel(
        reps: 1,
        workouts: [
          Workout(
            sessionType: SessionType.work,
            goalType: SessionGoalType.distance,
            goal: 5000, // 5000 meters
          ),
        ],
      ),
    ],
  );

  await _appleWorkoutScheduler.scheduleWorkout(workout);
}

Advanced Example: Interval Training

Create a complex interval workout with multiple work/recovery cycles:

Future<void> scheduleIntervalWorkout() async {
  ExceriseModel intervalWorkout = ExceriseModel(
    title: 'Interval Training',
    date: DateTime.now().add(Duration(hours: 1)), // Schedule for later
    sessions: [
      // Warm-up
      SessionModel(
        reps: 1,
        workouts: [
          Workout(
            sessionType: SessionType.work,
            goalType: SessionGoalType.time,
            goal: 300, // 5 minutes in seconds
          ),
        ],
      ),
      // Main interval set (5x)
      SessionModel(
        reps: 5,
        workouts: [
          Workout(
            sessionType: SessionType.work,
            goalType: SessionGoalType.distance,
            goal: 1000, // 1000 meters
          ),
          Workout(
            sessionType: SessionType.recovery,
            goalType: SessionGoalType.time,
            goal: 120, // 2 minutes recovery
          ),
        ],
      ),
      // Cool-down
      SessionModel(
        reps: 1,
        workouts: [
          Workout(
            sessionType: SessionType.recovery,
            goalType: SessionGoalType.time,
            goal: 300, // 5 minutes
          ),
        ],
      ),
    ],
  );

  await _appleWorkoutScheduler.scheduleWorkout(intervalWorkout);
}

API Reference

AppleWorkoutScheduler

Methods

requestAuthorization()

Request HealthKit authorization from the user.

Future<WorkoutAuthentication> requestAuthorization()

Returns: WorkoutAuthentication enum value

getAuthorization()

Get the current HealthKit authorization status.

Future<WorkoutAuthentication> getAuthorization()

Returns: WorkoutAuthentication enum value

scheduleWorkout(ExceriseModel model)

Schedule a workout on Apple Watch.

Future<dynamic> scheduleWorkout(ExceriseModel model)

Parameters:

• model: An ExceriseModel containing workout configuration

Returns: Boolean or dynamic value indicating success

Data Models

ExceriseModel

Represents a complete workout.

ExceriseModel({
  required String title,           // Workout title
  required List<SessionModel> sessions,  // List of workout sessions
  required DateTime date,          // Scheduled date and time
})

SessionModel

Represents a workout session with repetitions.

SessionModel({
  required int reps,              // Number of repetitions
  required List<Workout> workouts, // List of workout segments
})

Workout

Represents an individual workout segment.

Workout({
  required SessionGoalType goalType,    // distance or time
  required SessionType sessionType,     // work or recovery
  required int goal,                    // Goal value
})

Goal units:

• Distance: meters (e.g., 5000 = 5km)
• Time: seconds (e.g., 300 = 5 minutes)

Enums

WorkoutAuthentication

enum WorkoutAuthentication {
  notDetermined,  // User hasn't been asked for authorization yet
  restricted,     // Authorization restricted (parental controls, etc.)
  denied,         // User denied authorization
  authorized,     // Authorization granted
}

SessionType

enum SessionType {
  work,       // Active workout segment
  recovery,   // Recovery/rest segment
}

SessionGoalType

enum SessionGoalType {
  distance,   // Goal measured in meters
  time,       // Goal measured in seconds
}

Example App

Check out the example app for a complete working implementation.

Troubleshooting

Authorization Issues

If authorization is not working:

• Ensure HealthKit capability is enabled in Xcode
• Check that Info.plist contains the required usage descriptions
• Verify device has an Apple Watch paired
• Reset Health app permissions in Settings → Privacy & Security → Health

Workout Not Appearing

If scheduled workouts don't appear on Apple Watch:

• Ensure the Apple Watch is connected and unlocked
• Check that HealthKit sync is enabled
• Verify the scheduled date is in the future
• Restart both iPhone and Apple Watch

Limitations

• iOS only (requires HealthKit)
• Requires paired Apple Watch
• Limited to HealthKit-supported workout types
• Workouts must have valid date in the future or present

Contributing

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

Issues and Feedback

Please file issues, bugs, or feature requests in our issue tracker.

License

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

Author

Created and maintained by the Fitpage team.

Changelog

See CHANGELOG.md for a detailed list of changes.