Conheça a API Medications do HealthKit

Olá! Meu nome é Eric. Sou iOS developer na equipe Health. Vou apresentar as novas APIs de medicamentos adicionadas ao HealthKit, que podem possibilitar experiências incríveis no iOS, iPadOS e visionOS. Olá! Meu nome é Srishti Gupta. Também sou software engineer na equipe Health. Hoje vou mostrar o app que desenvolvi que usa as novas APIs que Eric vai apresentar.

Vou apresentar a nova API do HealthKit que permite que seu app leia dados de medicamentos. Vou dar alguns exemplos de como esses dados aparecem no app Saúde. Em seguida, Srishti vai mostrar, passo a passo, um app de exemplo que usa essas APIs.

Vamos falar das consultas de objetos ancorados e como o app Saúde ajudará seu app a gerenciar a autorização de medicamentos recém-adicionados. Antes de detalhar as novas APIs, vou mostrar como os dados de medicamentos são adicionados ao HealthKit. No iOS 15, o app Saúde incluiu o acompanhamento de medicamentos. O acompanhamento de medicamentos fica na aba Buscar do app Saúde. Para começar, toque em Medicamentos. A visualização de medicamentos é exibida. Se você ainda não adicionou um medicamento, toque em “Adicionar um Medicamento”. Ao adicionar um medicamento, o primeiro passo é procurá-lo. Muitos medicamentos têm o mesmo nome, mas podem ter diferentes concentrações e estar disponíveis em diferentes formas. Depois de selecionar um medicamento, configure um cronograma de lembretes para não perder os horários. Você também pode personalizar o medicamento adicionando mais detalhes. Ao concluir, o medicamento será adicionado à lista.

