Conoce la HealthKit Medications API

¡Hola! Soy Eric, iOS developer del equipo de Salud. Hoy les presentaré las nuevas API de medicamentos en HealthKit que pueden impulsar experiencias emocionantes en iOS, iPadOS y visionOS. ¡Hola! Yo soy Srishti Gupta, Software Engineer en Salud. Yo mostraré una app que desarrollé y que usa las nuevas API que Eric presentará.

Primero, repasaré la nueva API de HealthKit para que tu app pueda leer datos de medicamentos. Daré algunos ejemplos de cómo se ven estos datos en Salud. Luego, con Srishti veremos una app de muestra que usa estas API.

Repasaremos las consultas de objetos anclados y cómo con Salud tu app podrá administrar la autorización de medicamentos recién agregados. Antes de ver las nuevas API, les mostraré cómo agregar los datos de medicamentos a HealthKit.

En iOS 15, la app Salud agregó el seguimiento de medicamentos. Lo puedes encontrar en la pestaña Buscar en Salud. Para comenzar toca Medicamentos. Irás a la vista de medicamentos. Si aún no agregaste ninguno, puedes agregar el primero tocando Agregar un medicamento. Para ello, deberás buscarlo. Muchos medicamentos tienen el mismo nombre, pero diferentes concentraciones y formas. Luego de seleccionar uno, también puedes configurar recordatorios para ayudarte con el seguimiento. También podrás agregar detalles adicionales sobre tu medicamento para personalizarlo. Cuando finalices, aparecerá el medicamento en tu lista.

