Acompanhe exercícios com o HealthKit no iOS e iPadOS

Acompanhe exercícios com o HealthKit no iOS e iPadOS

Conheça as melhores práticas para criar uma ótima experiência de exercício no iOS. Revise o ciclo de vida de uma sessão de exercício, explore as diferenças entre os treinos no Apple Watch e no iPhone e saiba como usar as Atividades ao Vivo e a Siri para melhorar a experiência do seu app na Tela Bloqueada.

Capítulos
- 0:00 - Introdução
- 0:56 - Realizar uma sessão de exercício
- 2:50 - Obter as métricas da sessão
- 8:35 - Recuperar após um falha
- 9:34 - Melhores práticas
Recursos
Vídeos relacionados

WWDC25
- Conheça a API Medications do HealthKit
WWDC24
- Bring your app’s core features to users with App Intents
WWDC23
- Build a multi-device workout app
- Meet ActivityKit
Olá! Meu nome é Brian. Sou Engineer na equipe HealthKit. Há centenas de apps de saúde e boa forma que ajudam as pessoas a serem saudáveis. Com a sua permissão, elas têm acesso ao banco de dados centralizado e criptografado do HealthKit e a um conjunto de APIs para oferecer uma visão abrangente da sua saúde. As APIs de treino estão entre as mais avançadas que o HealthKit oferece. Vou mostrar como usar essas APIs no iPhone e no iPad. Vou começar abordando o básico de uma sessão de treino. Vou abordar como acessar métricas de saúde durante um treino, com foco em como esse processo é diferente do que ocorre no Apple Watch. Depois, vou mostrar como se recuperar em caso de falha e finalizarei com algumas dicas de treino e boas práticas. Vamos começar esta sessão de treino. Se você já executa treinos em um app no Apple Watch, poderá usar o mesmo código no iPhone e no iPad com poucas alterações. Assim como no Apple Watch, você pode usar uma sessão de treino para acompanhar qualquer atividade e usar o construtor de treino associado para salvar o treino no HealthKit. Como você ainda pode não ter um app no Apple Watch, vou mostrar rapidamente um exemplo de como executar uma sessão de treino. Uma sessão de treino tem várias etapas, desde a configuração e o início até a coleta de métricas de saúde e o encerramento da sessão. Para começar, você precisa criar uma configuração de treino e definir seu tipo para refletir a atividade que a pessoa vai realizar. Vou usar running e definir a localização como outdoor. Em seguida, crie HKWorkoutSession passando a configuração.
Na sessão de treino, obtenha o construtor associado e conecte uma fonte de dados.
Depois, chame prepare na sessão e exiba uma contagem regressiva de três segundos para ativar os sensores do dispositivo ou conectar um monitor externo de frequência cardíaca. Essa contagem regressiva garante que as métricas estejam disponíveis assim que a atividade do treino começar. Assim que a contagem regressiva terminar, basta chamar startActivity na sessão e beginCollection no construtor de treino associado. Não é necessário usar uma consulta de objeto ancorado para atualizar a interface. O delegado do construtor de treino oferece atualizações convenientes para o app quando novos dados são coletados e mantém as métricas sincronizadas quando o treino é salvo.
Quando o usuário decidir encerrar o treino, você deverá chamar stopActivity na sessão para permitir que as métricas finais sejam coletadas pelo construtor ativo.
Assim que a sessão mudar para o estado de parada, você pode chamar endCollection no construtor e finalizar o treino. Depois que o construtor finalizar, chame end na sessão e exiba o resumo do treino.
Agora que você já sabe como executar um treino, vou explicar algumas diferenças entre fazer um treino no Apple Watch e no iPhone ou no iPad. Uma diferença são os sensores disponíveis.
Embora todos os tipos de atividade de treino estejam disponíveis no iPhone e iPad, esses dispositivos não têm sensor de frequência cardíaca.
Você pode parear o iPhone ou o iPad com dispositivos usados durante o treino compatíveis com o perfil GAT de frequência cardíaca, como monitores wearable ou o Powerbeats Pro 2.
Depois que um dispositivo é emparelhado, o HealthKit obtém dados de frequência cardíaca e salva-os como amostras no Health Store, disponibilizando-os ao app. Isso significa que pode haver uma diferença entre as amostras que você quer coletar no treino e as amostras que o sistema consegue gerar. Vamos analisar essa diferença.
Tipos gerados: São os tipos de dados gerados pelo sistema durante uma atividade de treino, como calorias e distância. E tipos coletados: São as métricas que você deseja monitorar ao vivo e adicionar à amostra do treino. Por exemplo, se o app quiser registrar a água consumida durante um treino, ele precisará adicionar essas amostras ao banco de dados de saúde.
Na inicialização do iPhone e iPad, os tipos coletados na fonte de dados incluirão os tipos de amostra que queremos coletar para a atividade atual. A frequência cardíaca será incluída mesmo que não seja gerada pelo sistema, a menos que você tenha um sensor externo de frequência cardíaca.
A fonte de dados observa todas as amostras e tipos a serem coletados, gerados pelo sistema ou salvos pelo app, e os envia para o Live Builder.
Para saber o que o sistema está gerando, use o mesmo delegado Workout Builder utilizado para atualizar as métricas na interface. Se seu app quiser modificar os tipos padrão para coleta, você poderá chamar enable ou disable collection de métodos de tipo na fonte de dados para adicionar ou remover os tipos desejados. Para coletar a água ingerida durante um treino, o app chama Enable Collection e, enquanto o treino estiver em andamento, adiciona a medição como uma amostra ao banco de dados de saúde, e a fonte de dados passará essas amostras para o Live Builder. Agora que você sabe como obter métricas durante a sessão, vamos descobrir como ler as métricas do treino depois de salvo.
Comece usando estatísticas no objeto de treino para mostrar um resumo.
Se quiser mostrar gráficos das métricas ao longo do treino, use uma consulta de coleção de estatísticas com o intervalo desejado.
Se o app precisar de dados detalhados, as amostras de quantidade associadas ao treino podem ter uma contagem maior que um. Isso indica que as amostras têm dados mais detalhados, que podem ser acessados usando HKQuantitySeriesSampleQuery.
Você pode ter notado que isso acontece ao analisar treinos históricos do Apple Watch, e o mesmo ocorrerá com treinos salvos no iOS. Agora você sabe como coletar métricas enquanto seu app está em primeiro plano e como lê-las após o treino ter sido salvo. Outra diferença é que, ao contrário do Apple Watch, é provável que seu iPhone seja bloqueado durante um treino. Por privacidade, dados de saúde não ficam disponíveis com o dispositivo bloqueado, mas não se preocupe. Na primeira vez que uma sessão de treino é iniciada, o sistema mostra um aviso informando que os dados do treino estarão disponíveis no app, mesmo com o dispositivo bloqueado. Essa é uma ótima oportunidade para seu app mostrar uma atividade ao vivo com suas métricas mais importantes na tela de bloqueio, permitindo atualizações em tempo real sem que o usuário precise desbloquear o telefone. Mas lembra aquele aviso de privacidade que mencionei? Atualize a interface para mostrar só a duração do treino se os dados não estiverem disponíveis com o dispositivo bloqueado ou se a frequência cardíaca não estiver acessível, não exibindo a métrica. Mas isso não é tudo o que você pode fazer na tela de bloqueio. Estamos contentes em trazer suporte à Siri na tela de bloqueio. Agora você poderá iniciar, pausar, retomar e cancelar um treino sem precisar desbloquear o telefone. Assim que o telefone for desbloqueado, o HealthKit salvará e disponibilizará o treino no seu app via Health Store. Vou explicar como adicionar uma intent da Siri ao app que funciona na tela de bloqueio.
Você começa definindo IntentHandler. Isso precisa ser tratado dentro do app para funcionar na tela de bloqueio. Depois, você vai definir as Intents às quais deseja dar suporte. Eu as dividi neste exemplo para facilitar a leitura. Em seguida, você vai tratar a intent recebida. Aqui, recebi StartWorkoutIntent. Você começa verificando se já existe um treino em andamento e retorna uma falha caso exista. E você precisa obter o tipo de atividade e a localização. Neste exemplo, vou definir como uma corrida ao ar livre. Depois, você retorna uma resposta de sucesso.
Agora que você tem intents definidas, precisa criar um delegado de app para responder a elas. Você então definirá o delegado no seu app.
E, com isso, seu app é compatível com as intents de treino da Siri na tela bloqueada.
Adicionar intents da Siri e Atividades ao Vivo garantirá que as pessoas aproveitem ao máximo seu app, independentemente do estado de bloqueio do dispositivo. Para saber mais sobre essas tecnologias, confira "Disponibilizar os principais recursos do app com o App intents" da WWDC24 e "Conhecer o ActivityKit" da WWDC23. Agora que você sabe como ver as métricas nas sessões e usar as intents da Siri em Atividades ao Vivo, vamos para a recuperação de falhas. A recuperação de falhas já está disponível no Apple Watch há algum tempo, mas vou destacar três pontos principais. O sistema vai reiniciar automaticamente o seu app em caso de falha. A sessão de treino no Builder será restaurada em seu estado anterior. Mas você precisará reconfigurar sua fonte de dados ao vivo. Para iPhone e iPad, adicionamos um novo delegado de cena que você usará para recuperar seu treino em andamento.
Usar o App Delegate criado para Intents da Siri para adicionar Scene Delegate que lidará com a recuperação de falhas. Começaremos definindo nosso App Delegate e verificando se o parâmetro options indica shouldHandleActiveWorkoutRecovery. Agora, vamos obter a workoutSession recuperada do Health Store, garantindo passar recoveredSession para WorkoutManager.
Em WorkoutManager, você pode gerenciar a continuação do treino ativo. E, se você se lembra, só precisamos recriar dataSource.
Por fim, vou falar sobre algumas melhores práticas para treinos. Se você tiver um app para Apple Watch, inicie o treino nele para obter todas as métricas disponíveis. Basta chamar Start Watch App no Health Store. Depois de fazer isso, espelhe o treino para o iPhone. Confira "Criar um app de exercícios compatível com vários dispositivos" da WWDC 23 para saber como. Seu app deve solicitar autorização apenas para os tipos de dados necessários. O app deve pedir autorização somente para os tipos de dados relacionados, para evitar que usuários fiquem confusos sobre o motivo do pedido. Por fim, sempre use a API Workout Builder para criar e salvar um treino. Isso garantirá que os círculos de atividade sejam atualizados corretamente.
É assim que se rastreia treinos com o HealthKit no iPhone e no iPad. Com essa atualização, esses dispositivos contam com uma API robusta, com recuperação de falhas e capacidade de exibir e gerenciar treinos com a tela bloqueada. Aqui estão alguns próximos passos antes de eu ir. Não deixe de baixar o app de demonstração anexado a esta sessão. Ele contém todo o código que compartilhei hoje, reunido em um exemplo funcional para você começar. Se você já tem um app para iPhone ou iPad, atualize para as APIs do Workout Builder de que falei hoje. Essa atualização é uma ótima melhoria. Se você já tem um app para Apple Watch, o suporte multiplataforma para a mesma API significa que seu app alcança um novo mercado para quem não tem Apple Watch. Por fim, muitos recursos implementados são resultado direto do seu feedback, então continue enviando sugestões. Queremos ajudar em relação aos recursos de que você precisa para continuar criando apps incríveis que mantêm o mundo saudável. Agradeço sua participação.