Você pode registrar os medicamentos quando quiser. Cada vez que registrar um, selecione a quantidade tomada e o horário. Quando o sistema exibir um lembrete para você registrar seu medicamento, selecione Tomado ou Não Tomado ou adie a notificação por 10 minutos. Seja ao adicionar medicamentos ou registrar doses, seus dados são armazenados com segurança no HealthKit. Os dados que seus apps podem buscar no HealthKit estão aumentando. Estamos incluindo a capacidade de ler medicamentos e eventos de dosagem. O objeto que representa medicamentos se chama HKUserAnnotatedMedication. HKMedicationDoseEvent representa as doses registradas para um medicamento. É um novo tipo de HKSample. Seu app usa descritores de consulta e HKQueries para buscar dados no HealthKit, e estamos lançando um novo descritor de consulta e uma nova HKQuery para buscar medicamentos. Eles se chamam HKUserAnnotatedMedicationQueryDescriptor e HKUserAnnotatedMedicationQuery. Primeiro, vou focar os dois objetos que representam medicamentos e eventos de dosagem. Medicamentos anotados pelo usuário representam um medicamento específico e suas personalizações. São compostas por quatro propriedades. isArchived é uma sinalizador para medicamento finalizado ou que não está mais sendo tomado. Esses medicamentos são salvos em uma seção de arquivados e não aparecem na lista de medicamentos ativos. hasSchedule informa ao app se o medicamento tem um cronograma de lembretes. Se tiver, o sistema exibirá notificações para registrar esse medicamento. Um apelido é a forma mais fácil de lembrar e se referir a um medicamento, em vez do seu nome clínico mais longo. É usado para personalização, tornando o gerenciamento de medicamentos menos clínico e mais amigável. Há também uma referência ao medicamento que está sendo tomado. HKMedicationConcept representa esse medicamento específico. Isso é chamado de conceito de medicamento, pois representa apenas a ideia conceitual de um medicamento, não o registro de prescrição. Seu identificador é único entre todos os conceitos de medicamento, garantindo que o app identifique o mesmo medicamento em diferentes dispositivos e ao longo do tempo. Seu texto de exibição representa um nome para o medicamento. Sua forma geral indica o formato físico do medicamento, como cápsula, comprimido ou líquido. Diferentes formas de medicamentos podem ter maneiras distintas de serem administradas. Por fim, codificações relacionadas contêm um conjunto de códigos clínicos associados ao medicamento. Esses códigos podem vir de terminologias padronizadas, como RxNorm. Isso permite a interoperabilidade com outros sistemas de saúde e uma forma mais robusta de identificar e categorizar medicamentos. Eventos de dose representam os horários em que um medicamento deveria ser tomado ou foi tomado. Eles são um novo tipo de HKSample. Estão relacionados a um medicamento específico, pelo medicationConceptIdentifier. Também contêm o status do registro do evento, como Tomado ou Não Tomado. Doses programadas podem ser adiadas ou não receber nenhuma interação. As doses salvas nesses casos terão um logStatus que reflete a situação. Cada evento de dose também captura quanto de um medicamento foi registrado. Eventos de dose programados terão a data e a quantidade referentes à dose agendada. Se a quantidade programada for diferente da quantidade da dose, isso significará que houve uma diferença entre o que estava previsto para ser tomado e o que foi realmente tomado. Os eventos de dose estão vinculados a um medicamento. O medicationConceptIdentifier é o mesmo que a propriedade identifier de um conceito de medicamento. Seu app buscará HKUserAnnotatedMedications no HealthKit. Quando seu app fizer consultas, eles representarão o estado atual das personalizações no app Saúde. Agora vou mostrar um medicamento adicionado ao app Saúde e indicar onde você pode ver seus detalhes e personalizações. Vamos supor que você adicionou amoxicilina ao app Saúde. Você vai iniciar um tratamento com antibióticos para combater uma infecção. Quando seu app consultar os medicamentos, receberá um objeto que representa a amoxicilina e suas propriedades personalizáveis. Não há um cronograma configurado para esse medicamento, é “Uso Esporádico”. E o apelido que você deu é “Antibióticos”, pois reflete porque você está tomando o medicamento. A amoxicilina é representada por um conceito de medicamento. Tem um identificador único, seu nome é “amoxicilina tri-hidratada cápsula 500 mg oral” e é fabricada na forma de cápsula. E há uma única codificação relacionada. Um código RxNorm 308192. Seu app pode usar esse HKUserAnnotatedMedication para criar uma experiência semelhante à mostrada no app Saúde. Ele contém os componentes personalizáveis e os detalhes específicos do medicamento. Seu app consultou os medicamento no app Saúde, mas para criar experiências baseadas em como esse medicamento foi registrado, seu app também vai buscar os Eventos de dose. Vou mostrar um exemplo de evento de dose registrado e indicar quais valores seu app pode esperar nessas propriedades. Como é importante tomar antibióticos em uma cadência regular, você configurou um cronograma. Um lembrete foi enviado para tomar amoxicilina, mas você o ignorou. Quando você ignorou o lembrete, um evento de dose foi salvo no HealthKit. Seu app consultará eventos de dose de medicamentos e receberá essa amostra no manipulador de resultados. O status do evento de dose é skipped. Como o medicamento não foi tomado, doseQuantity é 0. startDate da amostra é o horário do registro. Este evento de dose registra um evento agendado específico. scheduledDate e scheduledQuantity correspondem ao evento programado. A data é o horário programado do evento e a quantidade é o que deveria ter sido tomado. Haverá eventos de dose salvos para cada dose programada de um medicamento. Esse evento de dose está associado ao conceito de medicamento amoxicilina, pelo seu medicationConceptIdentifier. Seu app pode usar HKMedicationDoseEvents para criar experiências baseadas em como alguém registrou o medicamento. Elas capturam o contexto e os detalhes do que foi registrado. Agora que mostrei os dois objetos que seu app pode usar para incorporar dados de medicamentos, vou mostrar as consultas que seu app pode usar para buscá-los. Para obter a lista de medicamentos, seu app deve usar o novo descritor de consulta. Seu app pode usá-lo para obter a lista de medicamento ativos e arquivados do HealthKit. Há dois novos predicados que você pode usar com esse descritor de consulta. Um para isArchived e outro para hasSchedule. O app também pode especificar um limite. Se o descritor de consulta for configurado com um predicado, o app receberá apenas os medicamento que correspondem a esse predicado. Nesse caso, o app não verá o piroxicam, pois ele está arquivado. Eventos de dose são HKSamples, e seu app pode usar qualquer consulta existente baseada em tipos de amostra para buscá-los, como consultas de amostra, consultas de objeto ancorado e consultas de observador. Ao configurar essas consultas, seu app deve usar o novo tipo de amostra HKMedicationDoseEvent. Também lançamos diversos novos predicados de consulta para eventos de dose. Ao escolher quais eventos de dose buscar, o mais útil é buscá-los por medicamento ou por status de registro.

