Как перенести данные платформы "Здоровье и спорт" с Android 13 (APK) на Android 14 (фреймворк)

Платформа "Здоровье и спорт" будет встроена в Android 14 как общее хранилище данных о здоровье и физической активности пользователей. Доступ к нему будет защищен детализированными разрешениями и возможен через системное приложение Android (далее в этом документе – модуль фреймворка).

Разработчикам следует рассматривать APK-файл платформы "Здоровье и спорт" (Android 13) как уровень обратной совместимости для модели фреймворка. Модель фреймворка сохранит 100% паритета функций со своим предшественником APK.

При переходе с Android 13 на Android 14 крайне важно, чтобы пользовательский интерфейс оставался максимально плавным и интуитивно понятным.

В этом документе описан план переноса, приведены примеры сценариев переноса и перечислены изменения в Jetpack SDK, который упрощает доступ к API Здоровья и спорта.

План переноса

  1. После выпуска Android 14 приложение "Здоровье и спорт" станет системным.
  2. Когда паритет функций будет достигнут, данные будут дополнены из APK.
  3. Все точки входа будут вести на интерфейс системного приложения.
  4. Начнется перенос данных. Пока выполняется перенос, API модулей будут приостановлены со статусом "Выполняется перенос". Это также будет видно в интерфейсе платформы "Здоровье и спорт".
  5. После завершения переноса APK-файл можно удалить.

Примеры сценариев переноса

Ниже приведены примеры сценариев, описывающих процесс переноса данных типов interval и series.

Пример 1. Бег (интервальные данные)

Пользователь собирал данные о своих пробежках в течение 10 лет. Он бегал по часу каждый день. Это равносильно следующему:

  • Записи о тренировках: 365 * 10 * 1
  • Шаги: 365 * 10 * 1
  • Калории: 365 * 10 * 1
  • Итого: 365 * 10 * 3 (365 * 30) = 10 950.

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

Наше внутреннее тестирование подтвердило, что на вставку типичного фрагмента уходит примерно секунда, поэтому данные в примере будут перенесены примерно за 4 секунды.

Пример 2. Пульс (серия данных)

Пользователь собирал данные о пульсе в течение пяти лет (запись создавалась каждую минуту). Всего у него 2 628 000 записей.

Если в каждом фрагменте будет по 3000 записей, то данные будут распределены по 876 фрагментам. Учитывая, что на вставку одного фрагмента уходит примерно секунда, перенос данных займет менее 15 минут.

Предлагаемый процесс переноса

Мы решили выбрать мгновенный перенос. На практике это означает, что APK станет неактивным, как только устройство будет обновлено до Android 14, при минимальном вмешательстве пользователя.

Вот как выглядит процесс переноса:

  1. Пользователь обновляет устройство до Android 14.
  2. Jetpack 14 перенаправляет пользователя к API модулей и блокирует их на время переноса.
  3. Перенос начинается, когда версия модуля совместима с APK по набору функций, то есть содержит тот же набор функций или больше. После запуска процесса переноса APK-файл переносит разрешения и данные.
    1. Если версии несовместимы, версию модуля нужно будет обновить. После завершения обновления начнется процесс переноса.
  4. После завершения переноса статус меняется на "Перенос завершен", а API модуля разблокируются.
  5. Теперь APK-файл можно удалить.

Элементы интерфейса переноса

Перед переносом и во время него модуль фреймворка показывает пользователю следующие экраны:

Рисунок 1. Если APK-файл платформы "Здоровье и спорт" не поддерживает перенос, пользователю будет предложено обновить его. Если пользователь откажется от обновления, модуль продолжит работать и начнет накапливать разрешения и данные.

Изображение телефона с надписью "Требуется обновление"
Рисунок 1. Предложение обновить APK-файл платформы "Здоровье и спорт".

Рисунок 2. Если для совместимости с функцией требуется обновить модуль фреймворка, пользователю будет предложено выполнить обновление и перезагрузить устройство. Если пользователь откажется от обновления, модуль продолжит работать и начнет накапливать разрешения и данные.

Изображение, показывающее, что нужно обновить APK-файл
Рисунок 2. Предложение обновить модуль фреймворка.

Рисунок 3. Во время переноса данных на экране будет показываться индикатор выполнения и текст о том, что выполняется синхронизация.

Иллюстрация синхронизации данных
Рисунок 3. Перенос данных.

Данные без дубликатов

Если модуль фреймворка начал получать данные и разрешения до переноса или облачного восстановления, действуют следующие правила:

Разрешения

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

Данные

При переносе дублирующиеся данные из APK игнорируются. Приоритет отдается более новым данным из модуля.

