Начните миграцию или разработку нового приложения уже сегодня! Приложения с более чем 100 пользователями могут подать заявку на верификацию начиная с 30 марта.

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

Эта страница переведена с помощью Cloud Translation API.

Руководство по переходу

API Google Health — это новый API, разработанный с нуля, позволяющий разработчикам запрашивать данные пользователей Fitbit. Это не просто обновление, а стратегический шаг, призванный обеспечить безопасность, надежность и готовность ваших приложений к будущим достижениям в области медицинских технологий. API поддерживает новую консоль для регистрации приложений, поддержку Google OAuth 2.0, новые типы данных, новую схему конечных точек и новый формат ответов.

Данное руководство призвано помочь разработчикам перевести существующие приложения Fitbit Web API на новый Google Health API.

Почему вам стоит эмигрировать?

Преимущества использования API Google Health заключаются в следующем:

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

Регистрация приложения

Все приложения Google Health API должны быть зарегистрированы с помощью консоли Google Cloud , которая служит центральным центром для управления всеми вашими приложениями Google.

Инструкции по регистрации вашего приложения см. в разделе «Начало работы ». Вот какие отличия вы заметите при регистрации приложений.

	Веб-API Fitbit	API Google Health
Общедоступная ссылка(и)	https://dev.fitbit.com/apps	https://console.cloud.google.com
Добавление нового приложения	Нажмите «Зарегистрировать новое приложение» .	Создайте проект в Google Cloud. Включить API Google Health
Основная информация	Поля для заполнения: Название приложения Описание URL веб-сайта приложения Организация URL-адрес веб-сайта организации Условия использования URL URL политики конфиденциальности	Поля для заполнения: Название приложения Электронная почта службы поддержки Целевая аудитория (внутренняя или внешняя) Контактный адрес электронной почты значок логотипа URL веб-сайта приложения URL политики конфиденциальности Условия использования URL Авторизованный домен
Типы приложений	Разработчику необходимо выбрать: Сервер Клиент Личное	Веб-приложение Android Расширение Chrome iOS Телевизоры Настольное приложение Универсальная платформа Windows
Идентификатор клиента	Регистрируется при сохранении настроек приложения.	Зарегистрировано отдельно
Тип доступа	Доступ на чтение и запись контролируется на уровне приложения.	Доступ на чтение и запись контролируется на уровне области действия.
Дополнительные URL-адреса	URL перенаправления : Сайт, на который пользователи перенаправляются после авторизации областей действия.	Авторизованные источники JavaScript : HTTP-источник, на котором размещено веб-приложение. URL перенаправления : Сайт, на который пользователи перенаправляются после авторизации областей действия.

Реализация OAuth

Приложения Google Health API поддерживают только клиентские библиотеки Google OAuth2 . Клиентские библиотеки доступны для популярных фреймворков, что упрощает реализацию OAuth 2.0. Различия между библиотеками Google OAuth2 и библиотеками OAuth2 с открытым исходным кодом заключаются в следующем:

	Веб-API Fitbit	API Google Health
Поддержка библиотеки OAuth2	Открытый исходный код	Библиотеки клиента Google OAuth2
Функциональность	Несогласованность на разных платформах	Единообразный интерфейс на всех платформах
URL авторизации	https://www.fitbit.com/oauth2/authorize	https://accounts.google.com/o/oauth2/v2/auth
URL токена	https://api.fitbit.com/oauth2/token	https://oauth2.googleapis.com/token
Пожизненный срок действия токена доступа	8 часов	1 час
Размер токена доступа	1024 байта	2048 байт
Токен обновления	Токены обновления генерируются при использовании потока предоставления кода авторизации. Для пользователя может быть сгенерирован только один токен обновления. Токены никогда не истекают и могут быть использованы только один раз.	Для генерации токена обновления строка авторизации должна содержать параметр запроса "access_type=offline". Для одного пользователя можно создать несколько токенов обновления. Токены обновления могут быть ограничены по времени. Они истекают, если не использовались в течение 6 месяцев, если пользователю был предоставлен доступ на основе времени или если приложение находится в режиме "Тестирование". Дополнительные сведения см. в разделе "Срок действия токена обновления ".
Ответ токена	JSON-ответ содержит: токен доступа Срок действия токена доступа истекает области тип токена токен обновления ID пользователя	JSON-ответ содержит: токен доступа Срок действия токена доступа истекает области тип токена токен обновления Для получения идентификатора пользователя используйте конечную точку users.getIdentity .

