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

iOS上で最適なワークアウト体験を構築するためのベストプラクティスを紹介します。ワークアウトセッションのライフサイクル、Apple WatchとiPhoneの間のワークアウトの差異、アプリのロック画面の体験を向上させるためのライブアクティビティとSiriの利用方法について学ぶことができます。

リソース

関連ビデオ

WWDC25

HealthKit Medications APIの紹介

WWDC24

App Intentでアプリのコア機能をユーザーに提供

WWDC23

こんにちは HealthKitチームのエンジニア Brianです世の中には健康増進や健康維持を目的としたヘルスアプリやフィットネスアプリは沢山ありますユーザーの許可を得てこれらアプリは HealthKitの一元化された暗号化データベースやパワフルなAPIにアクセスして総合的な健康状態を提供しますワークアウトAPIは HealthKitが提供する最も強力な機能の一つに成長しました本日は iPhoneとiPadで APIを使用する方法をご紹介しますまずワークアウトセッション実行に関する基本事項を説明します次にワークアウト中の測定値へのアクセス方法を詳しく説明します Apple Watchのプロセスとの違いにも注目してみます次にクラッシュが発生した場合の回復方法を紹介します最後にワークアウトのヒントやベストプラクティスを紹介しますワークアウトセッションを始めましょうすでにApple Watchのアプリでワークアウトを実行している場合は iPhoneとiPadでも最小限の変更だけで同じコードを使用できます Apple Watchと同様ワークアウトセッションであらゆるアクティビティをトラッキングし関連付けしたWorkout Builderによる HealthKitへの保存が可能になりました Apple Watchアプリをこれから開発される皆さんのためにワークアウトセッション実行方法の例を簡単に説明しますワークアウトセッションはセットアップから開始、測定値の収集まで複数のステップに分かれ最後にセッション終了ですまずワークアウト構成を作成してユーザーが実行したいと思っているアクティビティを反映させてタイプを設定します「running」を使用して場所を「outdoor」に設定します HKWorkoutSessionを作成して設定を渡します

ワークアウトセッションから関連付けられているビルダーを取得してデータソースをアタッチします

セッションで「prepare」を呼び出し 3秒のカウントダウンを表示してデバイス上のセンサーがオンになるまでまたは外部心拍計を接続するまでの時間を確保しますカウントダウンがあることでワークアウトアクティビティの開始後すぐに測定値が利用可能になりますカウントダウンが完了したらセッションでstartActivityを関連するWorkout Builderで beginCollectionを呼び出すだけですアンカーオブジェクトクエリを使用して UIを更新する必要はありません新しいデータを収集すると Workout Builderデリゲートはアップデートをアプリに提供しワークアウトの保存時には測定値を同期処理します

アプリを使用しているユーザーがワークアウトを終了すると判断した場合はライブビルダーで最終的な測定値を収集できるようセッションでstopActivityを呼び出す必要があります

セッションが停止状態に遷移したらビルダーで「endCollection」を呼び出してワークアウトを終了できますビルダーが完成したらセッションで「end」を呼び出しワークアウトの概要を表示します

ワークアウトの実行方法を一通りご紹介したところで Apple Watchで実行する場合と iPhoneやiPadで実行する場合の違いについて説明します第一の主な違いは利用可能なセンサーです

iPhoneとiPadではすべてのワークアウトアクティビティタイプを利用できますがこれらデバイスには心拍センサーが搭載されていません

ただしウェアラブル心拍モニタや Powerbeats Pro 2などワークアウト中に装着する GATプロファイル対応デバイスとのペアリングは可能です

デバイスをペアリングすると HealthKitは心拍数データをデバイスから取得してサンプルとしてHealth Storeに保存しアプリで利用できる状態にしますつまりワークアウト中に収集したいサンプルとシステムが生成できるサンプルは違っている可能性があるということですその違いを見ていきましょう

先ほど型を生成しましたカロリーや距離などワークアウト中にシステムによって生成されるデータ型です収集される型のほうはリアルタイムで監視してワークアウトサンプルに追加する測定値ですたとえばワークアウト中の水分摂取量を収集する場合アプリはHealthデータベースにサンプルを追加する必要があります

iPhoneやiPadの場合初期化するとデータソースで収集する型には実行中のアクティビティで収集しそうなすべてのサンプルタイプが含まれますたとえば外部心拍センサーがない場合システムで生成しない場合でも心拍数が含まれます

データソースはシステムが生成したものであるかアプリが保存したものかを問わず収集したサンプルとタイプを監視してライブビルダーに渡します

システムが実際に生成しているデータを知りたい場合は UIの測定値更新に使用しているものと同じ Workout Builderデリゲートを使用できます

アプリで収集するデフォルトの型を変更する場合はデータソースで型のメソッドに対して「enable collection」や「disable collection」を呼び出して必要な型の追加や削除ができます

たとえばワークアウト中の水分摂取量を収集するとアプリが Enable Collectionを呼び出しワークアウトの実行中に測定値をサンプルとして Healthデータベースに追加しデータソースはサンプルを自動的にライブビルダーに渡しますセッションの測定値を取得する方法を紹介しましたここでワークアウトの保存後に測定値を読み取る方法を簡単に説明します

