Save Quantity Sample

Save quantity samples to HealthKit

saveQuantitySample

Save a new quantity sample to HealthKit.

saveQuantitySample(
  identifier: QuantityTypeIdentifierWriteable,
  unit: string,
  value: number,
  start: Date,
  end: Date,
  metadata?: AnyMap
): Promise<QuantitySample | undefined>

identifier · QuantityTypeIdentifierWriteable · required

The quantity type identifier to save. Must be a writeable type (read-only types like 'HKQuantityTypeIdentifierAppleExerciseTime' cannot be written to)

unit · string · required

The unit of measurement for the quantity value (e.g., 'count', 'kg', 'mi', 'IU')

value · number · required

The numeric value of the quantity

start · Date · required

The start date and time for the sample

end · Date · required

The end date and time for the sample. For instantaneous measurements (like weight), this should typically be the same as the start date

metadata · AnyMap

Optional metadata to attach to the sample. Can include both built-in HealthKit metadata keys and custom app-specific data

Show Common metadata keys

HKInsulinDeliveryReason · InsulinDeliveryReason

For insulin delivery samples. Values: InsulinDeliveryReason.basal or InsulinDeliveryReason.bolus

HKBloodGlucoseMealTime · number

Indicates when a blood glucose measurement was taken relative to a meal

HKWasUserEntered · boolean

Whether the data was manually entered by the user

HKExternalUUID · string

A unique identifier from an external system

Returns

sample · QuantitySample | undefined

The saved quantity sample, or undefined if the save failed

Show QuantitySample properties

uuid · string

HealthKit’s unique identifier for the sample

quantityType · QuantityTypeIdentifier

The type of quantity data

quantity · number

The quantity value that was saved

unit · string

The unit of measurement

startDate · Date

When the sample started

endDate · Date

When the sample ended

metadata · AnyMap

The metadata that was saved with the sample

Examples

Save step count

import { saveQuantitySample } from '@kingstinct/react-native-healthkit'

const stepSample = await saveQuantitySample(
  'HKQuantityTypeIdentifierStepCount',
  'count',
  1000,
  new Date('2024-03-15T10:00:00'),
  new Date('2024-03-15T11:00:00')
)

if (stepSample) {
  console.log(`Saved ${stepSample.quantity} steps`)
}

Save weight measurement

import { saveQuantitySample } from '@kingstinct/react-native-healthkit'

const now = new Date()
const weightSample = await saveQuantitySample(
  'HKQuantityTypeIdentifierBodyMass',
  'kg',
  70.5,
  now,
  now, // Same as start for instantaneous measurements
  {
    HKWasUserEntered: true
  }
)

Save insulin delivery with metadata

import { 
  saveQuantitySample, 
  InsulinDeliveryReason 
} from '@kingstinct/react-native-healthkit'

const insulinSample = await saveQuantitySample(
  'HKQuantityTypeIdentifierInsulinDelivery',
  'IU',
  5.5,
  new Date(),
  new Date(),
  {
    HKInsulinDeliveryReason: InsulinDeliveryReason.bolus,
    notes: 'Pre-meal insulin'
  }
)

Save blood glucose with meal context

import { saveQuantitySample } from '@kingstinct/react-native-healthkit'

const glucoseSample = await saveQuantitySample(
  'HKQuantityTypeIdentifierBloodGlucose',
  'mg/dL',
  120,
  new Date(),
  new Date(),
  {
    HKBloodGlucoseMealTime: 1, // Preprandial (before meal)
    HKWasUserEntered: true
  }
)

Make sure you’ve requested write permission for the quantity type using requestAuthorization before calling saveQuantitySample, or the app will crash.

Some quantity types are read-only (like HKQuantityTypeIdentifierAppleExerciseTime) and cannot be saved by third-party apps. These are defined as QuantityTypeIdentifierReadOnly in the type system.

Metadata Keys

HealthKit metadata keys follow a specific naming pattern. In the Apple documentation, they appear with the HKMetadataKey prefix (e.g., HKMetadataKeyExternalUUID), but when serialized, they use the HK prefix (e.g., HKExternalUUID).

Common metadata keys include:

• HKExternalUUID - Unique identifier from external system
• HKWasUserEntered - Boolean indicating manual entry
• HKInsulinDeliveryReason - Reason for insulin delivery (basal/bolus)
• HKBloodGlucoseMealTime - Timing relative to meals
• HKHeartRateMotionContext - Motion context for heart rate

You can also use custom string keys for app-specific metadata.

Unit Compatibility

Use the isQuantityCompatibleWithUnit() helper function to check if a unit is compatible with a quantity type before saving:

import { isQuantityCompatibleWithUnit } from '@kingstinct/react-native-healthkit'

const isCompatible = isQuantityCompatibleWithUnit(
  'HKQuantityTypeIdentifierBodyMass',
  'kg'
)

if (isCompatible) {
  await saveQuantitySample(
    'HKQuantityTypeIdentifierBodyMass',
    'kg',
    70.5,
    new Date(),
    new Date()
  )
}