rzaripov.kz

Интеграция HealthKit в приложение на Swift

HealthKit — системный слой iOS для хранения и обмена данными о здоровье между совместимыми приложениями. Через него можно работать с шагами, пульсом, тренировками, массой тела, сном, артериальным давлением и другими показателями, если пользователь предоставил соответствующее разрешение.

Интеграция с Apple Health требует более внимательного подхода, чем обычное подключение фреймворка. Приложение должно корректно описывать назначение доступа, обрабатывать отказ пользователя, учитывать ограничения конкретного устройства и не раскрывать чувствительную информацию в журналах или аналитике.

В Swift основным объектом взаимодействия служит HKHealthStore. Он отвечает за запрос разрешений, чтение сохранённых записей и добавление новых данных. Для некоторых сценариев также используются HKWorkoutSession, HKLiveWorkoutBuilder, фоновые обновления и синхронизация с Apple Watch.

Хорошая реализация разделяет работу с HealthKit и пользовательский интерфейс. Такой подход упрощает тестирование, позволяет заменить источник данных в будущем и хорошо сочетается с архитектурами MVVM, Clean Architecture или собственными сервисными слоями.

Подготовка проекта и системные требования

Сначала добавьте HealthKit.framework в проект через раздел Frameworks, Libraries, and Embedded Content. В современных версиях Xcode чаще достаточно импортировать фреймворк в нужном файле:

import HealthKit

В настройках Target необходимо открыть вкладку Signing & Capabilities и добавить capability HealthKit. После этого Xcode создаст соответствующие entitlement-файлы. Без этой настройки приложение может успешно собраться, но вызовы хранилища завершатся ошибкой на устройстве.

В файле Info.plist следует указать понятное описание цели доступа. Для чтения используется ключ NSHealthShareUsageDescription, а для записи — NSHealthUpdateUsageDescription. Текст должен объяснять реальную функцию приложения: например, что данные нужны для отображения динамики тренировок или сохранения результата занятия.

HealthKit доступен на iPhone и Apple Watch, но возможности зависят от платформы и версии системы. Перед вызовом отдельных API полезно проверять HKHealthStore.isHealthDataAvailable(). Симулятор подходит для проверки части логики, однако полноценное поведение датчиков, тренировок и разрешений необходимо тестировать на реальном устройстве.

Запрос разрешений и безопасный доступ

Разрешения запрашиваются отдельно для чтения и записи. Пользователь может разрешить сохранение тренировок, но запретить чтение пульса. Поэтому приложение не должно считать, что один успешный запрос автоматически открывает доступ ко всем типам данных.

Пример базового сервиса:

import HealthKit

final class HealthKitService {
    private let store = HKHealthStore()

    func requestAuthorization() async throws {
        guard HKHealthStore.isHealthDataAvailable() else {
            throw NSError(domain: "HealthKit", code: 1)
        }

        guard
            let stepType = HKObjectType.quantityType(forIdentifier: .stepCount),
            let workoutType = HKObjectType.workoutType()
        else {
            return
        }

        let readTypes: Set<HKObjectType> = [stepType, workoutType]
        let writeTypes: Set<HKSampleType> = [workoutType]

        try await store.requestAuthorization(
            toShare: writeTypes,
            read: readTypes
        )
    }
}

Запрос лучше выполнять в контексте действия пользователя, например после нажатия кнопки подключения Apple Health. Не стоит показывать системное окно сразу после запуска приложения без объяснения пользы. Также важно помнить: отсутствие разрешения на чтение не всегда можно отличить от отсутствия записей, поскольку HealthKit специально ограничивает раскрытие такой информации.

Приложение должно хранить собственное состояние интеграции, но не делать выводы о медицинском статусе человека на основании отказа или пустого результата. При ошибке следует показать понятное сообщение и предоставить путь к настройкам приложения, не блокируя основные функции, которые не зависят от HealthKit.

Модели данных и чтение показателей

Данные HealthKit разделены на несколько основных категорий. Количественные записи представлены объектами HKQuantitySample, категориальные события — HKCategorySample, тренировки — HKWorkout, а коррелированные наборы могут объединять несколько связанных значений. Для каждого типа необходимо использовать правильную единицу измерения.

