Save Workout Sample

Save a workout sample to HealthKit with associated quantity samples and metadata

saveWorkoutSample

Save a workout sample to HealthKit. You can associate quantity samples (like heart rate, distance) with the workout and include metadata.

Signature

function saveWorkoutSample(
  workoutActivityType: WorkoutActivityType,
  quantities: readonly QuantitySampleForSaving[],
  startDate: Date,
  endDate: Date,
  totals?: WorkoutTotals,
  metadata?: AnyMap
): Promise<WorkoutProxy>

Parameters

workoutActivityType · WorkoutActivityType · required

The type of workout activity (e.g., running, cycling, swimming). See WorkoutActivityType enum for all available types.

quantities · QuantitySampleForSaving[] · required

Array of quantity samples to associate with the workout (e.g., heart rate readings, GPS locations as active energy burned). Each sample should fall within the workout’s time range.

Show QuantitySampleForSaving properties

quantityType · QuantityTypeIdentifier · required

The type of quantity (e.g., ‘HKQuantityTypeIdentifierHeartRate’)

quantity · number · required

The numeric value

unit · string · required

The unit for the quantity (e.g., ‘count/min’ for heart rate)

startDate · Date · required

When the sample started

endDate · Date · required

When the sample ended

metadata · AnyMap

Optional metadata for the quantity sample

startDate · Date · required

When the workout started

endDate · Date · required

When the workout ended

totals · WorkoutTotals

Optional totals for the workout

Show properties

distance · number

Total distance in meters

energyBurned · number

Total energy burned in kilocalories

metadata · AnyMap

Optional metadata for the workout. Common keys include:

• HKMetadataKeyIndoorWorkout (boolean)
• HKMetadataKeyAverageSpeed (number)
• HKMetadataKeyMaximumSpeed (number)
• HKMetadataKeyElevationAscended (number)
• HKMetadataKeyElevationDescended (number)

Returns

workout · Promise<WorkoutProxy>

The saved workout as a WorkoutProxy object, which provides access to workout data and methods for adding routes or querying statistics.

Example

import { saveWorkoutSample, WorkoutActivityType } from '@kingstinct/react-native-healthkit'

const startDate = new Date('2024-03-01T08:00:00')
const endDate = new Date('2024-03-01T08:30:00')

// Heart rate samples during the workout
const heartRateSamples = [
  {
    quantityType: 'HKQuantityTypeIdentifierHeartRate',
    quantity: 145,
    unit: 'count/min',
    startDate: new Date('2024-03-01T08:05:00'),
    endDate: new Date('2024-03-01T08:05:00'),
  },
  {
    quantityType: 'HKQuantityTypeIdentifierHeartRate',
    quantity: 152,
    unit: 'count/min',
    startDate: new Date('2024-03-01T08:15:00'),
    endDate: new Date('2024-03-01T08:15:00'),
  },
  {
    quantityType: 'HKQuantityTypeIdentifierHeartRate',
    quantity: 138,
    unit: 'count/min',
    startDate: new Date('2024-03-01T08:25:00'),
    endDate: new Date('2024-03-01T08:25:00'),
  },
]

// Save a running workout
const workout = await saveWorkoutSample(
  WorkoutActivityType.running,
  heartRateSamples,
  startDate,
  endDate,
  {
    distance: 5000, // 5 km in meters
    energyBurned: 350, // 350 kcal
  },
  {
    HKMetadataKeyIndoorWorkout: false,
    HKMetadataKeyAverageSpeed: 2.78, // m/s (10 km/h)
    HKMetadataKeyElevationAscended: 50, // meters
  }
)

console.log('Workout saved:', {
  uuid: workout.uuid,
  duration: workout.duration,
  distance: workout.totalDistance,
})

// You can also save a workout route after saving the workout
const locations = [
  {
    latitude: 37.7749,
    longitude: -122.4194,
    altitude: 10,
    course: 0,
    speed: 2.5,
    horizontalAccuracy: 5,
    verticalAccuracy: 5,
    date: new Date('2024-03-01T08:00:00'),
  },
  // ... more locations
]

await workout.saveWorkoutRoute(locations)

You must request write authorization for HKWorkoutTypeIdentifier and any quantity types you want to save before calling this function.

To add a GPS route to your workout, use the saveWorkoutRoute method on the returned WorkoutProxy object. See Workout Routes for more details.