Seguimiento de los entrenamientos con HealthKit en iOS y iPadOS

Seguimiento de los entrenamientos con HealthKit en iOS y iPadOS

Descubre las prácticas recomendadas que te permitirán crear una experiencia de entrenamiento fantástica para iOS. Revisa el ciclo de vida de una sesión de entrenamiento, explora las diferencias entre los entrenamientos en el Apple Watch y el iPhone, y descubre cómo usar Actividades en Vivo y Siri para mejorar la experiencia de la pantalla bloqueada de la app.

Capítulos
- 0:00 - Introducción
- 0:56 - Iniciar una sesión de entrenamiento
- 2:50 - Obtener métricas de sesión
- 8:35 - Recuperarse de un accidente
- 9:34 - Prácticas recomendadas
Recursos
Videos relacionados

WWDC25
- Conoce la HealthKit Medications API
WWDC24
- Bring your app’s core features to users with App Intents
WWDC23
- Build a multi-device workout app
- Meet ActivityKit
Hola, mi nombre es Brian, soy ingeniero del equipo de HealthKit. Hay cientos de apps de salud y fitness que ayudan a las personas a estar sanas. Y con tu permiso, tienen acceso a la base de datos encriptada y centralizada de HealthKit y a un conjunto de API potentes para brindarte una visión integral de tu salud. Ahora, las API de entrenamiento son algunas de las más potentes que ofrece HealthKit. Estoy feliz de mostrarles cómo usar estas API en el iPhone y el iPad. Empezaré por lo básico de cómo ejecutar una sesión de entrenamiento. Luego explicaré cómo acceder a las métricas de salud durante un entrenamiento y cómo el proceso difiere del de Apple Watch. Te mostraré cómo recuperarte en caso de un accidente. Finalizaré con algunos consejos de entrenamiento y prácticas recomendadas. Comencemos esta sesión de entrenamiento. Si ya estás ejecutando entrenamientos en una app en el Apple Watch, podrás usar el mismo código en el iPhone y el iPad con solo unos cambios mínimos. Al igual que en el Apple Watch, ahora puedes usar una sesión de entrenamiento para rastrear cualquier actividad y el creador asociado para guardarla en HealthKit. Pero como es posible que aún no tengas una app en el Apple Watch, te mostraré rápidamente cómo ejecutar una sesión de entrenamiento. Una sesión tiene varios pasos desde la configuración y el inicio hasta la recopilación de métricas de salud y, por último, la finalización. Para empezar, debes crear una configuración de entrenamiento y establecer su tipo según la actividad que hará la persona. Usaré correr y estableceré la ubicación al aire libre. Luego crea una HKWorkoutSession pasando la configuración.
Desde la sesión de entrenamiento, obtendrás el creador asociado y adjuntarás una fuente de datos.
Luego, invoca prepare en la sesión y muestra una cuenta regresiva de 3 segundos para que se activen los sensores o se conecte un monitor de frecuencia cardíaca externo. Esta cuenta regresiva garantiza que tengas métricas disponibles cuando empiece la actividad. Una vez que se complete la cuenta regresiva, invoca startActivity en la sesión y beginCollection en el creador de entrenamiento asociado. No es necesario usar una consulta de objeto anclado para actualizar tu IU. El delegado del creador de entrenamiento brinda a tu app actualizaciones útiles al recopilar nuevos datos y mantiene las métricas sincronizadas al guardar el entrenamiento.
Cuando la persona que usa tu app decide finalizar el entrenamiento, debes invocar stopActivity en la sesión para que el creador en vivo recopile las métricas finales.
Una vez que esta sesión pase al estado de detención, puedes invocar endCollection en el creador y finalizar el entrenamiento. Cuando el creador termine, invoca end en la sesión y muestra el resumen del entrenamiento.
Bien, ahora que sabes cómo ejecutar un entrenamiento, repasemos algunas de las diferencias entre ejecutar un entrenamiento en el Apple Watch y hacerlo en el iPhone o el iPad. Una diferencia clave son los sensores disponibles.
Si bien todos los tipos de entrenamiento están en el iPhone y el iPad, estos dispositivos no incluyen sensor de frecuencia cardíaca.
Pero puedes enlazarlos con cualquier dispositivo que uses que admita el perfil de frecuencia cardíaca GAT, como un monitor portátil o los Powerbeats Pro 2.
Una vez enlazado un dispositivo, HealthKit obtendrá los datos de frecuencia cardíaca y los guardará como muestras en Health Store, donde estarán disponibles para tu app. Esto significa que puede haber una diferencia entre las muestras que deseas obtener para tu entrenamiento y las que el sistema puede generar. Repasemos esa diferencia.
Tenemos tipos generados. Estos son los tipos de datos generados por el sistema durante un entrenamiento, como calorías y distancia. Y los tipos recopilados, que son las métricas que quieres ver en tiempo real y agregar a tu muestra de entrenamiento. Por ejemplo, si tu app quiere recopilar el agua consumida durante un entrenamiento, deberá agregar las muestras a la base de datos de salud.
En el iPhone y el iPad, durante la inicialización, los tipos que se recopilan en la fuente de datos incluirán todos los tipos de muestra que queremos recopilar para la actividad actual. Por ejemplo, se incluirá la frecuencia cardíaca aunque no la genere el sistema, a menos que tengas un sensor de frecuencia cardíaca externo.
La fuente de datos buscará todos los tipos y muestras que se recopilarán, ya sean generados por el sistema o guardados por tu app, y los pasará al creador en vivo.
Si quieres saber qué está generando el sistema, puedes usar el mismo delegado del Creador de entrenamiento que usas para actualizar las métricas en tu IU.
Si tu app quiere modificar los tipos predeterminados que se recopilan, puedes invocar los métodos habilitar o deshabilitar en la fuente de datos para agregar o quitar los que necesites.
Por ejemplo, si registras el agua ingerida durante un entrenamiento, la app invocará Enable Collection y, mientras se ejecuta el entrenamiento, agregará la medición como muestra en la base de datos de salud. La fuente de datos enviará esas muestras a tu creador en vivo. Ahora que ya sabes cómo obtener métricas en una sesión, hagamos una breve pausa y veamos cómo leer las métricas del entrenamiento después de haberlo guardado.
Comienza con las estadísticas del objeto de entrenamiento para mostrar un resumen.
Si quieres graficar métricas durante el entrenamiento, usa una consulta de recopilación de estadísticas con el intervalo que prefieras.
Si tu app necesita datos muy detallados, ten en cuenta que las muestras de cantidad asociadas con el entrenamiento pueden tener un recuento mayor que uno. Esto indica que las muestras tienen datos más detallados a los que se puede acceder usando HKQuantitySeriesSampleQuery.
Quizá hayas notado que este es el caso cuando miras los entrenamientos históricos del Apple Watch, y también será el caso con los entrenamientos guardados en iOS. Genial, ahora ya sabes cómo recopilar métricas mientras tu app está en primer plano y puedes leerlas después de guardar el entrenamiento. Otra diferencia clave es que, a diferencia del Apple Watch, es muy probable que tu iPhone se bloquee durante un entrenamiento. Por razones de privacidad, los datos de salud no suelen estar disponibles mientras un dispositivo está bloqueado. La primera vez que se inicia un entrenamiento, el sistema mostrará un aviso de que los datos estarán disponibles en tu app, incluso con el dispositivo bloqueado. Es una gran oportunidad para que tu app muestre una actividad en vivo con tus métricas clave en la pantalla de bloqueo, lo que permite mostrar actualizaciones en vivo sin que el usuario tenga que desbloquear el teléfono. ¿Pero recuerdas ese aviso de privacidad que mencioné? Puedes actualizar la IU para omitir métricas y mostrar solo la duración del entrenamiento si no tienes acceso a los datos con el dispositivo bloqueado o si no hay datos de frecuencia cardíaca, sin mostrar esa métrica.
No es todo lo que puedes hacer desde la pantalla de bloqueo. Incorporamos la compatibilidad de Siri a la pantalla de bloqueo. Ahora podrás iniciar, pausar, reanudar y cancelar un entrenamiento sin tener que desbloquear el teléfono. Una vez que el teléfono esté desbloqueado, HealthKit guardará el entrenamiento, disponible en tu app desde Health Store. Te explicaré cómo agregar a la app una acción de Siri que funcione desde la pantalla de bloqueo.
Comienza por definir tu IntentHandler. Esto debe hacerse desde la app para que funcione en la pantalla de bloqueo. Luego, podrás definir las acciones que quieres admitir. Las desglosé en este ejemplo para que sean más fáciles de leer. Luego, administrarás la acción entrante. Aquí recibí un StartWorkoutIntent. Primero, verifica si hay un entrenamiento en curso y devuelve un error si es así. Luego, debes obtener el tipo de actividad y la ubicación. Para este ejemplo, lo configuraré para que sea al aire libre. Después de eso, devuelve una respuesta correcta.
Ahora que tienes las acciones definidas, crea un delegado de app para responder a ellas. Luego definirás el delegado en tu app.
Con eso, tu app admite las acciones de entrenamiento de Siri desde la pantalla de bloqueo.
Agregar acciones de Siri y actividades en vivo garantizará que las personas que usan tu app la aprovechen al máximo, sin importar el estado de bloqueo del dispositivo. Para conocer detalles sobre ambas tecnologías, consulta “Bring your app’s core features to users with App intents” de la WWDC24 y “Meet ActivityKit” de la WWDC23. Ahora que ya sabes cómo obtener métricas en la sesión y cómo usar las acciones de Siri en actividades en vivo, pasemos a la recuperación de fallas. La recuperación de fallas ya está disponible en el Apple Watch, ahora repasemos tres puntos clave. El sistema reiniciará automáticamente la app en caso de falla. La sesión de entrenamiento y el generador volverán a su estado anterior. Sin embargo, deberás reconfigurar la fuente de datos en vivo. Para el iPhone y el iPad, agregamos un nuevo delegado de escena para recuperar tu entrenamiento durante la sesión.
Puedes usar el delegado de app creado para Siri para agregar un delegado de escena que se encargue de la recuperación. Definiremos nuestro App Delegate y verificaremos si el parámetro de opciones indica shouldHandleActiveWorkoutRecovery. Ahora tomaremos la workoutSession recuperada de Health Store, y nos aseguraremos de pasar la recoveredSession a tu WorkoutManager. Desde tu WorkoutManager, puedes administrar la continuación del entrenamiento activo. Si recuerdas, solo necesitamos recrear nuestro dataSource.
Por último, repasemos algunas recomendaciones para los entrenamientos. Si tienes una app de Apple Watch, comienza el entrenamiento allí para obtener todas las métricas disponibles. Simplemente invoca a StartWatchApp desde el Health Store. Una vez que lo hagas, asegúrate de reflejar el entrenamiento en el iPhone. Consulta “Build a multi-device workout app” de la WWDC23 para más información.
Tu app solo debe solicitar autorización para los tipos de datos que necesitas. No querrás que tus usuarios se pregunten por qué pides acceso a datos que parecen no estar relacionados con el enfoque de tu app. Por último, usa siempre la API de creación de entrenamientos para crearlos y guardarlos. Esto garantizará que los círculos de actividad se actualicen bien.
Así puedes dar seguimiento a los entrenamientos con HealthKit en el iPhone y el iPad. Con esta actualización, estos dispositivos tienen una API robusta con recuperación de fallas y pueden mostrar y administrar entrenamientos incluso con la pantalla bloqueada. Antes de irme, te dejo algunos próximos pasos. Asegúrate de descargar la app de demostración adjunta a esta sesión. Tiene todo el código que compartí hoy en un ejemplo completamente funcional que puedes usar para comenzar. Si ya tienes una app en el iPhone o el iPad, asegúrate de actualizarla a las API de creación de entrenamientos que mencioné hoy. Creo que te encantarán las mejoras. Si ya tienes una app para Apple Watch, la compatibilidad multiplataforma con la misma API abre un nuevo mercado para quienes no tienen un Apple Watch. Por último, muchas de las funcionalidades que implementamos son la respuesta a tus comentarios, así que sigue enviándolos. Queremos apoyar las funcionalidades que necesitas para seguir creando apps increíbles que ayuden a mantener al mundo saludable. Gracias por tu atención.