Agora que mostrei uma visão geral dessas APIs e alguns exemplos de dados, vamos conferir com a Srishti. Ela criou um app que incorpora dados de medicamento e eventos de dose do HealthKit. Srishti, estou curioso para conhecer o app que você criou. Também quero ver como você está usando a API de medicamentos. Poderia fazer uma demonstração? Claro, Eric! Vou mostrar como funciona o app que criei. É para visualizar eventos de dose e registrar efeitos colaterais de um medicamento. Vamos ver como ele funciona. Você também pode baixar o app de exemplo desta sessão pelo link disponível na página de descrição da sessão. Ao abrir meu app, você verá uma lista de medicamentos que já estão autorizados. São os medicamentos que foram adicionados ao app Saúde. Quando toco em um medicamento específico, vejo a dose mais recente que tomei hoje. Eu o registrei como tomado esta manhã no app Saúde. Também posso ver uma lista de efeitos colaterais que posso estar sentindo. Os efeitos colaterais estão ligados a esse medicamento específico. Como estou com uma dor de cabeça forte, vou selecionar esse sintoma e escolher um emoji para marcar como grave. Vou tocar no botão “Salvar no HealthKit” para salvar a amostra. Agora que fiz um resumo rápido do meu app, vamos entrar nos detalhes de como o criei. Antes, precisamos pedir permissão para ler e compartilhar os dados do usuário. Meu app usa a API de autorização por objeto do HealthKit para solicitar acesso de leitura aos dados de medicamentos, já que medicamentos são objetos. Essa solicitação está incorporada em um view do SwiftUI. Configurei minha solicitação com um repositório de saúde e um novo tipo de objeto, HKUserAnnotatedMedicationType. Também usei uma variável de estado para indicar quando o prompt de autorização deve ser acionado. Quando essa variável de estado é alterada para true, o sistema exibe uma lista de medicamentos adicionados ao app Saúde. Para alternar os medicamento a serem compartilhados com o app, basta tocar em “Permitir”. Após a revisão da autorização, o manipulador de conclusão é chamado, permitindo que eu trate os erros de modo adequado. Não preciso solicitar autorização separadamente para ler as doses de medicamento. Quando alguém autoriza um medicamento, meu app recebe automaticamente permissão para ler esse medicamento e suas doses. Em uma solicitação separada, meu app também solicita permissão para ler e compartilhar sintomas, como náusea e dor de cabeça. Vou usar uma chamada de API semelhante para solicitar acesso aos dados de saúde. Mas aqui forneço uma lista de tipos de amostras para ler e compartilhar, em vez de um único tipo de objeto. Alterar a variável de estado para true inicia a solicitação de autorização, exibindo uma tela para selecionar os tipos de dados a serem lidos e compartilhados. Os usuários podem alternar os tipos de sintomas e tocar em “Permitir”. A conclusão da solicitação de autorização deve ser tratada da mesma forma, garantindo que meu app falhe de modo adequado se a autorização não for bem-sucedida. Após verificar as autorizações, o app fará uma consulta para obter a lista completa de medicamentos autorizados no HealthKit. Para isso, meu app usa uma função assíncrona que retorna uma matriz de HKUserAnnotatedMedications. Essa função configura um descritor de consulta para buscar a lista autorizada de medicamentos. Esses são os medicamentos que alguém adicionou ao app Saúde. Para essa consulta, não é necessário predicado nem limite, pois queremos buscar os medicamentos ativos e arquivados. Vou aguardar os resultados do descritor de consulta, usando uma referência ao repositório de saúde. A classe que implementa esta função é responsável por várias consultas, por isso mantém uma referência a um repositório de saúde como uma variável de instância. Meu app só verá os medicamentos para as quais alguém concedeu autorização. Se eu tiver resultados da consulta, pegarei a lista de medicamentos dessa função e a usarei para preencher a visualização principal do meu app. Ao tocar em um medicamento, uma nova consulta busca os eventos de dose para a visualização das informações do medicamento. Precisamos consultar um evento de dose de medicamento que foi registrado para hoje. Vou mostrar como configurei meu descritor de consulta para buscar o evento de dose mais recente. Para buscar a última dose, escrevi uma função que recebe um HKMedicationConcept e retorna um HKMedicationDoseEvent opcional. Se nenhuma dose for registrada para hoje, o evento para esse medicamento será nil. Configurei um predicado composto para limitar meus resultados, pois me interessam eventos de dose do medicamento fornecido, doses registradas hoje e com status Tomado. Para ver mais detalhes de como configurei esse predicado de exemplo, confira o app de exemplo. Configurei o restante do meu descritor de consulta de exemplo e retornei o primeiro objeto dos resultados aguardados. sortDescriptors e limit garantem que os resultados tenham apenas a dose mais recente registrada que corresponda aos meus predicados. Depois de recuperar a dose de hoje, uso startDate para configurar o bloco da dose. Se não houver dose registrada para hoje, não mostrarei nada.