Пользователям Fitbit необходимо повторно подтвердить согласие на вашу новую интеграцию, поскольку ваше приложение использует другую библиотеку OAuth. Передача токенов доступа и токенов обновления в API Google Health и их корректная работа невозможны.

Области применения

Для использования областей действия API Google Health необходимо обновить запрос авторизации. Области действия определяют, поддерживает ли ваше приложение операции чтения или записи. Не используйте области действия, которые не нужны вашему приложению. Вы всегда можете добавить дополнительные области действия позже, если изменится дизайн вашего приложения.

Область действия API Google Health — это HTTP-адрес, начинающийся с https://www.googleapis.com/auth/googlehealth.{scope}. Например, https://www.googleapis.com/auth/googlehealth.activity_and_fitness.

Сопоставление областей видимости

Вот как области действия веб-API Fitbit соотносятся с областями действия API Google Health:

*Таблица: Сопоставление областей действия веб-API Fitbit и API Google Health.*
Области действия веб-API Fitbit	Области действия API Google Health
активность	.activity_and_fitness .activity_and_fitness.readonly
кардио_фитнес	.activity_and_fitness .activity_and_fitness.readonly
частота сердечных сокращений	.health_metrics_and_measurements .health_metrics_and_measurements.readonly
расположение	.location.readonly
питание	.питание .nutrition.readonly
насыщение кислородом	.health_metrics_and_measurements .health_metrics_and_measurements.readonly
профиль	.профиль .profile.readonly
частота дыхания	.health_metrics_and_measurements .health_metrics_and_measurements.readonly
настройки	.настройки .settings.readonly
спать	.спать .sleep.readonly
температура	.health_metrics_and_measurements .health_metrics_and_measurements.readonly
масса	.health_metrics_and_measurements .health_metrics_and_measurements.readonly

Типы данных

Ниже приведён список типов данных API Google Health и их соответствие веб-API Fitbit.

*Таблица: Сопоставление типов данных между веб-API Fitbit и API Google Health.*
Тип данных веб-API Fitbit	Тип данных API Google Health Идентификатор конечной точки
Минуты активной зоны	Минуты активной зоны `active-zone-minutes`
Содержит изменения уровня активности пользователя.	Уровень активности `activity-level`
Высота	Высота `altitude`
Жировая ткань	Жировая масса тела `body-fat`
`caloriesOut` в каждой зоне частоты сердечных сокращений	Калории в зоне частоты сердечных сокращений `calories-in-heart-rate-zone`
Сводка по вариабельности сердечного ритма	Суточная вариабельность сердечного ритма `daily-heart-rate-variability`
Сводка SpO2	Суточная сатурация кислорода `daily-oxygen-saturation`
Частота сердечных сокращений в состоянии покоя	Ежедневная частота сердечных сокращений в состоянии покоя `daily-resting-heart-rate`
Температура кожи	Ежедневные измерения температуры во время сна `daily-sleep-temperature-derivations`
Расстояние	Расстояние `distance`
Зарегистрированная активность	Упражнение `exercise`
Полы	Полы `floors`
Частота сердечных сокращений	Частота сердечных сокращений `heart-rate`
Вариабельность сердечного ритма внутри дня	Вариабельность сердечного ритма `heart-rate-variability`
Внутридневная сатурация кислорода (SpO2)	Насыщение кислородом `oxygen-saturation`
Значение VO2 Max во время бега пользователя	Бег VO2 Max `run-vo2-max`
Последовательность активности во времени, минуты сидячего образа жизни	Сидячий период `sedentary-period`
Спать	Спать `sleep`
Шаги	Шаги `steps`
`caloriesOut` на активность	Общее количество калорий `total-calories`
Значение VO2 Max	VO2 Max `vo2-max`
Масса	Масса `weight`

Конечные точки

REST-интерфейсы используют единый синтаксис для всех типов данных.

Конечная точка сервиса : базовый HTTP-адрес изменяется на https://health.googleapis.com.
Синтаксис конечных точек : API Google Health поддерживает ограниченное количество конечных точек, которые могут использоваться большинством поддерживаемых типов данных. Это обеспечивает согласованный синтаксис для всех типов данных и упрощает использование конечных точек.
Идентификатор пользователя : В синтаксисе конечной точки следует указывать либо идентификатор пользователя, либо me. При использовании me идентификатор пользователя определяется на основе токена доступа.

Пример : Вот пример вызова конечной точки GET Profile с использованием API Google Health.

ПОЛУЧИТЬ https://health.googleapis.com/v4/users/me/profile

Сопоставление конечных точек

