Google Health API adalah solusi komprehensif yang dibangun dari awal, yang memberi developer akses yang kuat ke berbagai data kesehatan pengguna yang diizinkan dan beragam jenis data. Google Health API menggunakan konsol baru untuk mendaftarkan aplikasi Anda, Google OAuth 2.0, jenis data baru, skema endpoint baru, dan format respons baru.
Panduan ini dirancang untuk membantu developer memigrasikan aplikasi Fitbit Web API yang ada ke Google Health API baru. Panduan ini berisi rekomendasi untuk memastikan migrasi yang lancar sekaligus mempertahankan pengguna.
Mengapa Anda harus bermigrasi?
Ini bukan sekadar update, melainkan langkah strategis untuk memastikan aplikasi Anda aman dan siap menghadapi kemajuan teknologi kesehatan di masa mendatang. Beberapa manfaat menggunakan Google Health API adalah:
- Akses ke Data Komprehensif: Dapatkan akses yang andal ke berbagai data kesehatan pengguna yang diizinkan dan beragam jenis data.
- Keamanan yang Ditingkatkan: Kepatuhan terhadap praktik terbaik keamanan Google, yang selaras dengan standar keamanan, privasi, dan identitas Google.
- Konsistensi: Menghilangkan inkonsistensi lama dalam format data, zona waktu, unit pengukuran, dan penanganan error untuk pengalaman developer yang lebih intuitif.
- Skalabilitas & Kesiapan untuk Masa Depan: Dirancang untuk diskalakan guna memenuhi permintaan di masa mendatang dan mendukung protokol modern seperti gRPC.
Transisi dari Fitbit Web API ke Google Health API melibatkan lebih dari sekadar modifikasi teknis. Karena beralih ke library OAuth baru, token akses dan token refresh yang ada tidak dapat ditransfer, sehingga pengguna harus memberikan izin ulang ke integrasi yang diperbarui.
Mendukung kedua metode login
Karena Fitbit Web API dan Google Health API menggunakan sistem yang berbeda untuk menangani login pengguna, selama Fitbit Web API masih aktif, aplikasi Anda akan perlu mendukung kedua metode autentikasi tersebut untuk sementara di seluruh basis pengguna Anda.
Daripada aplikasi Anda meminta data secara langsung, terapkan lapisan yang memutuskan apakah akan berkomunikasi dengan Fitbit Web API atau Google Health API untuk pengguna tertentu, sehingga bagian lain dari aplikasi Anda tidak perlu mengkhawatirkan detailnya.
Perbarui database pengguna Anda untuk menyertakan flag (misalnya, oauth_type)
untuk mengidentifikasi sistem login yang mereka gunakan.
- Untuk pengguna baru: Siapkan secara otomatis dengan Google Health API baru
(
oauth_type: google). - Untuk pengguna lama: Pertahankan mereka di Fitbit Web API hingga mereka memperbarui
izin mereka (
oauth_type: fitbit).
| Skenario Pengguna | oauth_type State |
Streaming API Aktif | Tindakan yang Diperlukan |
|---|---|---|---|
| Orientasi pengguna baru | google |
Khusus Google Health API | Luncurkan Google OAuth di browser sistem dan petakan ID dengan users.getIdentity. |
| Pengguna Fitbit lama (belum dimigrasikan) | fitbit |
Khusus Fitbit Web API | Lanjutkan sinkronisasi dengan Fitbit Web API; tampilkan perintah dalam aplikasi yang dapat ditutup untuk mengupgrade. |
| Pengguna Fitbit lama yang menyelesaikan migrasi | fitbit → google |
Beralih ke Google Health API | Verifikasi cakupan yang diberikan, panggil users.getIdentity (legacyUserId → healthUserId), alihkan oauth_type ke google, dan segera cabut token Fitbit lama. |
Agar tidak mengganggu pengalaman pengguna, sebaiknya jangan memaksa semua orang untuk logout dan login kembali. Sebagai gantinya:
- Saat pengguna yang tetap terhubung ke Fitbit Web API berinteraksi dengan aplikasi Anda, tampilkan notifikasi yang ramah untuk mendorong mereka memperbarui koneksi.
- Saat pengguna menerima tindakan update, picu alur login Google Health saat itu juga.
- Setelah login Google berhasil, simpan kredensial Google baru ke
profil pengguna, alihkan tanda
oauth_typemereka darifitbitkegoogle, dan segera nonaktifkan sinkronisasi lama dengan mencabut token Fitbit lama mereka secara terprogram untuk mencegah penyerapan data duplikat dan penautan ganda.
Memastikan kontinuitas data
Saat mentransisikan integrasi dari Fitbit Web API lama ke Google Health API, aplikasi developer harus memperhitungkan perubahan dalam struktur identifikasi pengguna.
Fitbit Web API lama mengidentifikasi akun menggunakan string alfanumerik 6 karakter (seperti A1B2C3), sedangkan Google Health API menggunakan
healthUserId yang diformat sebagai string hingga 63 digit & karakter.
Untuk menjembatani kesenjangan ini tanpa kehilangan konteks pengguna, developer dapat mengkueri
endpoint getIdentity untuk mendapatkan ID pengguna Fitbit dan
Health.
Endpoint ini menampilkan payload yang berisi legacyUserId dan healthUserId baru, sehingga aplikasi dapat membuat pemetaan secara dinamis antara data yang ada dan sistem akun baru.
Menangani Akun Google yang tidak ditautkan
Pengguna harus login ke aplikasi seluler Google Health untuk menautkan Google Health ke Akun Google mereka sebelum aplikasi Anda dapat menyinkronkan data melalui Google Health API. Lihat Menautkan Google Health sebelum izin OAuth. Karena Google OAuth 2.0 mengautentikasi Akun Google yang valid selama izin, Google OAuth 2.0 tidak dapat memblokir akun yang belum memiliki profil Google Health aktif.
Jika pengguna menyelesaikan izin Google OAuth sebelum membuat profil Google Health
atau sebelum memigrasikan akun Fitbit lama ke Akun Google-nya, memanggil
users.getIdentity atau endpoint
data akan menampilkan error HTTP 400 Bad Request dengan status
FAILED_PRECONDITION dan alasan ACCOUNT_NOT_LINKED:
{
"error": {
"code": 400,
"message": "The account is not linked to Google Health.",
"status": "FAILED_PRECONDITION",
"details": [
{
"@type": "type.googleapis.com/google.rpc.ErrorInfo",
"reason": "ACCOUNT_NOT_LINKED",
"domain": "health.googleapis.com",
"metadata": {
"redirect_uri": "https://fitbit.google.com/auth/signup"
}
}
]
}
}
Untuk memverifikasi akses akun dan menangani error ini:
- Tukarkan kode otorisasi OAuth dengan token dan segera panggil
users.getIdentity(GET https://health.googleapis.com/v4/users/me/identity) sebelum menandai akun sebagai tertaut di UI aplikasi Anda. - Jika
users.getIdentityatau panggilan sinkronisasi data latar belakang menampilkan HTTP400dengan alasanACCOUNT_NOT_LINKED, jangan tandai akun sebagai terhubung. Jika pengguna bermigrasi dari Fitbit Web API lama, biarkan koneksi Fitbit yang ada tetap aktif dan jangan cabut token Fitbit lama mereka. Tampilkan dialog yang dapat ditindaklanjuti yang ditujukan bagi pengguna baru yang belum pernah membuat akun Google Health atau Fitbit dan pengguna Fitbit lama yang belum bermigrasi ke Akun Google:
"Akun Google Anda belum ditautkan ke Google Health. Buka aplikasi seluler Google Health dan login dengan Akun Google Anda untuk membuat profil, atau pindahkan akun Fitbit yang ada ke Akun Google Anda, lalu kembali ke sini untuk menghubungkan."
Sediakan tombol pesan ajakan (CTA) yang membuka
redirect_uridari metadata error (https://fitbit.google.com/auth/signup) atau arahkan pengguna Fitbit lama ke artikel bantuan migrasi akun Fitbit.
Mengisi ulang data historis
Jika pengguna tidak melakukan autentikasi ke endpoint API Google Health baru sebelum endpoint lama dinonaktifkan, datanya akan tetap tersedia selama pengguna terus menyinkronkan perangkatnya ke aplikasi Google Health. Namun, Anda mungkin memiliki kesenjangan data untuk pengguna ini.
Untuk mengisi ulang data, setelah pengguna melakukan autentikasi ulang ke endpoint baru, Anda dapat menggunakan Google Health API kami untuk mengisi ulang data historis mereka. Lihat Membuat kueri data historis untuk mendapatkan panduan.
Contoh penerapan migrasi dan penautan
Implementasi referensi berikut menunjukkan cara menangani callback OAuth, memvalidasi izin parsial atau nol, menyelesaikan identitas pengguna dengan
users.getIdentity (termasuk penanganan HTTP 400 ACCOUNT_NOT_LINKED),
mencegah penautan ganda dengan mencabut token Fitbit lama, dan mengarahkan permintaan
data menggunakan oauth_type:
import requests
GOOGLE_HEALTH_IDENTITY_URL = "https://health.googleapis.com/v4/users/me/identity"
FITBIT_REVOKE_URL = "https://api.fitbit.com/oauth2/revoke"
DEFAULT_SIGNUP_URL = "https://fitbit.google.com/auth/signup"
def complete_google_health_linking(user_record: dict, oauth_token_response: dict, fitbit_client_creds: str) -> dict:
"""Completes Google Health account linking and migrates legacy Fitbit users."""
# 1. Check granted scopes (handle zero consent and partial consent)
granted_scopes = set(oauth_token_response.get("scope", "").split())
health_scopes = {s for s in granted_scopes if s.startswith("https://www.googleapis.com/auth/googlehealth")}
if not health_scopes:
return {
"status": "MISSING_PERMISSIONS",
"ui_action": "ROUTE_TO_MISSING_PERMISSIONS_SCREEN",
"message": "At least one permission is required to connect to Google Health.",
}
access_token = oauth_token_response["access_token"]
# 2. Call users.getIdentity and handle HTTP 400
# (status: "FAILED_PRECONDITION", ErrorInfo.reason: "ACCOUNT_NOT_LINKED").
identity_resp = requests.get(
GOOGLE_HEALTH_IDENTITY_URL,
headers={"Authorization": f"Bearer {access_token}", "Accept": "application/json"},
timeout=10,
)
if identity_resp.status_code == 400:
error_payload = identity_resp.json().get("error", {})
if error_payload.get("status") == "FAILED_PRECONDITION":
for detail in error_payload.get("details", []):
if detail.get("reason") == "ACCOUNT_NOT_LINKED":
redirect_uri = detail.get("metadata", {}).get("redirect_uri", DEFAULT_SIGNUP_URL)
return {
"status": "ACCOUNT_NOT_LINKED",
"ui_action": "PROMPT_LINK_GOOGLE_HEALTH_ACCOUNT",
"redirect_uri": redirect_uri,
"message": (
"Your Google Account isn't linked to Google Health yet. "
"Open the Google Health mobile app and sign in with your Google Account "
"to create a profile, or move your existing Fitbit account to your "
"Google Account, then return here to connect."
),
}
identity_resp.raise_for_status()
identity = identity_resp.json()
# 3. Verify legacyUserId and map legacyUserId -> healthUserId.
previous_oauth_type = user_record.get("oauth_type")
legacy_fitbit_refresh_token = user_record.get("fitbit_refresh_token")
existing_legacy_id = user_record.get("legacy_user_id")
returned_legacy_id = identity.get("legacyUserId")
legacy_id_verified = bool(returned_legacy_id) and (
not existing_legacy_id or returned_legacy_id == existing_legacy_id
)
if previous_oauth_type == "fitbit" and not legacy_id_verified:
return {
"status": "LEGACY_ID_MISMATCH",
"ui_action": "PROMPT_VERIFY_FITBIT_MIGRATION_ACCOUNT",
"message": (
"The Google Account you signed in with does not match your linked "
"Fitbit account. Sign in with the Google Account linked to your "
"Fitbit profile."
),
}
# 4. Cut over oauth_type and revoke legacy Fitbit token once verified.
user_record.update({
"health_user_id": identity.get("healthUserId") or user_record.get("health_user_id"),
"legacy_user_id": returned_legacy_id or existing_legacy_id,
"google_access_token": access_token,
"google_refresh_token": oauth_token_response.get("refresh_token"),
"granted_scopes": list(health_scopes),
"oauth_type": "google",
"fitbit_access_token": None,
"fitbit_refresh_token": None,
})
if previous_oauth_type == "fitbit" and legacy_fitbit_refresh_token:
requests.post(
FITBIT_REVOKE_URL,
headers={
"Authorization": f"Basic {fitbit_client_creds}",
"Content-Type": "application/x-www-form-urlencoded",
},
data={"token": legacy_fitbit_refresh_token},
timeout=10,
)
return {
"status": "CONNECTED",
"health_user_id": user_record["health_user_id"],
"granted_scopes": user_record["granted_scopes"],
}
Komunikasi dan pengaturan waktu
Untuk membantu pengguna Anda beralih dari OAuth Fitbit yang ada ke OAuth Google yang baru, ikuti praktik terbaik berikut.
Komunikasi yang mengutamakan nilai
Jangan memulai dengan "Kami telah memperbarui API kami", mulailah dengan manfaat mengintegrasikan data Google Health ke dalam aplikasi Anda, tetapi pastikan mereka mengetahui bahwa mereka perlu melakukan autentikasi ulang jika ingin menyinkronkan data mereka:
- Jelaskan dengan jelas fitur apa saja yang tersedia di aplikasi Anda yang didukung oleh integrasi, dan sesuaikan pesan Anda dengan manfaat yang diperoleh pengguna dari fitur tersebut.
- Fokus pada fitur Anda dan berikan kasus penggunaan, bukan detail implementasi teknis.
- Jangan katakan: "Anda tidak akan dapat terhubung ke Fitbit API."
- Sebaiknya katakan: "Untuk terus melihat latihan fisik mendetail dengan data detak jantung, berikan izin ulang ke Google Health API."
Kapan harus memberi tahu pengguna
Dalam semua komunikasi pengguna, patuhi panduan merek Google Health, dan gunakan banner, kartu, atau pemberitahuan yang dapat ditutup.
- Jangan memicu layar izin ulang saat pengguna sedang berolahraga atau mencatat sesuatu secara manual.
- Hanya wajibkan pemberian izin ulang setelah beberapa minggu peringatan, yang bertepatan dengan batas waktu penghentian Fitbit Web API resmi.
- Jika pengguna belum memberikan izin ulang setelah batas waktu yang ditentukan, berikan jalur pemulihan yang lancar. Berikan pesan bantuan dalam banner, kartu atau tooltip yang membantu mereka memahami alasan data mereka tidak ada, dan cara memperbaikinya.
Merencanakan pembatasan kapasitas pemberian token OAuth
Saat pengguna Fitbit yang ada memberikan izin ulang ke Google Health API, setiap otorisasi pengguna akan diperhitungkan dalam batas kapasitas pemberian token OAuth project Google Cloud Anda. Batas ini mengontrol jumlah pengguna yang dapat mengizinkan aplikasi Anda per menit dan per periode pengamatan 24 jam.
Jika Anda memperkirakan akan melebihi 10.000 pendaftaran atau autentikasi ulang pengguna dalam periode 24 jam selama migrasi, ikuti langkah-langkah berikut untuk menghindari batas kapasitas OAuth:
- Pantau penggunaan pemberian token di project Google Cloud Anda.
- Atur kecepatan notifikasi migrasi dalam aplikasi agar tetap berada dalam batas hibah harian Anda.
- Minta kuota pemberian token OAuth yang lebih tinggi sebelum meminta grup pengguna yang besar untuk melakukan autentikasi ulang. Untuk mengetahui petunjuk tentang cara memeriksa penggunaan dan meminta peningkatan, lihat Batas kapasitas aplikasi OAuth.