まずワークアウトオブジェクトの統計値を使用して概要を表示します

ワークアウト実行中の測定値をグラフにしたい場合は任意の間隔を指定して統計データ収集クエリを使用します

詳細なデータが必要な場合はワークアウトに関連する数量サンプルは粒度が1以上になる場合もあることを忘れないようにしましょうつまりサンプルがより細かい粒度のデータを持っていて HKQuantitySeriesSampleQueryでアクセスできるということです

お気づきでしょうがこれは過去のApple Watch ワークアウトについての話でしたただしこれは iOSに保存されているワークアウトにも当てはまりますここまでアプリの表示中に測定値を収集してワークアウト保存後に読み取る方法を紹介しましたもう1つの重要な相違点ですが Apple Watchとは異なりワークアウト実行中 iPhoneは高い確率でロックされますプライバシー上の理由から通常デバイスのロック中は健康データを利用できませんが心配は要りません 1回目のワークアウトセッションスタート時にシステムはデバイスのロック中もアプリがワークアウトデータを利用できることを示すプロンプトを提示しますアプリでライブアクティビティを表示する絶好の機会です iPhoneのロックを解除することなく最も重要な測定値をロック画面に表示して最新情報をリアルタイムで確認できるようになります先ほどプライバシープロンプトについてお話ししましたデータにアクセスできない場合やデバイスがロックされているとき心拍数データが利用できない場合は UIを更新して測定値を非表示にしワークアウトの時間だけを表示させることができます

ロック画面からできることは他にもありますロック画面もSiri対応になったことを嬉しく思います iPhoneのロックを解除しなくともワークアウトの開始、一時停止、再開とキャンセルが可能になりましたロックが解除されると HealthKitがワークアウトを保存して Health Store経由でアプリが利用できるようにします Siri Intentをアプリに追加してロック画面からでも機能させる方法を説明します

まず Intentハンドラの定義からスタートしますロック画面でも機能させるにはアプリ内部からの処理が必要です次にサポートするIntentを定義します読みやすくするためにこの例では分割しています次に引数として渡されるIntentですこの例では StartWorkoutIntentですまず実行中のワークアウトについて確認しワークアウトがある場合は「failure」を返します次にアクティビティ型と場所を取得する必要がありますこの例では屋外でのランニングに設定します成功レスポンスを返します

Intentを定義したら応答できるように Appデリゲートを作成する必要があります次にアプリ内のデリゲートを定義します

これでアプリがロック画面での Siri Workout Intentに対応します

Siri Intentとライブアクティビティを追加しておくとデバイスの状態に左右されることなくユーザーがアプリを最大限に活用できるようになりますこれら2つの技術の詳細については WWDC2024の「Bring your app's core features to users with App Intents」と WWDC23の「Meet ActivityKit」をご覧くださいセッションの測定値を取得する方法とライブアクティビティで Siri Intentの使用方法が分かったところで Crash Recoveryに進みましょう Crash Recoveryは以前から Watchにあった機能ですが重要なポイントを3つ確認しておきましょうクラッシュ発生時システムは自動的にアプリを再起動させます Builderのワークアウトセッションは再起動前の状態に戻りますただしライブデータソースの設定はやり直しが必要になります iPhoneとiPad用に新しくセッション中のワークアウトの回復に使用するシーンデリゲートを追加しました

Siriインテント用に作成したアプリデリゲートを使用してクラッシュからのリカバリ処理用のシーンデリゲートを追加できますその場合は Appデリゲートを定義して optionsパラメータが shouldHandleActiveWorkoutRecovery とあるか確認します次に復元された recoveredSessionを Health Storeから受け取って WorkoutManagerに渡すよう指定します WorkoutManagerからアクティブなワークアウトを継続するよう処理できますそう後はdataSourceを作成し直すだけです

最後になりますがワークアウトのベストプラクティスをご紹介します測定値をすべて取得できるよう Watchアプリがあればそこでワークアウトを開始するようにします Health StoreからStart Watch Appを呼び出すだけですその後は必ずワークアウトを iPhoneにミラーリングします WWDC2023の「Build a multi-device workout app」で詳しく紹介しています

承認リクエストは必要なデータ型についてのみ実行させるようにしますアプリの本質とは無関係に見えるデータ型で承認を要求してユーザーに疑念を持たせてしまうのは得策ではありません最後にワークアウトの作成と保存には Workout Builder APIを使用するようにしますこれでアクティビティリングが適切に更新されるようになります

以上が iPhoneやiPadでの HealthKitによるワークアウトのトラッキング方法ですアップデートを機にこれらデバイス用の堅牢なAPIが搭載されクラッシュからのリカバリ機能とワークアウト表示の管理機能が加わりデバイスのロック中も操作できますここでお願いがあります本セッション用のデモアプリは是非ともダウンロードをお願いします本日紹介したすべてのコードの機能をすぐに試していただけるようラップされていますすでにiPhoneまたはiPad用のアプリを構築されている場合は本日紹介した Workout Builder APIへのアップグレードを強くお勧めします改善ポイントを気に入っていただけると思います Apple Watch用のアプリを構築されている場合は同じAPIでマルチプラットフォームに対応することで非Apple Watchユーザー向けのまったく新しい市場が開けてきます最後に実装した機能はフィードバックから生まれました皆さんからの引き続きのご提供を心よりお待ちしています世界を健康的にするためのアプリ構築に必要な機能を提供してこれからも皆さんをサポートしますご視聴ありがとうございました