// 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
}

- 0:00 - Introducción
- La estructura HealthKit permite que las apps de salud y fitness accedan a una base de datos cifrada y centralizada que contiene la información de salud del usuario. Con las API de entrenamiento de la plataforma, puedes crear apps de entrenamiento integrales para el iPhone y el iPad que las personas pueden usar para llevar un registro de los entrenamientos, acceder a métricas de salud y recibir información sobre la recuperación. Aprende los conceptos básicos sobre cómo ejecutar sesiones de entrenamiento, acceder a métricas durante los entrenamientos, solucionar fallas y brindar consejos y prácticas recomendadas de entrenamiento.
- 0:56 - Iniciar una sesión de entrenamiento
- El mismo código se puede usar en el iPhone, el iPad y el Apple Watch con pequeños ajustes. Para llevar un registro de cualquier actividad, crea una configuración de entrenamiento, establece su tipo y luego inicia una sesión. El generador recopila métricas de salud durante el entrenamiento.
- 2:50 - Obtener métricas de sesión
- Al iniciar un entrenamiento en el Apple Watch, los sensores integrados del dispositivo brindan una experiencia fluida. Por el contrario, la recopilación de datos de frecuencia cardiaca en el iPhone o el iPad requiere el enlace con un sensor de frecuencia cardiaca externo porque estos dispositivos no tienen uno. El iPhone y el iPad pueden recopilar diversas métricas de entrenamiento, pero el sistema puede generar muestras diferentes a las solicitadas específicamente por una app. Puedes modificar los tipos de datos predeterminados recopilados durante un entrenamiento. Después de que el usuario guarda un entrenamiento, puedes consultar y mostrar estadísticas resumidas o crear gráficas de las métricas a lo largo del tiempo. Los entrenamientos del iPhone pueden tener datos más detallados disponibles para ciertas métricas, similares a los entrenamientos históricos del Apple Watch. El iPhone se suele bloquear durante los entrenamientos. Por razones de privacidad, normalmente no se puede acceder a los datos de salud mientras el dispositivo está bloqueado. Sin embargo, el sistema puede solicitarle al usuario que permita el acceso a los datos de entrenamiento a las apps incluso cuando el dispositivo está bloqueado. Luego puedes mostrar actividades en vivo en la pantalla bloqueada con métricas cruciales sin que la persona deba desbloquear su teléfono. La compatibilidad con Siri se extiende a la pantalla bloqueada, lo que permite a las personas iniciar, pausar, reanudar o cancelar entrenamientos sin usar las manos. Puedes integrar las intenciones de Siri en tus apps para habilitar esta funcionalidad.
- 8:35 - Recuperarse de un accidente
- En el Apple Watch, la recuperación de fallas reinicia automáticamente las apps y restaura las sesiones de entrenamiento. Para el iPhone y el iPad, un nuevo delegado de escena se encarga de la recuperación de las sesiones de entrenamiento después de una falla. Puedes usar este delegado de app para verificar las opciones de recuperación y recuperar la sesión de la tienda de Salud.
- 9:34 - Prácticas recomendadas
- Para llevar un registro efectivo de los entrenamientos con HealthKit, duplica los entrenamientos que iniciaste en la app Apple Watch en el iPhone, solicita solo la autorización de datos necesaria y usa la API de creación de entrenamientos. Con estas recomendaciones, podrás garantizar actualizaciones precisas de los círculos de Actividad y mejorar la experiencia del usuario. Asegúrate también de actualizar las nuevas API, descargar la app de demostración y considerar agregar soporte de entrenamiento para el iPhone y el iPad con el fin de expandir tu alcance en el mercado.

Capítulos

Recursos

Videos relacionados

WWDC25

WWDC24

WWDC23