Découvrez l’API Medications de HealthKit

Bonjour ! Je m’appelle Eric et je suis développeur iOS au sein de l’équipe Santé. Aujourd’hui, je vais vous présenter les nouvelles API de traitements médicaux ajoutées à HealthKit pour offrir des expériences optimales sous iOS, iPadOS et visionOS. Bonjour. Je m’appelle Srishti Gupta, également ingénieure logiciel dans l’équipe Santé. Aujourd’hui, je vais vous montrer une app que j’ai créée et qui utilise les nouvelles API qu’Eric va présenter.

Commençons par la nouvelle API HealthKit qui permet à votre app de lire les données des traitements. Je vous montrerai aussi à quoi ressemblent ces données dans Santé. Ensuite, Srishti vous présentera un exemple d’app qui utilise ces API.

Puis nous passerons en revue les requêtes d’objets ancrées et la manière dont Santé aidera votre app à gérer l’autorisation des traitements récemment ajoutés. Avant de détailler les nouvelles API, je vais vous montrer comment les données des traitements sont ajoutées à HealthKit.

Dans iOS 15, le suivi des traitements a été ajouté à l’app Santé. Vous pouvez le trouver sous l’onglet Rechercher de Santé. Touchez Traitements pour commencer. La vue Traitements s’affichera. Pour ajouter un traitement ; si ce n’est pas déjà fait ; touchez "Ajouter un traitement". Lorsque vous ajoutez un traitement, vous devez d’abord le rechercher. Bon nombre de médicaments portent le même nom, mais ils peuvent avoir des concentrations différentes et se présenter sous différentes formes. Une fois que vous avez sélectionné un médicament, vous pouvez aussi configurer un calendrier de rappels pour vous aider à le prendre correctement. Vous pouvez aussi ajouter des détails pour personnaliser la fiche. Lorsque vous aurez terminé, le médicament sera ajouté à votre liste.