Данные Идентификатор Тип значения Пример единицы
Шаги stepCount Количественный показатель count()
Пульс heartRate Количественный показатель count/min
Масса тела bodyMass Количественный показатель kg
Тренировка workoutType() Объект тренировки длительность и энергия

Для выборки обычно применяется HKSampleQuery. Запрос можно ограничить временным интервалом, источником или сортировкой по дате. Например, для подсчёта шагов за текущий день сначала создают предикат от начала суток до текущего момента, а затем передают его в HKStatisticsQuery.

func todaySteps() async throws -> Double {
    guard let type = HKObjectType.quantityType(forIdentifier: .stepCount) else {
        return 0
    }

    let start = Calendar.current.startOfDay(for: Date())
    let predicate = HKQuery.predicateForSamples(
        withStart: start,
        end: Date(),
        options: .strictStartDate
    )

    return try await withCheckedThrowingContinuation { continuation in
        let query = HKStatisticsQuery(
            quantityType: type,
            quantitySamplePredicate: predicate,
            options: .cumulativeSum
        ) { _, statistics, error in
            if let error {
                continuation.resume(throwing: error)
                return
            }

            let unit = HKUnit.count()
            let value = statistics?.sumQuantity()?.doubleValue(for: unit) ?? 0
            continuation.resume(returning: value)
        }

        self.store.execute(query)
    }
}

При обработке результата нужно учитывать часовые пояса, переход на летнее время и дубликаты из разных источников. HealthKit объединяет данные от Apple Watch, iPhone и сторонних устройств, поэтому простое сложение отдельных записей может привести к завышенным значениям. Для агрегирования лучше использовать статистические запросы системы.

Запись тренировок и фоновые обновления

Для сохранения завершённой тренировки можно создать объект HKWorkout с видом активности, датами начала и окончания, продолжительностью, дистанцией и энергозатратами. Если приложение отслеживает занятие в реальном времени, используются HKWorkoutSession и HKLiveWorkoutBuilder. Они позволяют получать потоковые значения во время тренировки.

Фоновое обновление строится через HKObserverQuery. После его регистрации приложение получает уведомление об изменении выбранного типа данных и запускает фоновую обработку. В callback необходимо вызвать предоставленный completionHandler, иначе система может ограничить дальнейшие уведомления.

Не каждое обновление требует немедленного сетевого запроса. Практичнее сохранять локальное состояние, обрабатывать изменения небольшими пакетами и использовать HKAnchoredObjectQuery, который возвращает новые и удалённые записи относительно предыдущего anchor. Такой механизм снижает нагрузку и помогает избежать повторной синхронизации.

Для сложных сценариев с Apple Watch нужно учитывать жизненный цикл расширения watchOS, передачу данных через WatchConnectivity и различия между приложением на часах и iPhone. На заблокированном устройстве доступ к некоторым данным может быть временно ограничен настройками защиты хранилища.

Конфиденциальность, тестирование и публикация

Медицинские сведения относятся к особо чувствительной информации. Не следует отправлять в аналитику подробные значения пульса, маршруты тренировок или записи сна без ясно объяснённой необходимости и согласия пользователя. В логах лучше оставлять технические статусы, идентификаторы запросов и типы ошибок без содержимого записей.

Проверяйте сценарии разрешения, отказа, отзыва доступа, отсутствия данных и недоступности HealthKit. Отдельно тестируйте повторный запуск приложения, смену часового пояса, пересекающиеся тренировки и ситуацию, когда данные добавлены другим источником. Для UI-тестов удобно внедрять протокол сервиса и использовать mock-реализацию вместо реального хранилища.

Перед отправкой в App Store проверьте entitlement-файлы, описания в Info.plist, тексты экранов согласия и соответствие заявленных функций фактическому использованию данных. Если приложение предлагает медицинские рекомендации, одного технического подключения HealthKit недостаточно: понадобятся дополнительные юридические и продуктовые проверки.

В прикладном Swift-проекте HealthKit лучше рассматривать как отдельный изолированный модуль. Сервис разрешений, слой запросов, преобразование единиц и обработка ошибок должны быть отделены от экранов. Это делает код предсказуемым, облегчает поддержку разных версий iOS и позволяет безопасно развивать функции мониторинга здоровья.