Meu app buscou com sucesso medicamentos e eventos de dose do HealthKit. Quero exibir uma lista de efeitos colaterais associados a um medicamento específico. Para isso, pesquisei os efeitos colaterais de cada medicamento.

Todo medicamento pode ter uma lista de efeitos colaterais, e o HealthKit tem tipos de categoria que refletem alguns dos sintomas, como dor de cabeça, náusea, entre outros. Quando fiz a pesquisa, associei códigos de um sistema chamado RxNorm a um modelo de sintomas que registra o nome do sintoma e o identificador do tipo de categoria. O RxNorm codifica medicamentos clínicos como identificadores únicos que representam um conceito individual. Codifiquei as associações que pesquisei em uma estrutura estática no app. Vou mostrar como relacionei um medicamento a uma lista de tipos de efeitos colaterais por meio dos códigos RxNorm. Vamos ver o diagrama que o Eric mostrou antes: usei a propriedade relatedCodings no HKMedicationConcept. Ele contém um conjunto de codificações clínicas que representam o medicamento. Codificação clínica é um código contextualizado em um sistema. Esses códigos representam conceitos médicos específicos, como alergias, condições e, no nosso caso, medicamentos. Os sistemas são identificados de acordo com a Terminologia oficial do FHIR. O sistema que me interessa, RxNorm, tem o seguinte URL que o identifica de modo único. Para saber mais sobre como modelar essas codificações, confira a documentação para desenvolvedores. Agora, vou mostrar como uso o sistema RxNorm no meu app. Aprimorei a estrutura de efeitos colaterais para relacionar os efeitos colaterais conhecidos a um medicamento. A primeira coisa que fiz foi adicionar uma constante para o sistema RxNorm. Depois, criei uma função para recuperar os tipos de sintomas de um HKMedicationConcept. Essa função relaciona os códigos RxNorm de um medicamento aos modelos de sintomas usando os dados do meu dicionário estático. Usei a função estática SideEffects para buscar todos os sintomas associados ao medicamento e exibi-los na visualização de detalhes do medicamento. Agora que meu app tem um conjunto de sintomas para um medicamento, implementei uma experiência para registrar esses sintomas. Meu jeito favorito de representar e registrar a intensidade dos sintomas é usando emojis. Para começar, escolhi 5 emojis que representam a intensidade do sintoma, de Nenhum ao Extremo. Depois, criei um novo enum chamado SymptomIntensity. Quero converter a intensidade na amostra de categoria para salvar no HealthKit, então associei os casos a um valor de categoria correspondente. Para integrar tudo, escrevi uma função que cria uma amostra para um tipo de categoria e uma SymptomIntensity. Vou salvar a amostra usando o método de salvamento no repositório de saúde. Quando toco em um tipo de sintoma, aparece um seletor de emoji. Posso escolher um emoji para representar a intensidade do meu sintoma e salvá-lo no HealthKit. Esse é o meu app até agora. Revisei as diferentes experiências que criei e as diversas consultas de medicamento que meu app usa para buscar os dados. Também mostrei como utilizei o sistema RxNorm para associar sintomas e exibi-los no meu app. Estou pensando em adicionar uma nova experiência com gráficos para acompanhar as doses de medicamento registradas ao longo do tempo. Eric, eu estava pensando em usar uma consulta de objeto ancorado para observar e buscar os dados subjacentes e preencher os gráficos. O que você acha? Agradeço por essa visão geral incrível. Uma consulta de objeto ancorado seria perfeita para a sua experiência com gráficos. Seu gráfico pode ser atualizado sempre que novas doses forem salvas no HealthKit.