Vous pouvez enregistrer vos traitements à tout moment. Chaque fois, vous pouvez choisir la quantité prise et le moment de la prise. Lorsque le système affiche une notification vous rappelant d’enregistrer vos traitements, vous pouvez choisir l’option « Pris », « Ignoré » ou reporter de 10 minutes. Que vous ajoutiez des traitements ou enregistriez des prises, vos données sont stockées en toute sécurité dans HealthKit. Désormais, vos apps peuvent récupérer davantage de données de HealthKit. Nous ajoutons la possibilité de lire les traitements et les prises. L’objet qui représente les traitements s’appelle HKUserAnnotatedMedication. HKMedicationDoseEvent représente les prises enregistrées pour un médicament. C’est un nouveau type de HKSample. Votre app récupère des données de HealthKit avec des descripteurs de requête et des HKQueries. Nous en introduisons de nouveaux pour récupérer les traitements. Il s’agit de HKUserAnnotatedMedicationQueryDescriptor et HKUserAnnotatedMedicationQuery. D’abord, parlons des deux objets qui représentent les traitements et les prises. UserAnnotatedMedication représente un traitement spécifique et ses personnalisations. Celles-ci sont composées de quatre propriétés. isArchived indique qu’un traitement est terminé ou qu’il n’est plus pris. Ces traitements sont soigneusement rangés dans une section archivée et n’apparaissent pas dans la liste des traitements en cours. hasSchedule indique si un programme de rappels est configuré pour un médicament. Si oui, le système affichera des notifications pour enregistrer les prises du médicament. nickname est une désignation du médicament plus simple que son nom scientifique. nickname permet de personnaliser la gestion des traitements, de la rendre plus conviviale. medication est une référence au médicament réellement pris. Un HKMedicationConcept incarne ce médicament spécifique. Nous appelons cela un concept de médicament, car ce n’est que l’idée conceptuelle, pas quelque chose comme un dossier d’ordonnance. L’identifier de chaque concept de médicament est unique. Ainsi, votre app peut identifier, de manière fiable, un médicament sur différents appareils et dans le temps. displayText représente le nom du médicament. generalForm indique la forme physique du médicament : gélule, comprimé, liquide… Ces différentes formes peuvent impliquer différentes voies d’administration. Les relatedCodings contiennent un ensemble de codes cliniques associés à ce médicament. Ces codes peuvent provenir de terminologies standardisées comme RxNorm. Cela permet une interopérabilité avec d’autres systèmes de santé et une meilleure identification et catégorisation des médicaments. Les DoseEvents représentent les moments où un médicament devait être pris ou a été pris. Ils représentent un nouveau type de HKSample. Ils sont toujours liés à un médicament spécifique, par son medicationConceptIdentifier. Ils contiennent également le logStatus, comme Pris ou Ignoré. Les prises programmées peuvent aussi être reportées ou laissées en suspens. Dans ce cas, les prises enregistrées présenteront l’état d’enregistrement correspondant. Chaque DoseEvent stocke aussi la dose de médicament enregistrée. Les DoseEvents programmés contiendront la date et la dose programmées. Si scheduledQuantity diffère de doseQuantity, cela signifie qu’il y a une différence entre ce qui devait être pris et ce qui a été pris réellement. Je reprends : les DoseEvents sont liés à un médicament. Le medicationConceptIdentifier est identique à la propriété identifier d’un MedicationConcept. Votre app va récupérer les HKUserAnnotatedMedications auprès de HealthKit. Quand votre app les demande, ils représentent l’état actuel des personnalisations dans Santé. Je vais maintenant vous montrer un traitement ajouté à Santé et où vous pouvez en voir les détails et les personnalisations. Disons que vous avez ajouté l’amoxicilline à Santé. Vous êtes sur le point de prendre un traitement antibiotique contre une infection. Lorsque votre app demande des médicaments, elle obtient en retour un objet représentant l’amoxicilline et ses propriétés personnalisables. Il n’y a pas de programme établi pour ce médicament, il est pris « Au besoin ». Et le surnom que vous lui avez donné est « Antibiotique ». L’amoxicilline est représentée par un concept médicamenteux. Il a son propre identifiant unique, son nom est « Amoxicillin Trihydrate 500mg Oral Tablet », il est fabriqué sous forme de comprimé. Et il y a un seul codage associé. Un code RxNorm de 308192. Votre app peut utiliser ce HKUserAnnotatedMedication pour créer une expérience similaire à celle présentée dans l’app Santé. Il contient les composants personnalisables et les détails spécifiques sur le médicament. Votre app a demandé les traitements dans Santé. Pour des expériences optimales, basées sur la façon dont ces traitements ont été enregistrés, elle voudra aussi récupérer les DoseEvents. Je vais vous présenter un exemple de prise enregistrée et vous montrer les valeurs que votre app peut attendre au sujet de ces propriétés. Les antibiotiques doivent être pris régulièrement, donc vous établissez un programme. Un rappel a été envoyé pour prendre l’amoxicilline, mais vous l’avez ignoré. Lorsque vous avez ignoré ce rappel, un DoseEvent a été enregistré dans HealthKit. Votre app demandera les medicationDoseEvents et récupèrera cet échantillon dans le gestionnaire de résultats. L’état de ce DoseEvent est « skipped ». Comme aucun médicament n’a été pris, doseQuantity indique 0. La date de début de l’échantillon est l’heure sélectionnée lors de l’enregistrement. Ce DoseEvent est un enregistrement d’une prise programmée spécifique. La date et la dose planifiées correspondent à la prise planifiée. La date est l’heure à laquelle la prise a été fixée et la dose est celle qui aurait dû être prise. Des DoseEvents seront enregistrés pour chaque prise programmée d’un médicament. Enfin, ce DoseEvent est associé au concept de médicament de l’amoxicilline, par son medicationConceptIdentifier. Votre app peut utiliser les HKMedicationDoseEvents pour créer des expériences basées sur la façon dont une personne a enregistré ses traitements. Ils capturent le contexte et les détails de ce qui a été enregistré. Après les deux objets que votre app peut utiliser pour incorporer les données de traitement, je vais vous montrer les requêtes qu’elle peut utiliser pour les récupérer. Pour récupérer la liste des médicaments, votre app doit utiliser le nouveau descripteur de requête. Il va permettre de récupérer la liste des traitements en cours et archivés de HealthKit. Vous pouvez utiliser deux nouveaux prédicats avec ce descripteur de requête. Un pour isArchived et un pour hasSchedule. Votre app peut également définir une limite. Si le descripteur de requête est configuré avec un prédicat, elle ne recevra que les médicaments qui correspondent à ce prédicat. Dans ce cas, votre app ne verra pas le piroxicam, puisqu’il est archivé. Les DoseEvents sont des HKSamples. Votre app peut utiliser n’importe quelle requête basée sur des types d’échantillons pour les récupérer, par exemple, requêtes d’échantillons, requêtes d’objets ancrées et requêtes d’observateurs. Lors de la configuration de ces requêtes, votre app doit utiliser le nouveau type d’échantillon HKMedicationDoseEvent. Nous avons aussi introduit de nouveaux prédicats de requête pour les DoseEvents. Concernant la récupération des DoseEvents, il est plus utile de le faire par médicament ou par état du journal.

