iOSとiPadOSでのHealthKitによるワークアウトのトラッキング

Hello and welcome, my name is Brian and I’m an engineer on the HealthKit team. There are hundreds of health and fitness apps that help people get healthy and stay healthy. And with your permission, they have access to HealthKit’s centralized encrypted database and a set of powerful APIs to provide you a comprehensive view of your health. Now the workout APIs are some of the most powerful that HealthKit provides. And I’m excited to show you how to use these APIs on iPhone and iPad. I’ll begin by covering the basics of running a workout session. Then, I’ll dive into how to access health metrics during a workout with the focus on how the process differs from that on Apple Watch.

I’ll then show you how to recover in the event of a crash and I’ll wrap it up with some workout tips and best practices. Let's get this workout session started.

If you’re already running workouts in an app on Apple Watch, you’ll be able to use the same code on iPhone and iPad with only minimal changes. Just like on Apple Watch, you can now use a workout session to track any activity and use the associated workout builder to save the workout in HealthKit. Now, since you may not already have an app on Apple Watch, let me quickly run through an example of how to run a workout session.

A workout session has several steps from setup and start to collecting health metrics and finally ending the session. To begin, you first need to create a workout configuration and set its type to reflect the activity the person will perform. I’ll use running and set the location to outdoor.

You then create an HKWorkoutSession passing in the configuration.

From the workout session, you’ll get the associated builder and attach a data source.

Then call prepare on the session and display a three second countdown to allow time for on-device sensors to turn on or an external heart rate monitor to connect. This countdown ensures that you have metrics available as soon as the workout activity starts.

Once the countdown completes, simply call startActivity on the session and beginCollection on the associated workout builder. There isn’t a need to use an anchored object query to update your UI. The workout builders delegate provides your app convenient updates when new data has been collected and handles keeping the metrics in sync when the workout is saved.

When the person using your app decides to end the workout, you should call stopActivity on the session to allow the final metrics to be collected by your live builder.

Once this session has transitioned to the stop state, you can call endCollection on the builder and finish the workout. After the builder has finished, call end on the session and display the workout summary.

Alright, now that you’re familiar with how to run a workout, let me go through some of the differences between running a workout on Apple Watch and running a workout on iPhone or iPad. One key difference are the available sensors.

While all workout activity types are available on iPhone and iPad, these devices don’t contain a heart rate sensor.

But you can pair them with any device that you wear during a workout that supports the heart rate GAT profile, like a wearable heart rate monitor or the Powerbeats Pro 2.

Once a device is paired, HealthKit will handle getting heart rate data from the device and saving it as samples to the Health Store, making it available to your app.

This means there may be a difference in the samples you want to collect for your workout and the samples that the system can generate. Let's go over that difference.

We have generated types. These are the data types generated by the system during a workout activity like calories and distance.

And collected types, with these being the metrics you want to observe live and add to your workout sample.

For example, if your app wants to collect water consumed during a workout, then your app will need to add the samples to the health database.

On iPhone and iPad, on initialization, the types to collect properly on the data source will contain all possible sample types we want to collect for the current activity.

For example, heart rate will be included even though it might not be generated by the system unless you have an external heart rate sensor.

The data source will observe for all samples and types to collect either generated by the system or saved by your app and pass them to the live builder.

If you want to know what the system is actually generating, you can use the same Workout Builder delegate you are using to update the metrics in your UI.

If your app wants to modify the default types to collect, you can call enable or disable collection for type methods on the data source to add or remove the types you want.

For example, collecting dietary water during a workout, your app will call Enable Collection and as the workout is running, add the measurement as a sample to the health database and the data source will automatically pass those samples to your live builder.

Now that you know how to get metrics in session, let’s take a quick pause and quickly cover how to read workout metrics after the workout has been saved.

Start by using statistics on the workout object to display a summary.

If you want to chart metrics over the duration of the workout, you will want to use a statistics collection query with your desired interval.

If your app does need fine grain data, keep in mind that quantity samples associated with the workout may have a count greater than one.

This indicates that samples have finer grain data which can be accessed by using an HKQuantitySeriesSampleQuery instead.

