diff --git a/README.md b/README.md index a5728a6..424708c 100644 --- a/README.md +++ b/README.md @@ -34,12 +34,15 @@ You need to add the Spezi HealthKit Swift package to ### Example Before you configure the ``HealthKit`` module, make sure your `Standard` in your Spezi Application conforms to the ``HealthKitConstraint`` protocol to receive HealthKit data. +The [`add(sample:)`](https://swiftpackageindex.com/stanfordspezi/spezihealthkit/documentation/spezihealthkit/healthkitconstraint/add(sample:)) function is triggered once for every newly collected HealthKit sample, and the [`remove(sample:)`](https://swiftpackageindex.com/stanfordspezi/spezihealthkit/documentation/spezihealthkit/healthkitconstraint/remove(sample:)) function ```swift actor ExampleStandard: Standard, HealthKitConstraint { + // Add the newly collected HKSample to your application. func add(sample: HKSample) async { // ... } + // Remove the deleted HKSample from your application. func remove(sample: HKDeletedObject) { // ... } diff --git a/Sources/SpeziHealthKit/CollectSample/CollectSample.swift b/Sources/SpeziHealthKit/CollectSample/CollectSample.swift index 3649ebc..f9321b1 100644 --- a/Sources/SpeziHealthKit/CollectSample/CollectSample.swift +++ b/Sources/SpeziHealthKit/CollectSample/CollectSample.swift @@ -11,6 +11,38 @@ import Spezi /// Collects a specified `HKSampleType` in the ``HealthKit`` module. +/// +/// This structure define what and how the ``HealthKit`` samples are collected. By default, all samples of the provided `HKSampleType` will be collected. The collection starts on calling ``HealthKit/triggerDataSourceCollection()`` if you configure the `deliverySetting` as ``HealthKitDeliverySetting/manual(safeAnchor:)`` or automatic once the application is launched when you configure anything else than manual, i.e. ``HealthKitDeliverySetting/anchorQuery(_:saveAnchor:)`` or ``HealthKitDeliverySetting/background(_:saveAnchor:)``. +/// +/// Your can filter the HealthKit samples to collect by specifying the `predicate`. For example, you can define an `NSPredicate` to only collect the data collected at a time within the given start and end date. Below is an example to create a `NSPredicate` restricting the data collected in the previous month. +/// ```swift +/// private var predicateOneMonth: NSPredicate { +/// // Define the start and end time for the predicate. In this example, +/// // we want to collect the samples in the previous month. +/// let calendar = Calendar(identifier: .gregorian) +/// let today = calendar.startOfDay(for: Date()) +/// // We want the end date to be tomorrow so that we can collect all the samples today. +/// guard let endDate = calendar.date(byAdding: .day, value: 1, to: today) else { +/// fatalError("*** Unable to calculate the end time ***") +/// } +/// // Define the start date to one month before. +/// guard let startDate = calendar.date(byAdding: .month, value: -1, to: today) else { +/// fatalError("*** Unable to calculate the start time ***") +/// } +/// // Initialize the NSPredicate with our start and end dates. +/// return HKQuery.predicateForSamples(withStart: startDate, end: endDate) +/// } +/// ``` +/// +/// Then, you just need to configure `predicate` with the `predicateOneMonth` you defined as above during your initialization of ``CollectSample`` to only collect data samples in the previous month. +/// +/// ```swift +/// CollectSample( +/// HKQuantityType(.stepCount), +/// predicate: predicateOneMonth, +/// deliverySetting: .background(.afterAuthorizationAndApplicationWillLaunch) +/// ) +/// ``` public struct CollectSample: HealthKitDataSourceDescription { private let collectSamples: CollectSamples diff --git a/Sources/SpeziHealthKit/HealthKit.swift b/Sources/SpeziHealthKit/HealthKit.swift index f81d7be..85ef935 100644 --- a/Sources/SpeziHealthKit/HealthKit.swift +++ b/Sources/SpeziHealthKit/HealthKit.swift @@ -16,12 +16,15 @@ import SwiftUI /// The `HealthKit` module simplifies access to HealthKit samples ranging from single, anchored, and background queries. /// /// Before you configure the ``HealthKit`` module, make sure your `Standard` in your Spezi Application conforms to the ``HealthKitConstraint`` protocol to receive HealthKit data. +/// The ``HealthKitConstraint/add(sample:)`` function is triggered once for every newly collected HealthKit sample, and the ``HealthKitConstraint/remove(sample:)`` function is triggered once for every deleted HealthKit sample. /// ```swift /// actor ExampleStandard: Standard, HealthKitConstraint { +/// // Add the newly collected HKSample to your application. /// func add(sample: HKSample) async { /// ... /// } -/// +/// +/// // Remove the deleted HKSample from your application. /// func remove(sample: HKDeletedObject) { /// ... /// } diff --git a/Sources/SpeziHealthKit/HealthKitConstraint.swift b/Sources/SpeziHealthKit/HealthKitConstraint.swift index 7420c13..bccb9c5 100644 --- a/Sources/SpeziHealthKit/HealthKitConstraint.swift +++ b/Sources/SpeziHealthKit/HealthKitConstraint.swift @@ -15,12 +15,15 @@ import Spezi /// /// Make sure that your standard in your Spezi Application conforms to the ``HealthKitConstraint`` /// protocol to receive HealthKit data. +/// The ``HealthKitConstraint/add(sample:)`` function is triggered once for every newly collected HealthKit sample, and the ``HealthKitConstraint/remove(sample:)`` function is triggered once for every deleted HealthKit sample. /// ```swift /// actor ExampleStandard: Standard, HealthKitConstraint { +/// // Add the newly collected HKSample to your application. /// func add(sample: HKSample) async { /// ... /// } -/// +/// +/// // Remove the deleted HKSample from your application. /// func remove(sample: HKDeletedObject) { /// ... /// } diff --git a/Sources/SpeziHealthKit/SpeziHealthKit.docc/SpeziHealthKit.md b/Sources/SpeziHealthKit/SpeziHealthKit.docc/SpeziHealthKit.md index 248fa33..f61dcec 100644 --- a/Sources/SpeziHealthKit/SpeziHealthKit.docc/SpeziHealthKit.md +++ b/Sources/SpeziHealthKit/SpeziHealthKit.docc/SpeziHealthKit.md @@ -27,13 +27,15 @@ You need to add the Spezi HealthKit Swift package to ### Example -Before you configure the ``HealthKit`` module, make sure your `Standard` in your Spezi Application conforms to the ``HealthKitConstraint`` protocol to receive HealthKit data. +Before you configure the ``HealthKit`` module, make sure your `Standard` in your Spezi Application conforms to the ``HealthKitConstraint`` protocol to receive HealthKit data. The ``HealthKitConstraint/add(sample:)`` function is triggered once for every newly collected HealthKit sample, and the ``HealthKitConstraint/remove(sample:)`` function is triggered once for every deleted HealthKit sample. ```swift actor ExampleStandard: Standard, HealthKitConstraint { + // Add the newly collected HKSample to your application. func add(sample: HKSample) async { // ... } + // Remove the deleted HKSample from your application. func remove(sample: HKDeletedObject) { // ... }