Maintenant que je vous ai présenté ces API et quelques exemples de données, tournons-nous vers Srishti. Elle a créé une app qui intègre les données des traitements et prises de HealthKit. Srishti, je suis curieux d’en savoir plus sur l’app que tu as créée. J’aimerais aussi voir comment tuutilises l’API des traitements. Tu veux bien nous montrer tout cela ? Bien sûr, Eric ! L’app que j’ai créée permet de visualiser les prises et d’enregistrer les effets secondaires d’un médicament. Je vais vous la montrer en action. Vous pouvez aussi télécharger l’exemple d’app à partir du lien fourni dans la page de description de la séance. Lorsque vous ouvrez mon app, vous voyez une liste des médicaments déjà autorisés. Ce sont les médicaments qui ont été ajoutés à l’app Santé. Lorsque je touche un médicament, je vois la prise la plus récente du jour. Je l’ai enregistré comme pris ce matin dans l’app Santé. Je peux aussi voir une liste des effets secondaires que je pourrais ressentir. Ces effets secondaires sont liés à ce médicament précis. Comme j’ai très mal à la tête, je vais sélectionner ce symptôme et le marquer comme intense en sélectionnant un emoji. Ensuite, je touche le bouton « Enregistrer dans HealthKit » pour enregistrer. Après ce bref aperçu de mon app, détaillons la façon dont je l’ai créée. D’abord, il faut demander à l’utilisateur l’autorisation de lire et de partager ses données. Mon app utilise l’API d’autorisation par objet HealthKit pour demander l’accès en lecture aux données des traitements, car ce sont des objets, pas des échantillons. Cette demande est intégrée dans une vue de l’interface utilisateur Swift. Ensuite, j’ai configuré ma demande avec un healthStore et un nouveau type d’objet, HKUserAnnotatedMedicationType. J’ai aussi utilisé une variable d’état pour indiquer quand l’invite d’autorisation doit être déclenchée. Quand cette variable d’état est remplacée par « true », le système affiche une liste des médicaments ajoutés à l’app Santé. Les utilisateurs peuvent choisir les médicaments à partager, puis toucher « Autoriser ». Une fois l’autorisation examinée, le gestionnaire de saisie semi-automatique est appelé, ce qui me permet de gérer les erreurs élégamment. Inutile de demander l’autorisation de lire les prises des médicaments. Lorsqu’une personne autorise un médicament, mon app est automatiquement autorisée à lire ce médicament et ses prises. Dans une demande distincte, mon app demandera, lira et partagera aussi l’accès aux échantillons de symptômes comme des nausées, des maux de tête. J’utiliserai un appel d’API similaire pour la demande d’accès aux données de santé. La différence est que je fournirai une liste de types d’échantillons à lire et à partager au lieu d’un seul type d’objet. La modification de la variable d’état sur « true » lance une demande d’autorisation, affichant une fiche de sélection des types de données pouvant être lus et partagés. Les utilisateurs peuvent choisir les types de symptômes, puis toucher Autoriser. La réalisation de cette demande d’autorisation doit être traitée de la même manière afin que mon app se comporte avec élégance si l’autorisation n’est pas accordée. Une fois les autorisations obtenues, mon app demande la liste complète des médicaments autorisés à HealthKit. Pour ce faire, mon app utilise une fonction asynchrone qui renvoie un tableau de HKUserAnnotatedMedications. D’abord, cette fonction configure un descripteur de requête pour récupérer la liste des médicaments autorisés, ceux que quelqu’un a ajoutés à Santé. Pour cette requête, aucun prédicat ni aucune limite n’est nécessaire, car nous voulons récupérer à la fois les médicaments en cours et archivés. J’attends les résultats du queryDescriptor, en utilisant une référence à un healthStore. La classe qui implémente cette fonction est responsable de plusieurs requêtes. Elle conserve donc une référence à un healthStore en tant que variable d’instance. Mon app ne verra que les médicaments autorisés par une personne. Si j’ai des résultats de requête, je prends la liste des médicaments de cette fonction et les utilise pour remplir la vue principale de mon app. Quand quelqu’un touche un médicament, nous devons effectuer une autre requête pour récupérer les DoseEvents pour la vue détaillée du médicament. Cette fois, nous devons demander un medicationDoseEvent enregistré aujourd’hui. Je vais vous montrer comment j’ai configuré mon descripteur de requête pour récupérer le dernier DoseEvent. Pour récupérer la dernière prise, j’ai écrit une fonction qui accepte un HKMedicationConcept et renvoie un seul HKMedicationDoseEvent facultatif. Si aucune prise n’est enregistrée aujourd’hui, ce DoseEvent pour ce médicament sera nul. J’utilise un CompoundPredicate pour liermes résultats car je cherche des DoseEvents pour ce médicament, les prises enregistrées aujourd’hui et dont l’état est « Pris ». Pour en savoir plus sur la configuration de ce prédicat, consultez l’exemple d’app. Ensuite, j’ai configuré le reste de mon descripteur de requête et renvoyé le premier objet des résultats attendus. Les descripteurs de tri et la limite garantiront que mes résultats ne présentent que la prise la plus récemment enregistrée correspondant à mes prédicats. Après avoir récupéré la prise du jour, j’utilise sa date de début pour configurer ma vignette de prise. S’il n’y a pas de prise enregistrée pour aujourd’hui, je n’affiche rien.