1:30 - Set up workout session

// Set up workout session

// Create workout configuration
let configuration = HKWorkoutConfiguration()
configuration.activityType = .running
configuration.locationType = .outdoor

// Create workout session
let session = try HKWorkoutSession(healthStore: healthStore, configuration: configuration)
session.delegate = self

// Get associated workout builder and add data source
let builder = session.associatedWorkoutBuilder()
builder.delegate = self
builder.dataSource = HKLiveWorkoutDataSource(healthStore: healthStore,
                                             workoutConfiguration: configuration)

1:54 - Starting the session

// Prepare and start session

session.prepare()

// Start and display count down

// Start session and builder collection once count down finishes
session.startActivity(with: startDate)
try await builder.beginCollection(at: startDate)

2:14 - Handling Metrics

// Handling collected metrics

func workoutBuilder(_ workoutBuilder: HKLiveWorkoutBuilder, 
                    didCollectDataOf collectedTypes: Set<HKSampleType>) {
    for type in collectedTypes {
        guard let quantityType = type as? HKQuantityType else { return }

        let statistics = workoutBuilder.statistics(for: quantityType)

        // Update the published values
        updateForStatistics(statistics)
    }
}

2:28 - Ending workout

// Stopping the workout session

session.stopActivity(with: .now)

// Session transitions to stopped then call end
func workoutSession(_ workoutSession: HKWorkoutSession,
                    didChangeTo toState: HKWorkoutSessionState,
                    from fromState: HKWorkoutSessionState,
                    date: Date) {
    guard change.newState == .stopped, let builder else { return }
     
    try await builder.endCollection(at: change.date)
    let finishedWorkout = try await builder.finishWorkout()
    session.end()
}

7:17 - Set up Siri Intent

// Create an INExtension within your main app

// Define an intent handler
public class IntentHandler: INExtension {

}

// Define the intents to support
extension IntentHandler: INStartWorkoutIntentHandling

extension IntentHandler: INPauseWorkoutIntentHandling

extension IntentHandler: INResumeWorkoutIntentHandling

extension IntentHandler: INEndWorkoutIntentHandling

7:32 - Handle the Siri intent

// Handle the intent

public func handle(intent: INStartWorkoutIntent) async -> INStartWorkoutIntentResponse {
    let state = await WorkoutManager.shared.state
        
    switch state {
    case .running, .paused, .prepared, .stopped:
        return INStartWorkoutIntentResponse(code: .failureOngoingWorkout, 
                                            userActivity: nil)
    default:
        break;
    }
    Task {
        await MainActor.run {
            // Handle the intents activity type and location
            WorkoutManager.shared.setWorkoutConfiguration(activityType: .running,   
                                                          location: .outdoor)
        }
    }
    return INStartWorkoutIntentResponse(code: .success, userActivity: nil)
 }

7:52 - App Delegate

// Implement an app delegate

// Create app delegate
class WorkoutsOniOSSampleAppDelegate: NSObject, UIApplicationDelegate {
    let handler = IntentHandler()

    func application(_ application: UIApplication, handlerFor intent: INIntent) -> Any? {
        return handler
    }
}

// Add app delegate to app
struct WorkoutsOniOSSampleApp: App {
    @UIApplicationDelegateAdaptor(WorkoutsOniOSSampleAppDelegate.self) var appDelegate

}

9:09 - Set up crash recovery

// App Delegate

func application(_ application: UIApplication,
                 configurationForConnecting connectingSceneSession: UISceneSession,
                 options: UIScene.ConnectionOptions) -> UISceneConfiguration {
    if options.shouldHandleActiveWorkoutRecovery {
        let store = HKHealthStore()
        store.recoverActiveWorkoutSession(completion: { (workoutSession, error) in
            // Handle error
            Task {
                await WorkoutManager.shared.recoverWorkout(recoveredSession: workoutSession)
            }
        })
    }
    let configuration = UISceneConfiguration(name: "Default Configuration", 
                                             sessionRole: connectingSceneSession.role)
    configuration.delegateClass = WorkoutsOniOSSampleAppSceneDelegate.self
    return configuration
}

9:25 - Recover the workout session

// Recover the workout for the session


func recoverWorkout(recoveredSession: HKWorkoutSession) {
    session = recoveredSession
    builder = recoveredSession.associatedWorkoutBuilder()
    session?.delegate = self
    builder?.delegate = self
    workoutConfiguration = recoveredSession.workoutConfiguration

    let dataSource = HKLiveWorkoutDataSource(healthStore: healthStore,                                                                  
                                             workoutConfiguration: workoutConfiguration)
    builder?.dataSource = dataSource
}

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

関連する章

リソース

関連ビデオ

WWDC25

WWDC24

WWDC23