Tenha cuidado ao usar uma consulta de objeto ancorado para dados de eventos de dose. Eventos de dose podem ser registrados para dias no passado, apagados e regravados ao editar ou salvos para lembretes com os quais nunca houve interação. Se tratados incorretamente, podem parecer dados inconsistentes. Aqui vai um resumo sobre consultas de objeto ancorado e algumas boas práticas. Quando seu app executa uma consulta de objeto ancorado, ele recebe um instantâneo das amostras existentes. Com uma atualização, seu app recebe outro conjunto de resultados, que pode conter exclusões de amostras que seu app já processou. As consultas de objeto ancorado podem ser usadas de vários jeitos. São uma maneira eficiente de garantir que seu app receba os novos dados adicionados ao HealthKit. As consultas de objeto ancorado são úteis para buscar dados considerando a âncora da consulta fornecida. Se você já buscou dados usando uma consulta de objeto ancorado, use a âncora da consulta retornada para garantir que seu app não processe os mesmos dados. Se seu app quiser iniciar uma consulta do início, forneça nil para a âncora de consulta. Seu app deve refletir os dados mais recentes de eventos de dose adicionados ao HealthKit. Eventos de dose registram um comportamento interativo, então pode ser desconfortável para o usuário ver dados desatualizados no app. Use consultas ancoradas para manter os dados do seu app atualizados, de modo que correspondam ao que é exibido no app Saúde. Consultas de objeto ancorado são mais eficientes do que uma consulta observadora emparelhada e uma consulta de amostra. E há uma interface Swift assíncrona para consultas de objetos ancorados. Essa interface fornece um fluxo de resultados, utilizável com Swift async/await. Se você nunca usou uma consulta de objeto ancorado ou quer saber mais e ver exemplos, consulte a documentação para desenvolvedores. E confira a apresentação da WWDC “Introdução ao HealthKit”.

Veremos como a Srishti vai usar uma consulta de objeto ancorado para buscar dados para os gráficos. Srishti, pode mostrar como está implementando essa consulta?