Mon app a récupéré les traitements et DoseEvents auprès de HealthKit. Je veux afficher une liste des effets secondaires associés à un médicament spécifique. Pour ce faire, j’ai fait des recherches sur les médicaments et leurs effets secondaires.

Tout médicament peut avoir des effets secondaires, et HealthKit utilise des catégories qui reflètent certains d’eux : maux de tête, nausées, etc. Lorsque j’ai fait mes recherches, j’ai associé les codes du système RxNorm à un modèle de symptôme qui capture le nom du symptôme et l’identifiant de catégorie. RxNorm donne aux médicaments des identifiants uniques qui représentent un concept individuel. J’ai encodé les associations que j’ai trouvées dans une structure statique de mon app. Je vais vous montrer comment j’ai lié un médicament à une liste de types d’effets secondaires via les codes RxNorm. D’abord, reprenons le schéma d’Eric. J’ai utilisé la propriété relatedCodings de HKMedicationConcept. Elle contient un ensemble de codifications cliniques qui représentent ce médicament. Une codification clinique est un code contextualisé dans un système. Ces codes représentent des concepts médicaux spécifiques comme des allergies, des affections et, dans notre cas, des médicaments. Les systèmes sont identifiés selon la terminologie FHIR officielle. Le système qui m’intéresse, RxNorm, a l’URL suivante qui l’identifie de manière unique. Pour en savoir plus sur la façon dont nous modélisons ces codifications, consultez notre documentation de développement. Maintenant, je vais vous montrer comment j’utilise le système RxNorm dans mon app. J’ai amélioré la structure des effets secondaires pour faire correspondre ceux qui sont connus à un médicament spécifique. Premièrement, j’ai ajouté une constante pour le système RxNorm. Puis j’ai introduit une fonction pour récupérer les types de symptômes pour un HKMedicationConcept. Cette fonction fait correspondre les codes RxNorm d’un médicament aux modèles de symptômes en utilisant les données de mon dictionnaire statique. J’ai utilisé la fonction statique SideEffects pour récupérer tous les symptômes associés au médicament, puis je les ai affichés dans la vue détaillée du médicament. Maintenant que mon app a un ensemble de symptômes pour un médicament, je mets en place une expérience pour enregistrer les symptômes. Pour représenter et enregistrer l’intensité des symptômes, je préfère des emojis. Pour commencer, j’ai choisi ces 5 emojis qui représentent un sentiment de symptôme allant de zéro à extrême. Ensuite, j’ai créé un enum appelé SymptomIntensity. Je veux transformer cette intensité en un échantillon de catégories à enregistrer dans HealthKit. J’ai donc associé ses cas à une valeur de catégorie correspondante. Pour lier le tout, j’ai écrit une fonction qui crée un échantillon pour un type de catégorie et une SymptomIntensity. J’enregistrerai l’échantillon en utilisant la méthode existante sur le healthStore. Maintenant, quand je touche un type de symptôme, j’obtiens un sélecteur d’emojis. Je peux choisir un emoji pour représenter l’intensité de mon symptôme et l’enregistrer facilement dans HealthKit. Voilà mon app pour l’instant. J’ai présenté les différentes expériences que j’ai créées et les différentes requêtes de traitement qu’elle utilise pour récupérer les données. J’ai aussi montré comment j’ai utilisé le système RxNorm pour associer des symptômes et les afficher dans mon app. J’envisage aussi d’ajouter une nouvelle expérience de graphiques pour suivre les prises de médicaments enregistrées au fil du temps. Eric, je pensais utiliser une requête d’objet ancrée pour observer et récupérer les données sous-jacentes, puis remplir mes graphiques. Qu’en penses-tu ? Merci beaucoup pour cette impressionnante présentation ! Je pense qu’une requête d’objet ancrée serait parfaite pour des graphiques. Ils se mettront à jour facilement quand des prises seront enregistrées dans HealthKit.