Puedes registrar medicamentos en cualquier momento. Cuando inicies sesión, podrás elegir qué cantidad tomaste y cuándo. Cuando el sistema te envía un recordatorio para registrar tus medicamentos, puedes elegir Tomado, No tomado, o posponer la notificación 10 minutos. Cuando agregas medicamentos o registras dosis, tus datos se almacenan de forma segura en HealthKit. Actualmente, hay más datos que tus apps pueden obtener de HealthKit. Agregamos la posibilidad de leer medicamentos y eventos de dosis. El objeto que representa los medicamentos es HKUserAnnotatedMedication. HKMedicationDoseEvent representa las dosis registradas de un medicamento. Es un nuevo tipo de HKSample. Tu app usa descriptores de consulta y HKQueries para tomar datos de HealthKit. Presentamos un nuevo descriptor de consulta y un nuevo HKQuery para buscar medicamentos. Estos son HKUserAnnotatedMedicationQueryDescriptor y HKUserAnnotatedMedicationQuery. Primero, me centraré en los dos objetos que representan medicamentos y eventos de dosis. Los medicamentos registrados por el usuario representan un medicamento y su personalización. Tienen cuatro propiedades. isArchived es una marca que indica que se terminó un medicamento o ya no se toma. Estos medicamentos se guardan en una sección archivada y no aparecen en la lista de medicamentos activos. hasSchedule le dice a tu app si un medicamento tiene recordatorios configurados. Si es así, el sistema muestra notificaciones periódicamente para registrar este medicamento. Para referirse a un medicamento, es más fácil usar un apodo, en lugar de su nombre clínico más largo. Sirve para personalizarlo y que la administración sea menos clínica y más amigable. También hay una referencia a la medicación que se está tomando. Un HKMedicationConcept integra ese medicamento específico. Lo llamamos “concepto de medicamento”: solo representa la idea conceptual de un medicamento, no un registro de recetas. Su identificador es único entre los conceptos de medicamentos, lo que garantiza que la app identifique el mismo medicamento en diferentes dispositivos y en el tiempo. Su texto en pantalla representa un nombre para el medicamento. Su forma general indica la forma física del medicamento: cápsula, tableta o líquido. La forma del medicamento puede tener diferentes modos de administración. Finalmente, las codificaciones relacionadas contienen un conjunto de códigos clínicos asociados al medicamento. Estos pueden ser de terminologías estandarizadas, como RxNorm. Así es posible la interoperabilidad con otros sistemas de salud y una forma más sólida de identificar y categorizar los medicamentos. Los eventos de dosis son los momentos en los que debía tomarse un medicamento, o en que se tomó. Son un nuevo tipo de HKSample. Siempre están relacionados con un medicamento, mediante su identificador de concepto de medicamento. También contienen el estado del registro del evento, como Tomado o No tomado. Las dosis programadas se pueden posponer o no interactuar con ellas. Las dosis guardadas para estos casos tienen un estado de registro que las muestra. Cada evento de dosis captura la cantidad de medicamento que se registró. Los eventos de dosis programadas tienen la fecha y la cantidad de esa dosis programada. Si la cantidad programada difiere de la cantidad de dosis significa que hubo una diferencia entre lo que estaba programado tomar y lo que realmente se tomó. Otra vez, los eventos de dosis están vinculados a un medicamento. El identificador del concepto de medicamento es igual que la propiedad identificadora de un concepto de medicamento. Tu app tendrá HKUserAnnotatedMedications de HealthKit. Cuando tu app los consulte, representarán el estado actual de las personalizaciones en Salud. Ahora, veremos un medicamento agregado a Salud y dónde puedes ver sus detalles y personalización. Por ejemplo, agregué amoxicilina a Salud. Iniciarás un tratamiento con antibióticos para combatir una infección. Cuando tu app consulta medicamentos, obtiene un objeto que representa amoxicilina y sus propiedades personalizables. No hay un cronograma establecido para este medicamento, es “según sea necesario”. Le pusiste como apodo “Antibióticos”, ya que eso refleja por qué lo estás tomando. La amoxicilina se representa con un concepto de medicamento. Tiene su identificador único, su nombre es “Amoxicilina Trihidrato 500 mg Tableta Oral”, se fabrica en tabletas. Y hay una única codificación relacionada. Un código RxNorm de 308192. Tu app puede usar este HKUserAnnotatedMedication para crear una experiencia como la que se muestra en la app Salud. Contiene los componentes personalizables y los detalles específicos sobre el medicamento. Tu app consultó los medicamentos en Salud, pero para potenciar las experiencias basadas en cómo se registró, también querrás que tu app obtenga Eventos de dosis. Veamos un ejemplo de un evento de dosis registrada y qué valores puede esperar tu app en estas propiedades. Es importante tomar los antibióticos con regularidad, entonces estableces un cronograma. Se envió un recordatorio para tomar amoxicilina, pero lo omitiste. Al omitir el recordatorio, se guarda un evento de dosis en HealthKit. Tu app iniciará una consulta de eventos de dosis de medicamentos y obtendrá esa muestra en el controlador de resultados. Se omitió el estado de este evento de dosis. Como no se tomó ningún medicamento, la cantidad de dosis es 0. La fecha de inicio de la muestra es la hora seleccionada al realizar el registro. Este evento de dosis es un registro de un evento programado específico. La fecha y la cantidad programadas coinciden con el evento programado. La fecha es la hora en la que se programó el evento y la cantidad es la cantidad que se debería haber tomado. Se guardarán eventos de dosis para cada dosis programada de un medicamento. Finalmente, este evento de dosis está asociado al concepto de medicamento amoxicilina, mediante su identificador de concepto de medicamento. Tu app puede usar HKMedicationDoseEvents para crear experiencias basadas en cómo alguien registró su medicación. Capturan el contexto y los detalles de lo registrado. Vimos los dos objetos que tu app puede usar para incorporar datos de medicamentos, ahora, les mostraré las consultas que tu app puede usar para obtenerlos. Para obtener la lista de medicamentos, tu app debe usar el nuevo descriptor de consulta. Puede obtener la lista de medicamentos activos y archivados de HealthKit. Puedes usar dos nuevos predicados con este descriptor de consulta. Uno para isArchived y otro para hasSchedule. Tu app también puede especificar un límite. Si el descriptor de consulta está configurado con un predicado, tu app solo recibirá medicamentos que coincidan con ese predicado. En este caso, tu app no vería piroxicam, ya que está archivado. Los eventos de dosis son HKSamples, tu app usa las consultas basadas en tipos de muestra existentes para obtenerlos, como consultas de muestra, de objetos anclados y de observador. Al configurar estas consultas, tu app debe usar el nuevo tipo de muestra HKMedicationDoseEvent. También agregamos una variedad de nuevos predicados de consulta para eventos de dosis. Al considerar qué eventos de dosis buscar, es más útil buscarlos por medicación o por estado del registro.