// 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 - Introdução
- O framework HealthKit permite que apps de saúde e boa forma acessem um banco de dados criptografado centralizado com dados de saúde do usuário. Com as APIs da plataforma, você pode criar apps de exercícios para iPhone e iPad que as pessoas podem usar para acompanhar treinos, acessar métricas de saúde e receber informações sobre recuperação. Aprenda o básico sobre sessões de exercícios, como acessar métricas durante os treinos, como lidar com falhas e como fornecer dicas e práticas recomendadas.
- 0:56 - Realizar uma sessão de exercício
- O mesmo código pode ser usado no iPhone, no iPad e no Apple Watch com pequenos ajustes. Para monitorar qualquer atividade, crie uma configuração de treino, defina o tipo e inicie uma sessão. O criador de exercícios coleta métricas de saúde durante o treino.
- 2:50 - Obter as métricas da sessão
- Ao executar um treino no Apple Watch, os sensores integrados do dispositivo proporcionam uma experiência perfeita. Por outro lado, a coleta de dados de frequência cardíaca no iPhone ou iPad requer o emparelhamento com um sensor de frequência cardíaca externo, pois esses aparelhos não têm um. O iPhone e o iPad podem coletar várias métricas de treino, mas o sistema pode gerar amostras diferentes daquelas especificamente solicitadas por um app. Você pode modificar os tipos padrão de dados coletados durante um treino. Depois que alguém salva um treino, você pode acessar e exibir estatísticas resumidas ou métricas em gráficos ao longo do tempo. Os treinos do iPhone podem ter dados mais refinados disponíveis para determinadas métricas, semelhante ao histórico de exercícios do Apple Watch. O iPhone normalmente é bloqueado durante os treinos. Por motivos de privacidade, os dados de saúde geralmente não ficam acessíveis enquanto o dispositivo está bloqueado. No entanto, o sistema pode solicitar que alguém permita o acesso aos dados do treino a apps mesmo quando bloqueados. Você pode então exibir atividades ao vivo na Tela Bloqueada, mostrando métricas cruciais sem que a pessoa precise desbloquear o telefone. A compatibilidade com a Siri se estende para a Tela Bloqueada, permitindo iniciar, pausar, retomar ou cancelar exercícios sem usar as mãos. Você pode integrar as intenções da Siri aos seus apps para ativar essa funcionalidade.
- 8:35 - Recuperar após um falha
- A recuperação de falhas no Apple Watch reinicia apps e restaura automaticamente as sessões de treinos. No iPhone e iPad, um novo delegado de cena cuida da recuperação das sessões de treino após uma falha. Você pode usar esse delegado para verificar opções de recuperação e reaver as sessões recuperadas do app Saúde.
- 9:34 - Melhores práticas
- Para monitorar a eficiência dos treinos com o HealthKit, espelhe os exercícios iniciados no app Apple Watch para iPhone, solicite autorização apenas para os dados necessários e use a API do criador de exercícios. Com essas recomendações, você garante atualizações precisas dos círculos de Atividade e aprimora a experiência do usuário. Também faça upgrade para as novas APIs, baixe o app de demonstração e adicione suporte a exercícios para iPhone e iPad para expandir seu alcance de mercado.

Capítulos

Recursos

Vídeos relacionados

WWDC25

WWDC24

WWDC23