You may have noticed that this is the case when looking at historical Apple Watch workouts, and this will also be the case with workouts saved in iOS.

Great, now you know how to collect metrics while your app is in the foreground and read them after the workout has been saved. Another key difference is that unlike Apple Watch, your iPhone will most likely lock while a workout is running. For privacy reasons, health data is not normally available while a device is locked, but never fear. The first time a workout session is started, the system will show a prompt indicating that workout data will be available to your app, even while the device is locked. And this is a great opportunity for your app to show a live activity with your most crucial metrics on the lock screen, allowing you to show live updates right from the lock screen without the user having to unlock their phone.

But remember that privacy prompt I just mentioned? You may want to update your UI to omit metrics and just show the workout duration if you don’t have access to data when the device is locked or if heart rate data is unavailable, not showing the metric at all.

But that is not all you can do from the lock screen. We are excited to bring Siri support to the lock screen. You will now be able to start, pause, resume, and cancel a workout without ever having to unlock your phone. Once the phone is unlocked, HealthKit will save the workout and make it available to your app via the Health Store. Let me go over how to add a Siri intent to your app that works from the lock screen.

You first start by defining your Intent Handler. This must be handled from inside your app to work on the lock screen. Then, you’ll want to define the intents you want to support. I've broken them out in this example to make them easier to read.

Next you will handle the incoming intent. Here I’ve received a StartWorkoutIntent.

You start by first checking if there is a running workout and return a failure if there is. Next you need to get the activity type and location. For this example, I’ll just set it to an outdoor run. After which you return a success response.

Now that you have intents defined, you need to create an app delegate to respond to them.

You will then define the delegate in your app.

And with that, your app now supports Siri workout intents from the lock screen.

Adding Siri intents and live activities will ensure that the people using your app will get the most out of your app, regardless of the lock state of the device. For details on both these technologies, check out “Bring your app’s core features to users with App intents” from WWDC24, and “Meet ActivityKit” from WWDC23.

Now that you know how to get metrics in session and how to use Siri intents in live activities, let’s move on to Crash recovery.

Crash Recovery has been available on Watch for a while, but let me go over three key points. The system will automatically relaunch your app in case of a crash.

The workout session in Builder will be restored in their previous state. However, you’ll need to set up your live data source again. For iPhone and iPad, we’ve added a new scene delegate you’ll use to recover your in-session workout.

You can use the app delegate you created for Siri intents to add a scene delegate to handle crash recovery.

We’ll start by defining our App Delegate and check if the options parameter indicates we shouldHandleActiveWorkoutRecovery.

Now we’ll grab the recovered workoutSession from Health Store, making sure to pass the recoveredSession to your WorkoutManager. From your WorkoutManager, you can handle continuing the active workout. And if you remember, we only need to recreate our dataSource.

Finally, let me go over some best practices for workouts.

If you have a Watch app, be sure to start the workout there to get all available metrics. Just call Start Watch App from the Health Store.

And once you have, be sure to mirror the workout to the iPhone. Check out “Build a multi-device workout app” from WWDC 23 to learn how.

Your app should only request for authorization for data types you need. You don’t want your users wondering why you’re asking for authorization for data types that seem unrelated to the focus of your app.

And finally, always use the workout builder API to create and save a workout. This will ensure that activity rings are appropriately updated.

So that’s how to track workouts with HealthKit on iPhone and iPad. With this update, these devices now have a robust API with crash recovery and the ability to display and manage workouts even when the screen is locked. Here are some next steps before I go. Be sure to download the demo app attached to this session. It has all the code I shared today wrapped into a fully functional example you can use to get started.

If you already have an app on iPhone or iPad, make sure to upgrade to the Workout Builder APIs I covered today. I think you’ll find them a welcome improvement.

If you already have an app for Apple Watch, multi-platform support for the same API means your app has a whole new market for those without an Apple Watch.

And finally, many of the features we implement are a direct result of your feedback, so keep it coming.

We want to support the features you need to keep building those amazing apps to keep the world healthy. Thank you for watching.