Если клиент предоставляет идентификатор записи, то в clientRecordId выполняется дедупликация данных. Если нет, то в качестве ключа используются временные интервалы (startTime и endTime для внутренних записей и time для мгновенных записей), а также тип данных и название пакета приложения.

Изменения в Jetpack SDK

Jetpack SDK служит общей точкой интеграции как для APK-файла платформы "Здоровье и спорт", так и для API фреймворка.

OEM-производители могут начать интеграцию с Jetpack 13, чтобы после выхода Jetpack 14 вы могли использовать новую библиотеку и компилировать ее в Android 14.

Мы выпустим новую версию SDK, которая поддерживает переход на Android 14. Чтобы переход прошел без проблем, вам нужно будет внести некоторые изменения в существующую интеграцию.

Декларация разрешений

В Android 13 разрешения объявляются в специальном формате в файле ресурсов, связанном с манифестом.

#AndroidManifest.xml

<activity>
    android:name=".RationaleActivity"
    android:exported="true">
    <intent-filter>
        <action android:name="androidx.health.ACTION_SHOW_PERMISSIONS_RATIONALE"/>
    </intent-filter>
    <meta-data
        android:name="health_permissions"
        android:resource="@array/health_permissions"/>
</activity>

<queries>
    <package android:name="com.google.android.apps.healthdata" />
</queries>

#health_permissions.xml

<resources>
  <array name="health_permissions">
    <item>androidx.health.permission.SleepSession.READ</item>
    <item>androidx.health.permission.SleepStage.READ</item>
    <item>androidx.health.permission.Weight.READ</item>
    <item>androidx.health.permission.Weight.WRITE</item>
  </array>
</resources>

Чтобы обеспечить поддержку Android 14, разработчикам необходимо перейти на стандартный формат разрешений:

#AndroidManifest.xml

<uses-permission android:name=”android.permission.health.READ_SLEEP” />
<uses-permission android:name=”android.permission.health.READ_WEIGHT” />
<uses-permission android:name=”android.permission.health.WRITE_WEIGHT” />

<activity>
    android:name=".RationaleActivity"
    android:exported="true">
    <intent-filter>
        <action android:name="androidx.health.ACTION_SHOW_PERMISSIONS_RATIONALE" />
    </intent-filter>
</activity>

<queries>
    <package android:name="com.google.android.apps.healthdata"/>
</queries>

Открыть сервис "Здоровье и спорт"

В большинстве сторонних приложений есть кнопка, которая открывает приложение "Здоровье и спорт", например кнопка "Управление доступом" в Fitbit.

В Android 13 приложение "Здоровье и спорт" можно открыть, используя название пакета или действие androidx.health.ACTION_HEALTH_CONNECT_SETTINGS.

В Android 14 необходимо использовать действие intent, указанное в Jetpack SDK. Его значения зависят от версии Android, в которой оно выполняется:

@get:JvmName("getHealthConnectSettingsAction") @JvmStatic val ACTION_HEALTH_CONNECT_SETTINGS

Как получить клиент Health Connect

Мы создали единый API под названием sdkStatus, доступный в Jetpack 11, который заменит два других устаревших API – IsSdkSupported() и isProviderAvailable().

Изменения в API для записи сеансов

В версии alpha10 удалены четыре подтипа ExerciseSession:

  • ExerciseEvent
  • ExerciseLaps
  • ExerciseRepetitions
  • SwimmingStrokes

Как и ExerciseSessionRecord, SleepStage станет подтипом SleepSession.

Оба подтипа ExerciseSessionRecord и изменения SleepSession будут выпущены в рамках апрельского обновления SDK.

Обновление типа тренировки

Следующие типы тренировок больше не будут поддерживаться, но позже будут добавлены как типы сегментов:

  • EXERCISE_TYPE_BACK_EXTENSION
  • EXERCISE_TYPE_BARBELL_SHOULDER_PRESS
  • EXERCISE_TYPE_BENCH_PRESS
  • EXERCISE_TYPE_BENCH_SIT_UP
  • EXERCISE_TYPE_BURPEE
  • EXERCISE_TYPE_CRUNCH
  • EXERCISE_TYPE_DEADLIFT
  • EXERCISE_TYPE_DUMBBELL_CURL_LEFT_ARM
  • EXERCISE_TYPE_DUMBBELL_CURL_RIGHT_ARM
  • EXERCISE_TYPE_DUMBBELL_FRONT_RAISE
  • EXERCISE_TYPE_DUMBBELL_LATERAL_RAISE
  • EXERCISE_TYPE_DUMBBELL_TRICEPS_EXTENSION_LEFT_ARM
  • EXERCISE_TYPE_DUMBBELL_TRICEPS_EXTENSION_RIGHT_ARM
  • EXERCISE_TYPE_DUMBBELL_TRICEPS_EXTENSION_TWO_ARM
  • EXERCISE_TYPE_FORWARD_TWIST
  • EXERCISE_TYPE_JUMPING_JACK
  • EXERCISE_TYPE_JUMP_ROPE
  • EXERCISE_TYPE_LAT_PULL_DOWN
  • EXERCISE_TYPE_LUNGE
  • EXERCISE_TYPE_PLANK
  • EXERCISE_TYPE_SQUAT
  • EXERCISE_TYPE_UPPER_TWIST