Bien, vimos una descripción general de estas API y algunos ejemplos de datos. Ahora hablemos con Srishti. Creó una app que incorpora datos de medicamentos y dosis de HealthKit. Srishti, me gustaría saber más sobre la app que construiste. Y ver cómo usas la API de medicamentos. ¿Nos contarías más? ¡Por supuesto, Eric! Les mostraré la app que creé. Sirve para visualizar eventos de dosis y registrar efectos secundarios de un medicamento. Lo mostraré en acción. También puedes descargar la app de muestra para esta sesión desde el enlace proporcionado en la página de descripción de la sesión. Cuando abras mi app, verás una lista de medicamentos ya autorizados. Estos son los medicamentos que se agregaron a la app Salud. Cuando hago clic en un medicamento específico, obtengo la dosis que tomé hoy. Lo registré como tomado esta mañana en la app Salud. También puedo ver una lista de efectos secundarios que podría estar experimentando. Estos efectos secundarios son sobre este medicamento específico. Tengo un fuerte dolor de cabeza, seleccionaré ese síntoma y lo marcaré como grave con un emoji. Luego, tocaré el botón Guardar en HealthKit para guardar la muestra. Hicimos un resumen rápido de mi app, ahora profundicemos en los detalles de cómo la armé. Primero lo primero: debemos pedir permiso al usuario para leer y compartir sus datos. Mi app usa la API de autorización por objeto de HealthKit para solicitar acceso de lectura a los datos de medicamentos, ya que estos son objetos, no muestras. Esta solicitud está incrustada en una vista de IU de Swift. Luego, configuré mi solicitud con una tienda de salud y un nuevo tipo de objeto, HKUserAnnotatedMedicationType. También usé una variable de estado para indicar cuándo debe activarse la solicitud de autorización. Cuando esta variable de estado cambia a verdadera, el sistema presenta una lista de medicamentos agregados a la app Salud. Los usuarios pueden alternar los medicamentos que desean compartir con mi app y luego tocar Permitir. Luego de revisar la autorización, se llamará al controlador de finalización, así podré manejar cualquier error sin problemas. No necesito solicitar autorización por separado para leer las dosis de medicamentos. Cuando alguien autoriza un medicamento, mi app obtiene automáticamente acceso para leer ese medicamento y sus dosis. En una solicitud separada, mi app también solicitará, leerá y compartirá acceso a muestras de síntomas, como náuseas y dolor de cabeza. Usaré una llamada API similar para la solicitud de acceso a datos de salud. Pero la diferencia aquí es que proporciono una lista de tipos de muestra para leer y compartir en lugar de un solo tipo de objeto. Cambiar la variable de estado a verdadero inicia una solicitud de autorización y muestra una hoja para seleccionar los tipos de datos solicitados para leer y compartir. Se pueden alternar los tipos de síntomas admitidos y tocar Permitir. La finalización de la solicitud de autorización debe realizarse igual, y, si la autorización no fue exitosa, mi app fallará. Luego de determinar las autorizaciones, mi app consultará la lista completa de medicamentos autorizados de HealthKit. Para hacer esto, mi app usa una función asíncrona que entrega una matriz de HKUserAnnotatedMedications. Primero, esta función configura un descriptor de consulta para obtener la lista autorizada de medicamentos. Estos son medicamentos que alguien agregó a Salud. Para esta consulta no es necesario ningún predicado ni límite, ya que queremos obtener medicamentos activos y archivados. Luego, esperaré los resultados del descriptor de consulta, usaré una referencia a una tienda de salud. La clase que implementa esta función es responsable de múltiples consultas, así mantiene una referencia a una tienda de salud como una variable de instancia. Mi app solo verá medicamentos que hayan recibido autorización. Si tengo resultados de la consulta, tomaré la lista de medicamentos de esta función y los usaré para completar la vista principal de mi app. Cuando alguien haga clic en un medicamento, necesitaremos realizar otra consulta para obtener los eventos de dosis para la vista de detalles del medicamento. Esta vez necesitamos consultar un evento de dosis de medicamento que se registró hoy. Ahora, veremos cómo configuro mi descriptor de consulta para obtener el evento de dosis más reciente. Para obtener la dosis más reciente, escribí una función que acepta un HKMedicationConcept y devuelve un único HKMedicationDoseEvent opcional. Si no se registran dosis para hoy, este evento de dosis para ese medicamento será nulo. Configuré un predicado compuesto para limitar mis resultados, ya que me interesan los eventos de dosis de esa medicación, las dosis que se registraron hoy y que tienen el estado de tomadas. Para ver más detalles sobre cómo configuré este predicado de muestra, echa un vistazo a la app de muestra. Luego configuré el resto del descriptor de consulta de muestra y devolví el primer objeto de los resultados esperados. Los descriptores de clasificación y el límite garantizarán que mis resultados solo tengan la dosis registrada más reciente que coincida con mis predicados. Luego de recuperar la dosis de hoy, uso su fecha de inicio para configurar mi mosaico de dosis. Si no hay ninguna dosis registrada para hoy, no mostraré nada.