Il faut utiliser une requête d’objet ancrée prudemment pour les données de DoseEvent. Des DoseEvents peuvent être enregistrés pour des jours passés, supprimés, puis récupérés, ou encore enregistrés pour des rappels laissés sans suite. Une mauvaise gestion peut générer des données semblant incohérentes. Voici un rappel sur les requêtes d’objets ancrées et quelques bonnes pratiques à garder à l’esprit. Lorsque votre app exécute une requête d’objet ancrée, elle reçoit un instantané des échantillons existants. Après une mise à jour, votre app reçoit un ensemble supplémentaire de résultats, qui peut contenir des suppressions pour des échantillons qu’elle a déjà traités. Les requêtes d’objets ancrées peuvent être utilisées de toutes sortes de façons. Elles permettent de s’assurer que votre app reçoit les données ajoutées à HealthKit. Les requêtes d’objets ancrées sont utiles pour récupérer des données par rapport à l’ancre de requête fournie. Si vous avez déjà récupéré des données à partir d’une requête d’objet ancrée, utilisez l’ancre de requête renvoyée pour que votre app ne retraite pas les mêmes données. Si votre app souhaite recommencer une requête, indiquez « nil » pour l’ancre de requête. Votre app doit refléter les données de DoseEvent les plus récentes ajoutées à HealthKit. Les DoseEvents capturent le comportement d’enregistrement interactif. Mais les utilisateurs ne veulent pas voir de données obsolètes dans votre app. Veillez à utiliser des requêtes ancrées pour que les données de votre app soient à jour et correspondent à celles de Santé. L’utilisation de requêtes d’objets ancrées est en général plus efficace que la configuration d’une requête d’observateur et d’une requête d’échantillon. Enfin, il existe une interface asynchrone Swift pour les requêtes d’objets ancrées. Cette interface fournit un flux de résultats, utilisable avec Swift async-await. Si vous n’avez jamais utilisé de requête d’objet ancrée ou souhaitez plus d’informations et d’exemples, consultez notre documentation de développement. Regardez aussi notre conférence WWDC « Getting started with HealthKit ».

Voyons comment Srishti va utiliser une requête d’objet ancrée pour récupérer des données pour ses graphiques. Srishti, peux-tu nous montrer comment tu implémentes cette requête ?