Типы замены:

  • EXERCISE_TYPE_HIGH_INTENSITY_INTERVAL_TRAINING
  • EXERCISE_TYPE_STRENGTH_TRAINING
  • EXERCISE_TYPE_CALISTHENICS

Обработка журнала изменений

При переходе с APK на Android 14 журналы изменений не переносятся.

После завершения переноса вы начнете получать исключения TOKEN_EXPIRED или TOKEN_INVALID. Их следует обрабатывать следующими способами (в порядке предпочтения):

1. Считывайте и дедуплицируйте все данные, начиная с временной метки последнего считывания или за последние 30 дней.

Сохранять временную метку последнего считывания данных из сервиса "Здоровье и спорт" приложением. По истечении срока действия токена данные должны быть повторно считаны либо из этого значения, либо за предыдущие 30 дней (в зависимости от того, что соответствует минимуму) и дедуплицированы по сравнению с ранее считанными данными с использованием UUID.

2. Считывать данные, начиная с временной метки последнего чтения.

Установите временную метку, которая указывает, когда данные в последний раз считывались из сервиса "Здоровье и спорт". По истечении срока действия токена считайте все данные, которые были получены после этой временной метки.

3. Удалить и заново считать данные за последние 30 дней

Удалите все данные, считанные из Здоровья и спорта за последние 30 дней, и считайте их снова (как при первой интеграции приложения с Здоровьем и спортом).

4. Ничего не делать (т.е. повторно считать данные за последние 30 дней и не удалять дубликаты)

Этот способ следует использовать только в крайнем случае, поскольку он может привести к дублированию данных. Разработчикам следует использовать варианты 1–3, поскольку UUID уже должны быть настроены.

Тестирование API Android 14 с помощью Jetpack SDK

Android 14 Jetpack SDK будет выпущен 7 июня 2023 года вместе с третьей бета-версией Android 14. Чтобы использовать Jetpack SDK для Android 14, вам нужно будет начать компилировать приложение для Android 14.

Если вы хотите протестировать свое решение на предварительных версиях Android для разработчиков до 7 июня, обратитесь за помощью к контактному лицу Google.

Если вы хотите протестировать свое решение в Beta 3, внесите в APK-файл следующие изменения:

  1. Установите значение compileSDKPreview = UpsideDownCake.
  2. Добавьте в манифест намерение для Android 14:
# AndroidManifest.xml

<uses-permission android:name=”android.permission.health.READ_SLEEP”/>
<uses-permission android:name=”android.permission.health.READ_WEIGHT”/>
<uses-permission android:name=”android.permission.health.WRITE_WEIGHT”/>

<activity>
    android:name=".RationaleActivity"
    android:exported="true">
    <intent-filter>
        <action android:name="androidx.health.ACTION_SHOW_PERMISSIONS_RATIONALE"/>
    </intent-filter>
</activity>

<activity-alias>
      android:name="AndroidURationaleActivity"
      android:exported="true"
      android:targetActivity=".RationaleActivity"
      android:permission="android.permission.START_VIEW_PERMISSION_USAGE">
      <intent-filter>
        <action android:name="android.intent.action.VIEW_PERMISSION_USAGE" />
        <category android:name="android.intent.category.HEALTH_PERMISSIONS" />
      </intent-filter>
</activity-alias>

<queries>
    <package android:name="com.google.android.apps.healthdata" />
</queries>

Настройка OEM

В Android 14 настройки конфиденциальности и управления данными платформы "Здоровье и спорт" находятся в настройках системы.

Чтобы экраны управления данными и разрешениями выглядели как часть устройства, на платформе "Здоровье и спорт" можно использовать темы OEM с помощью настраиваемых оверлеев.

Документация по стилизации OEM доступна в документации по сервисам Google для мобильных устройств для приложения "Здоровье и спорт". Чтобы посмотреть страницу, может потребоваться войти в аккаунт Google Developers.