Список доступных типов данных и поддерживаемых ими методов API см. в таблице «Доступность типов данных» .

Тип конечной точки веб-API Fitbit	API Google Health
Запрос GET (Log \| Summary \| Daily Summary), в котором запрашиваются данные за один день.	Метод dailyRollup с `windowSize` = 1 день
GET (внутридневная торговля), где запрашиваются детализированные данные.	метод списка
Получение данных (временного ряда) по дате или интервалу.	Метод rollUp или dailyRollUp , включающий диапазон дат.
GET (Список логов)	метод списка
СОЗДАНИЕ И ОБНОВЛЕНИЕ ЖУРНАЛОВ	метод патча
Удалить журналы	метод batchDelete
Получить профиль	Метод users.getProfile возвращает конкретную информацию о пользователе. Метод users.getSettings возвращает единицы измерения и часовые пояса пользователя.
ОБНОВИТЬ профиль	Команда users.updateProfile изменяет конкретную информацию пользователя. Параметр users.updateSettings изменяет единицы измерения и часовые пояса пользователя.
Получить идентификатор пользователя	Метод users.getIdentity возвращает идентификатор пользователя, связанный с его учетной записью Fitbit (старая версия) и идентификатор пользователя Google.

Перенесите своих пользователей

Переход с веб-API Fitbit на API Google Health — это не просто техническое обновление. Вашим пользователям потребуется повторно дать согласие на новую интеграцию из-за изменения библиотеки OAuth. Передача токенов доступа и токенов обновления в API Google Health и их последующая работа невозможны. Чтобы помочь в удержании пользователей во время миграции, ниже приведены некоторые технические и стратегические рекомендации для успешного перехода.

Стратегия двойной библиотеки

Поскольку Fitbit Web API и Google Health API используют разные библиотеки OAuth2, вам необходимо обеспечить "промежуточный" период, в течение которого обе библиотеки будут присутствовать в вашем коде.

Параллельное управление авторизацией

Инкапсуляция клиентов : Создайте абстрактный слой или интерфейс для вашей «службы здоровья». Это позволит остальной части вашего приложения запрашивать данные, не зная, какая библиотека (Fitbit OAuth или Google OAuth) активна для конкретного пользователя.
Обновление схемы базы данных : обновите таблицу пользователей, добавив флаг oauth_type . Например, используйте fitbit для аутентификации Fitbit OAuth и google для аутентификации Google OAuth.
- Для новых пользователей : по умолчанию используется Google Health API и библиотека Google OAuth. Установите oauth_type в google .
- Существующие пользователи : Оставайтесь в системе Fitbit Web API до завершения процесса повторного согласия. Установите oauth_type в fitbit .

Процедура повторного согласия "поэтапного повышения".

Вместо принудительного выхода из системы используйте поэтапный подход к авторизации :

Обнаружение токена открытого исходного кода Fitbit : когда пользователь Fitbit Web API открывает приложение, запускается уведомление об обновлении сервиса.
Запуск потока Google OAuth : Когда пользователь нажимает кнопку «Обновить», запустите поток библиотеки Google OAuth2.
Замена и аннулирование : После успешного получения токена Google OAuth сохраните его в профиле пользователя, обновите oauth_type с fitbit на google и (если возможно) программно аннулируйте старый токен fitbit , чтобы сохранить чистоту профиля безопасности пользователя.

Максимальное удержание пользователей

Повторное согласие — это «опасная зона» для оттока пользователей. Чтобы предотвратить уход пользователей из приложения, следуйте этим рекомендациям по UX:

Коммуникация, ставящая ценности на первое место.

Не начинайте с фразы "Мы обновили наш API". Начните с преимуществ новой системы, поддерживаемой Google:

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

Умный тайминг

Не прерывайте выполнение важных задач : никогда не запускайте экран повторного согласия, когда пользователь находится в процессе тренировки или регистрации потребляемой пищи.
Этап «постепенного воздействия» : В течение первых 30 дней используйте закрывающийся баннер.
Этап «жесткого прекращения» : повторное согласие должно стать обязательным только после нескольких недель предупреждений, что совпадает с официальными сроками прекращения поддержки веб-API Fitbit.

Сравнение миграционных потоков

Четкое визуальное разграничение старого и нового сценариев помогает разработчикам понять, где происходит разветвление логики.

Особенность	Веб-API Fitbit (устаревшая версия)	API Google Health (Google-Identity)
Библиотека аутентификации	Стандартный открытый исходный код	Google Identity Services (GIS) / Google Auth
Учетные записи пользователей	Устаревшие учетные данные Fitbit	Аккаунт Google
Тип токена	Доступ/Обновление, специфичные для Fitbit	Токены доступа/обновления, выданные Google.
Управление объемом работ	Широкие права доступа	Детализированные/постепенные разрешения