Avec plaisir ! La requête que je vais écrire devra uniquement récupérer les prises enregistrées pour un médicament et situées dans la fenêtre de dates du graphique. Je dois également surveiller la façon dont les données de mon app seront mises à jour. Pour configurer ma requête d’objet ancrée, je vais faire comme pour la requête d’échantillon créée précédemment. J’utiliserai le même prédicat pour récupérer les prises par médicament et par état d’enregistrement, mais un autre prédicat pour récupérer les prises qui se situent dans ma fenêtre de dates. Pour en savoir plus sur la configuration de ce prédicat, consultez l’exemple d’app. J’indiquerai «nil » pour l’ancre, car je veux commencer au début de tous les DoseEvents enregistrés. J’utilise une interface asynchrone Swift pour exécuter la requête sur un thread d’arrière-plan. Une fois que j’aurai obtenu les résultats de la requête, je les traiterai dans une fonction distincte pour mettre à jour le modèle de données de mon app. Il s’agit d’une nouvelle fonction appelée handleResult. Je dois d’abord récupérer les objets supprimés du résultat et nettoyer toutes les données qui ont été supprimées. Puis je mettrai à jour l’ensemble de points de graphique avec les échantillons ajoutés. Pour en savoir plus sur la gestion des points de graphique, consultez l’exemple d’app. Maintenant, examinons l’interface utilisateur et la façon dont mes graphiques sont mis à jour quand de nouvelles données sont enregistrées. Voici mon graphique. L’axe X représente les jours et l’axe Y représente le nombre de prises pour un médicament. Vous pouvez choisir différents médicaments dans la vue de défilement horizontal. Sur ma montre, je vais marquer ma prise dans l’app Traitements. Comme j’utilise une requête d’objet ancrée pour vérifier constamment de nouvelles données, mon graphique se met automatiquement à jour par rapport à ma montre. Je suis ravie du résultat de mes graphiques ! Ils afficheront les données les plus récentes enregistrées dans HealthKit. C’est super pratique pour garder un œil sur les prises enregistrées au fil du temps. Mais Eric, que se passe-t-il quand j’ajoute un nouveau médicament à l’app Santé ? Excellente question. Tout ce que nous vous avons montré jusqu’à présent suppose que votre app dispose d’une autorisation pour tous les traitements ajoutés à Santé.

Disons que votre app est installée et autorisée à accéder aux données des traitements. Une personne utilisant votre app souhaite ajouter un traitement à sa liste active. Elle veut que le nouveau traitement apparaisse avec les autres traitements actifs. Elle retourne donc dans l’app Santé pour l’ajouter. Elle cherche le médicament à ajouter et le personnalise. Avant de l’ajouter à sa liste, elle suit une dernière étape. Comme votre app a déjà demandé l’accès aux traitements, l’app Santé présentera à la personne un commutateur lui permettant de sélectionner le partage avec votre app. Cela revient à demander une autorisation, mais à partir de l’app Santé. Votre app n’a rien d’autre à faire. Après avoir sélectionné votre app, la personne enregistre son traitement dans Santé. Quand elle revient sur votre app, elle peut voir le nouveau médicament ajouté. Cette gestion des autorisations facilite la tâche à votre app et à vos utilisateurs. Voilà pour l’API des traitements ! Des personnalisations uniques aux prises dans le temps, votre app a tout ce qu’il faut pour offrir une expérience optimale concernant les données des traitements. Tout est lié via un MedicationConcept que vous pouvez relier à d’autres données cliniques. Imaginez toutes les expériences qui peuvent aider les gens à comprendre l’impact des traitements qu’ils prennent sur leur santé. J’espère que vous trouverez des façons intéressantes d’intégrer les traitements dans votre app.

Avant de vous dire au revoir, voici quelques points intéressants. Notre exemple d’app est limité. Il y a tant de possibilités ! Téléchargez cet exemple et consultez le code pour vous aider à démarrer le développement de vos propres apps. Pour utiliser l’API HKMedicationConcept encore mieux, examinez les systèmes de codification clinique comme RxNorm pour catégoriser et identifier les traitements, puis les associer à des données utiles comme les effets secondaires ou du contenu éducatif. Consultez notre documentation de développement pour en savoir plus sur les différents états d’enregistrement, pour plus de prédicats de requête et pour d’autres fonctionnalités de HKMedicationDoseEvent. Enfin, consultez notre autre vidéo « Meet workouts on iOS ». Merci d’avoir exploré l’API des traitements avec nous aujourd’hui ! Nous sommes impatients de voir ce que vous allez créer. Pensez à nous donner votre avis sur ces nouvelles API via l’assistant d’évaluation ! Merci de votre attention !