Mi app obtuvo con éxito medicamentos y eventos de dosis de HealthKit. Ahora quiero mostrar una lista de efectos secundarios relevantes asociados con un medicamento específico. Para lograr esto, investigué qué efectos secundarios tiene cada medicamento.

Cualquier medicamento puede tener una lista de efectos secundarios, y HealthKit tiene tipos de categorías que reflejan algunos de estos síntomas, como dolor de cabeza, náuseas y más. Para mi investigación, asocié los códigos en un sistema llamado RxNorm con un modelo de síntomas que captura el nombre del síntoma y el identificador del tipo de categoría. RxNorm codifica los medicamentos clínicos como identificadores únicos que representan un concepto individual. Codifiqué las asociaciones que investigué en una estructura estática en mi app. Veamos cómo relacioné un medicamento con una lista de tipos de muestras de efectos secundarios con códigos RxNorm. Primero, echemos un vistazo al diagrama que Eric mostró al comienzo, usé la propiedad de codificaciones relacionadas en HKMedicationConcept. Contiene un conjunto de codificaciones clínicas que representan este medicamento. Una codificación clínica es un código contextualizado en un sistema. Estos códigos representan conceptos médicos específicos, como alergias, afecciones, en nuestro caso, medicamentos. Los sistemas se identifican según la terminología oficial FHIR. El sistema que me interesa, RxNorm, se identifica con la siguiente URL de forma única. Encuentra más información sobre cómo ajustar estas codificaciones en nuestra documentación para desarrolladores. Ahora veamos cómo uso el sistema RxNorm en mi app. Decidí mejorar mi estructura de efectos secundarios para que coincida con los efectos secundarios conocidos de un medicamento específico. Lo primero que hice fue agregar una constante para el sistema RxNorm. Luego, ingresé una función para recuperar tipos de síntomas para un HKMedicationConcept. Esta función hace coincidir los códigos RxNorm de un medicamento con los modelos de síntomas mediante los datos de mi diccionario estático. Usé la función estática SideEffects para obtener todos los síntomas asociados al medicamento y luego los mostré en la vista de detalles del medicamento. Como mi app ahora tiene un conjunto de síntomas para un medicamento, implementé una experiencia para registrar los síntomas. Mi forma favorita de representar y registrar la intensidad de los síntomas es con emojis. En principio, elegí estos 5 emojis que representan un síntoma o sensación, de nada a muy fuerte. Luego, creé una nueva enum llamada SymptomIntensity. Quiero convertir esta intensidad en una muestra de categoría para guardar en HealthKit, así que asocié sus casos a un valor de categoría correspondiente. Para unir todo, escribí una función que crea una muestra para un tipo de categoría y una SymptomIntensity. Guardaré la muestra con el método de guardado existente en la tienda de Salud. Ahora, cuando toco un síntoma, aparece un selector de emojis. Puedo elegir un emoji para representar la intensidad de mi síntoma y guardarlo en HealthKit así de fácil. ¡Esa es mi app hasta ahora! Repasé las diferentes experiencias que creé y las diferentes consultas de medicamentos que mi app usa para obtener los datos. También vimos cómo usé el sistema RxNorm para asociar síntomas y mostrarlos en mi app.