Устранение нюансов миграции учетных записей

Согласно документации Fitbit, пользователи, переносящие свои учетные записи в Google, как правило, не теряют сразу же свои подключения к сторонним сервисам, но изменение версии API является требованием разработчиков.

Проверка действительности токена : используйте фоновый процесс (backgroundworker), чтобы проверить, не выдают ли токены Fitbit ошибки "Несанкционированный доступ". Это может указывать на то, что пользователь перенес свою учетную запись, но ваше приложение еще не обновилось.
Корректная обработка ошибок : Если запрос OAuth к Fitbit завершается неудачей, перенаправьте пользователя на специальную страницу «Переподключение Fitbit», которая использует новый процесс аутентификации Google OAuth.

Пример кода

Для перехода с устаревшего веб-API Fitbit на Google Health API вам потребуется перейти от общих библиотек OAuth2 к библиотеке аутентификации Google. Ниже представлено архитектурное предложение и псевдокод, написанный на JavaScript, для обработки этого состояния «двойной библиотеки».

1. «Переключатель промежуточного программного обеспечения»

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

Выполнение

const { OAuth2Client } = require('google-auth-library');
const FitbitV1Strategy = require('fitbit-oauth2-library').Strategy;

// 1. Initialize the Google Health API Client
const GHAClient = new OAuth2Client(
  process.env.GOOGLE_CLIENT_ID,
  process.env.GOOGLE_CLIENT_SECRET,
  process.env.REDIRECT_URI
);

// 2. Create a Unified Fetcher
async function fetchSteps(user) {
  if (user.apiVersion === 4) {
    // ---- GOOGLE OAUTH LIBRARY LOGIC ----
    GHAClient.setCredentials({ refresh_token: user.refreshToken });
    const url = 'GET https://health.googleapis.com/v4/users/me/dataTypes/steps/dataPoints';
    const res = await GHAClient.request({ url });
    return res.data;
  } else {
    // ---- FITBIT WEB API LEGACY LOGIC ----
    // Use your existing Fitbit open-source library logic here
    return callLegacyV1Api(user.accessToken);
  }
}

2. Перенести пользовательский интерфейс.

Для максимального удержания пользователей используйте схему «Прерывание и обновление» . Это гарантирует, что пользователю не придется повторно входить в систему, пока он уже не начнет активно использовать приложение.

Логика перенаправления

Когда пользователь Fitbit Web API обращается к определенной функции, запустите миграцию:

app.get('/dashboard', async (req, res) => {
  const user = await db.users.find(req.user.id);

  if (user.apiVersion === 1) {
    // Render a "soft" migration page explaining the Google transition
    return res.render('migrate-to-google', {
      title: "Keep your data syncing",
      message: "Fitbit is moving to Google accounts. Re-connect now to stay updated."
    });
  }

  const data = await fetchSteps(user);
  res.render('dashboard', { data });
});

3. Ключевые технические переходы

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

Особенность	Веб-API Fitbit (устаревшая версия)	API Google Health (Google-Identity)
Конечная точка токена	https://api.fitbit.com/oauth2/token	https://oauth2.googleapis.com/token
Библиотека аутентификации	Стандартный открытый исходный код	Аутентификация Google
Объем	активность	https://www.googleapis.com/auth/googlehealth.activity_and_fitness
ID пользователя	Идентификатор Fitbit, закодированный в ответе /oauth2/token	Идентификатор пользователя, возвращаемый конечной точкой users.getIdentity.

4. Контрольный список для обеспечения сохранности данных

Сохранение сессии : Не удаляйте старую сессию пользователя в Fitbit Web API до тех пор, пока access_token Google Health API не будет успешно проверен и сохранен в вашей базе данных.
Автоматическое аннулирование : После завершения миграции на API Google Health используйте POST-запрос к устаревшей конечной точке аннулирования разрешений Fitbit: https://api.fitbit.com/oauth2/revoke. Это гарантирует, что пользователь не увидит «дублирующиеся» разрешения приложений в настройках Fitbit.
Обработка ошибок : Если при обращении к Fitbit возвращается ошибка 401 Unauthorized, происходит автоматическое перенаправление на процесс аутентификации Google OAuth вместо отображения сообщения об ошибке.

Руководство по переходу Оптимизируйте свои подборки Сохраняйте и классифицируйте контент в соответствии со своими настройками.