Com certeza! Vou escrever uma consulta que busque apenas as doses registradas para o medicamento dentro do intervalo de datas do gráfico. E preciso acompanhar como os dados do meu app estão sendo atualizados. Para configurar minha consulta de objeto ancorado, vou configurar a consulta como no exemplo que criei antes. Vou usar o mesmo predicado para buscar doses por medicamento e status de registro, mas substituí o predicado de hoje por outro que corresponde às doses dentro do intervalo de datas do gráfico. Para ver mais detalhes de como configurei esse predicado, confira o app de exemplo. Vou fornecer nil para a âncora, pois quero começar do início de todos os eventos de dose registrados. Uso uma interface Swift assíncrona para executar a consulta em um thread em segundo plano. Após receber os resultados da consulta, vou processá-los em uma função separada para atualizar o modelo de dados do app. Farei isso em uma nova função chamada handleResult. Primeiro, preciso obter os objetos excluídos do resultado e limpar os dados que foram excluídos. Preciso atualizar meu conjunto de pontos do gráfico com as novas amostras. Para ver mais detalhes de como gerenciei os pontos do gráfico, confira o app de exemplo. Agora, vamos ver a interface e como meus gráficos são atualizados quando novos dados são salvos. Aqui está meu gráfico, em que o eixo x representa os dias e o eixo y representa o número de doses tomadas de um medicamento. Escolha diferentes medicamentos na visualização de rolagem horizontal. No meu Apple Watch, vou registrar minha dose no app Medicamentos. Como estou usando uma consulta de objeto ancorado para verificar novos dados, meu gráfico é atualizado com as novas doses registradas no meu Apple Watch. Estou feliz com o resultado dos meus gráficos. Ele vai mostrar os dados mais recentes salvos no HealthKit, o que é conveniente para acompanhar as doses registradas ao longo do tempo. Mas Eric, o que acontece quando adiciono um novo medicamento no app Saúde? Ótima pergunta. Tudo o que mostramos até agora assume que seu app tem autorização para todos os medicamentos adicionados ao app Saúde.

Seu app foi instalado e autorizado com sucesso para acessar dados de medicamentos. Uma pessoa que está usando seu app quer adicionar um novo medicamento à lista ativa. Ela quer que o novo medicamento apareça ao lado dos outros medicamento ativos, então vai voltar ao app Saúde para adicioná-la. Ela vai buscar o novo medicamento que quer adicionar e personalizá-lo. Antes de adicioná-la à lista, há uma última etapa. Como seu app já solicitou acesso aos medicamentos, o app Saúde vai apresentar ao usuário uma opção para escolher se deseja compartilhar os dados com seu app. Isso é como pedir autorização, só que dentro do app Saúde, e não exige nenhum trabalho extra do seu app. Depois de selecionar seu app, o medicamento é salvo no app Saúde. Ao voltar ao app, é possível ver o medicamento recém-adicionado. Gerenciar a autorização desse modo simplifica tudo, tanto para o app quanto para os usuários. E essa é a API de medicamentos. De personalizações únicas a doses ao longo do tempo, seu app tem tudo para criar uma ótima experiência com dados de medicamentos. Tudo está conectado por meio de um conceito específico de medicamento, que está relacionado a outros dados clínicos. Imagine todas as experiências que podem ajudar as pessoas a entender como os medicamento que estão tomando afetam sua saúde. Espero que você encontre maneiras úteis de incorporar medicamentos no seu app.

Antes da despedida, aqui vão algumas coisas que você deve saber. Mostramos superficialmente o app de exemplo, e há muitos caminhos que você pode seguir a partir dele. Baixe o app de exemplo e confira o código para ajudar a dar a começar o desenvolvimento dos seus próprios apps. Para aproveitar a API HKMedicationConcept, explore os sistemas de codificação clínica como o RxNorm para ajudar a categorizar e identificar medicamentos e associá-los a dados valiosos, como efeitos colaterais ou conteúdos educativos. Consulte a documentação para desenvolvedores para entender os diferentes status de registro, obter mais predicados de consulta e explorar outros recursos do HKMedicationDoseEvent. Por fim, confira nossa outra apresentação: “Conhecer os treinos no iOS”. Agradecemos por explorar a API de medicamentos com a gente. Queremos ver o que você vai criar. E conte o que você achou dessas novas APIs usando o Assistente de Feedback. Agrademos sua participação.