Estoy pensando en agregar una nueva experiencia de gráficos, para dar seguimiento de mis dosis de medicamentos registradas en el tiempo. Eric, pensaba usar una consulta de objeto anclado para observar y obtener los datos subyacentes y luego completar mis gráficos. ¿Qué piensas? ¡Muchas gracias por esa fantástica descripción general! Una consulta de objeto anclado sería perfecta para tu experiencia con gráficos. Tu gráfico se puede actualizar sin problemas cuando hay nuevas dosis guardadas en HealthKit.

Es importante tener cuidado al usar una consulta de objeto anclado para datos de eventos de dosis. Los eventos de dosis se pueden registrar para días pasados, eliminados y reiterados al editar, o se pueden guardar como recordatorios con los que nunca se interactuó. Si se maneja incorrectamente, podrían parecer datos inconsistentes. Hagamos un repaso de las consultas de objetos anclados y algunas prácticas recomendadas para tener en cuenta. Cuando tu app ejecuta una consulta de objeto anclado, recibirá una instantánea de las muestras existentes. Si hay una actualización, tu app recibe un conjunto adicional de resultados, que pueden contener eliminaciones de muestras que tu app ya procesó.

Las consultas de objetos anclados se pueden usar de formas diferentes. Son una forma eficiente de garantizar que tu app reciba nuevos datos agregados a HealthKit. Recuerda que las consultas de objetos anclados son útiles para obtener datos con respecto al ancla de consulta proporcionada. Si ya se obtuvieron datos de una consulta de objeto anclado, usa el ancla de consulta devuelto para asegurarte de que tu app no procese los mismos datos de nuevo. Si tu app desea iniciar una consulta desde el principio, proporciona nulo para tu ancla de consulta. Tu app debe reflejar los datos de eventos de dosis más recientes agregados a HealthKit. Los eventos de dosis capturan un comportamiento de registro interactivo, podría ser desconcertante para alguien ver datos obsoletos en tu app. Usa consultas ancladas para mantener continuamente actualizados los datos de tus apps, de modo que coincidan con lo que se muestra en Salud. En general, el uso de consultas de objetos anclados es más eficiente que configurar una consulta de observador emparejada y una consulta de muestra. Por último, hay una interfaz asincrónica rápida para consultas de objetos anclados. Esta interfaz ofrece un flujo de resultados que se puede usar con async-await en Swift. Si no usaste una consulta de objeto anclado antes o si deseas más información y ejemplos, consulta nuestra documentación de Apple Developer. Y puedes ver la charla de la WWDC “Cómo empezar a usar HealthKit”.

Veamos cómo Srishti usa una consulta de objeto anclado para obtener datos para sus gráficos. Srishti, ¿puedes mostrarnos cómo implementas esta consulta?

