개요

Google Health API는 개발자가 Fitbit 사용자 데이터를 쿼리할 수 있도록 처음부터 빌드된 새로운 API입니다. 이번 업데이트는 단순히 업데이트가 아니라 앱이 안전하고 안정적이며 향후 건강 기술 발전에 대비할 수 있도록 하는 전략적 조치입니다. 이 API는 앱 등록을 위한 새로운 콘솔, Google OAuth 2.0 지원, 새로운 데이터 유형, 새로운 엔드포인트 스키마, 새로운 응답 형식을 지원합니다.

이 가이드는 개발자가 기존 Fitbit Web API 앱을 새로운 Google Health API로 이전하는 데 도움을 주기 위해 마련되었습니다.

마이그레이션해야 하는 이유

Google Health API 사용의 이점은 다음과 같습니다.

• 보안 강화: Google의 보안 권장사항을 준수하여 Google의 보안, 개인 정보 보호, ID 표준을 따릅니다.
• 일관성: 데이터 형식, 시간대, 측정 단위, 오류 처리의 기존 불일치를 없애 개발자 환경을 더 직관적으로 만듭니다.
• 확장성 및 미래 대비: 향후 요구사항을 충족하도록 확장할 수 있도록 설계되었으며 gRPC와 같은 최신 프로토콜을 지원합니다.

사용자 이전

Fitbit Web API에서 Google Health API로 이전하는 것은 단순한 기술 업데이트가 아닙니다. OAuth 라이브러리가 변경되므로 사용자가 새 통합에 다시 동의해야 합니다. 액세스 토큰과 새로고침 토큰을 Google Health API로 전송하여 작동하도록 할 수는 없습니다. 이전 중에 사용자 유지를 지원하기 위해 성공적인 이전을 위한 몇 가지 기술적 및 전략적 제안을 소개합니다.

이중 라이브러리 전략

Fitbit Web API와 Google Health API는 서로 다른 OAuth2 라이브러리를 사용하므로 코드베이스에 두 라이브러리가 모두 있는 '브리징' 기간을 관리해야 합니다.

병렬 승인 관리

• 클라이언트 캡슐화: '건강 서비스'의 추상화 레이어 또는 인터페이스를 만듭니다. 이렇게 하면 앱의 나머지 부분에서 특정 사용자에 대해 활성화된 라이브러리 (Fitbit OAuth와 Google OAuth)를 알지 못해도 데이터를 요청할 수 있습니다.
• 데이터베이스 스키마 업데이트: oauth_type 플래그를 포함하도록 사용자 테이블을 업데이트합니다. 예를 들어 Fitbit OAuth에는 fitbit를 사용하고 Google OAuth에는 google를 사용합니다.
  • 신규 사용자: Google Health API 및 Google OAuth 라이브러리가 기본값입니다. oauth_type를 google로 설정합니다.
  • 기존 사용자: 재동의 흐름을 완료할 때까지 Fitbit Web API를 유지합니다. oauth_type를 fitbit로 설정합니다.

'Step-Up' 재동의 절차

강제 로그아웃 대신 증분 승인 방식을 사용하세요.

1. Fitbit 오픈소스 토큰 감지: Fitbit Web API 사용자가 앱을 열면 '서비스 업데이트' 알림을 트리거합니다.
2. Google OAuth 흐름 실행: 사용자가 '업데이트'를 클릭하면 Google OAuth2 라이브러리 흐름을 시작합니다.
3. 바꾸기 및 취소: Google OAuth 토큰을 수신하면 사용자 프로필에 저장하고 oauth_type을 fitbit에서 google로 업데이트하고 (가능한 경우) 이전 fitbit 토큰을 프로그래매틱 방식으로 취소하여 사용자의 보안 프로필을 정리합니다.

사용자 유지율 극대화

재동의는 이탈이 발생할 수 있는 '위험 지대'입니다. 사용자가 앱을 포기하지 않도록 다음 UX 권장사항을 따르세요.

'가치 우선' 커뮤니케이션

'API가 업데이트되었습니다'로 시작하지 마세요. 새로운 Google 지원 시스템의 이점을 강조하세요.

• 보안 강화: Google의 업계 최고 수준의 계정 보호 및 2FA를 언급합니다.
• 안정성: 동기화 시간이 단축되고 데이터 연결이 더 안정적입니다.
• 기능 게이팅: 새 기능과 데이터 유형을 사용하려면 업데이트가 필요하다고 사용자에게 부드럽게 알립니다.

스마트 타이밍

• 가치가 높은 작업 방해 금지: 사용자가 운동 중이거나 음식 기록을 작성하는 중에 동의 다시 요청 화면을 트리거하지 마세요.
• '푸시' 단계: 처음 30일 동안은 닫을 수 있는 배너를 사용합니다.
• '강제 중단' 단계: 공식 Fitbit Web API 지원 중단 기한과 일치하도록 몇 주간 경고한 후에만 재동의를 필수사항으로 만듭니다.

이전 흐름 비교

이전 흐름과 새 흐름을 시각적으로 명확하게 구분하면 개발자가 로직이 분기되는 위치를 이해하는 데 도움이 됩니다.

기능	Fitbit Web API (기존)	Google Health API (Google-Identity)
인증 라이브러리	표준 오픈소스	Google ID 서비스 (GIS) / Google 인증
사용자 계정	Fitbit 기존 사용자 인증 정보	Google 계정
토큰 유형	Fitbit 관련 액세스 / 새로고침	Google에서 발급한 액세스/새로고침 토큰
범위 관리	광범위한 권한	세분화된 / 증분 권한

계정 이전의 미묘한 차이 처리

Fitbit 문서에 따르면 계정을 Google로 이전하는 사용자는 일반적으로 서드 파티 연결을 즉시 잃지 않지만 API 버전을 변경하는 것은 개발자 측 요구사항입니다.

• 토큰 유효성 확인: 백그라운드 작업자를 사용하여 Fitbit 토큰이 '인증되지 않음' 오류로 실패하는지 확인합니다. 이는 사용자가 계정을 이전했지만 앱이 이를 따라가지 못했음을 나타낼 수 있습니다.
• 그레이스풀 실패: Fitbit OAuth 호출이 실패하면 새 Google OAuth 흐름을 구체적으로 사용하는 맞춤 'Fitbit 다시 연결' 페이지로 사용자를 리디렉션합니다.