¡Por supuesto! Uso el mismo predicado para obtener dosis por medicación y por estado del registro, y reemplazo el predicado de hoy por uno que coincide con dosis dentro de la ventana de fecha de mi gráfico. También necesitaré dar seguimiento de cómo se actualizan los datos de mi app. Para configurar mi consulta de objeto anclado, comenzaré configurando mi consulta como la consulta de muestra que creé antes. Usaré el mismo predicado para obtener dosis por medicación y por estado del registro, pero reemplazo el predicado de hoy por uno que coincide con las dosis que está dentro de la ventana de fecha de mi gráfico. Para ver más detalles sobre cómo configuré este predicado, echa un vistazo a la app de muestra. Proporcionaré nulo para el ancla, ya que quiero comenzar desde el principio de todos los eventos de dosis registrados. Uso una interfaz asíncrona rápida para ejecutar la consulta en un hilo en segundo plano. Cuando obtenga los resultados de la consulta, los procesaré en una función separada para actualizar el modelo de datos de mi app. Haré esto en una nueva función llamada handleResult. Primero necesito obtener los objetos eliminados del resultado y limpiar cualquier dato que se eliminó. Luego, necesitaré actualizar mi conjunto de puntos del gráfico con las nuevas muestras agregadas. Para ver más detalles sobre cómo administré mis puntos gráficos, echa un vistazo a la app de muestra. Ahora, veamos la IU y cómo se actualizan mis gráficos cuando se guardan nuevos datos. Este es mi gráfico, el eje X representa días individuales y el eje Y representa la cantidad de dosis tomadas de un medicamento. Puedes elegir diferentes medicamentos en la vista de desplazamiento horizontal. En mi reloj voy a marcar mi dosis en la app Medicamentos. Como uso una consulta de objeto anclado para verificar constantemente si hay nuevos datos, mi gráfico se actualiza automáticamente con los nuevos datos que registré en mi reloj. ¡Estoy emocionada con el resultado de mis gráficos! Mostrará los datos más recientes guardados en HealthKit, lo cual es muy útil para controlar las dosis registradas en el tiempo. Pero Eric, ¿qué pasa cuando agrego un nuevo medicamento a la app Salud? Esa es una buena pregunta. Todo lo que vimos hasta ahora fue basado en que tu app tiene autorización determinada para todos los medicamentos agregados a Salud.

Supongamos que tu app se instaló y autorizó correctamente para los datos de medicamentos. Alguien que usa tu app ahora quiere agregar un nuevo medicamento a su lista activa. Quiere que su nuevo medicamento aparezca junto con sus otros medicamentos activos, entonces, volverá a la app Salud para agregarlo. Buscará el medicamento que desea agregar y lo personalizará. Antes de agregarlo a su lista, hay un paso final. Como la app ya solicitó acceso a los medicamentos, Salud le presentará al usuario un interruptor donde podrá seleccionar tu app para compartirlo. Esto es como solicitar autorización, pero desde dentro de la app Salud y no requiere ningún trabajo adicional por parte de tu app. Cuando seleccione tu app, guardará sus medicamentos en Salud. Cuando regrese a tu app, podrá ver el medicamento recién agregado. Administrar la autorización así hace que sea sencillo y sin complicaciones para tu app y los usuarios. ¡Así que esa es la API de medicamentos! Desde personalizaciones únicas hasta dosis a lo largo del tiempo: tu app tiene todo lo que necesitas para crear una excelente experiencia con los datos de medicamentos. Todo se conecta mediante un concepto de medicación específico, que puede relacionarse con otros datos clínicos. Pensemos un poco en todas las experiencias que pueden permitir a las personas entender cómo los medicamentos que toman afectan su salud. Espero que puedas encontrar formas interesantes de incorporar medicamentos en tu app.

Antes de irnos, hay algunas cosas que debes saber. Apenas vimos un poco de la app de muestra, y puedes tomar muchas direcciones con ella. Descarga la app de muestra y mira el código de ejemplo para iniciar el desarrollo de tus apps. Para aprovechar aún más la API de HKMedicationConcept, profundiza en los sistemas de codificación clínica como RxNorm para categorizar e identificar medicamentos y asociarlos con datos reveladores, como efectos secundarios o contenido educativo. Consulta nuestra documentación para desarrolladores para más información sobre lo que significan los diferentes estados de registro, más predicados de consulta y otras capacidades de HKMedicationDoseEvent. Por último, no te pierdas nuestra otra charla para desarrolladores: “Descubre los entrenamientos en iOS”. ¡Gracias por explorar la API de medicamentos aquí hoy! Ansiamos ver lo próximo que crees. ¡Cuéntanos qué piensas de estas nuevas API en el Asistente de comentarios! ¡Gracias por acompañarnos!