Panduan migrasi

Google Health API adalah API baru yang dibuat dari awal dan memungkinkan developer mengirim kueri data pengguna Fitbit. Ini bukan hanya update, tetapi juga langkah strategis untuk memastikan aplikasi Anda aman, andal, dan siap menghadapi kemajuan teknologi kesehatan di masa mendatang. API mendukung konsol baru untuk mendaftarkan aplikasi Anda, dukungan 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 sudah ada ke Google Health API yang baru.

Mengapa Anda harus bermigrasi?

Manfaat menggunakan Google Health API adalah:

  • 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 & Persiapan untuk Masa Depan: Dirancang untuk menskalakan guna memenuhi permintaan di masa mendatang dan mendukung protokol modern seperti gRPC.

Pendaftaran Aplikasi

Semua aplikasi Google Health API harus didaftarkan menggunakan Konsol Google Cloud, yang berfungsi sebagai hub pusat untuk mengelola semua aplikasi Google Anda.

Untuk mengetahui petunjuk tentang cara mendaftarkan aplikasi, ikuti langkah-langkah di Memulai. Berikut perbedaan yang akan Anda perhatikan saat mendaftarkan aplikasi.

Fitbit Web API Google Health API
Link publik https://dev.fitbit.com/apps https://console.cloud.google.com
Menambahkan aplikasi baru Tekan Daftarkan aplikasi baru
  1. Buat Project Google Cloud
  2. Aktifkan Google Health API
Info Dasar Kolom yang harus diisi:
  • Nama Aplikasi
  • Deskripsi
  • URL Situs Aplikasi
  • Organisasi
  • URL Situs Organisasi
  • URL Persyaratan Layanan
  • URL Kebijakan Privasi
 Kolom yang harus diisi:
  • Nama aplikasi
  • Email dukungan
  • Audiens (internal atau eksternal)
  • Email kontak
  • Ikon logo
  • URL situs aplikasi
  • URL kebijakan privasi
  • URL Persyaratan Layanan
  • Domain yang Diotorisasi
Jenis Aplikasi Developer harus memilih:
  • Server
  • Klien
  • Pribadi
  • Aplikasi web
  • Android
  • Ekstensi Chrome
  • iOS
  • TV
  • Aplikasi desktop
  • Platform Universal Windows
ID Klien Didaftarkan saat setelan aplikasi disimpan Terdaftar secara terpisah
Jenis Akses Akses Baca dan Tulis dikontrol di tingkat aplikasi Akses Baca dan Tulis dikontrol di tingkat cakupan
URL Tambahan
  • URL pengalihan: Situs tempat pengguna dialihkan setelah mengizinkan cakupan
  • Asal JavaScript Resmi: Asal HTTP yang menghosting aplikasi web
  • URL pengalihan: Situs tempat pengguna dialihkan setelah mengizinkan cakupan

Implementasi OAuth

Aplikasi Google Health API hanya mendukung Library Klien Google OAuth2. Library klien tersedia untuk framework populer, yang membuat penerapan OAuth 2.0 lebih sederhana. Perbedaan antara library Google OAuth2 dan library OAuth2 open source adalah sebagai berikut:

Fitbit Web API Google Health API
Dukungan library OAuth2 Open Source Library Klien OAuth2 Google
Fungsi Tidak konsisten di seluruh platform Konsisten di seluruh platform
URL otorisasi https://www.fitbit.com/oauth2/authorize https://accounts.google.com/o/oauth2/v2/auth
URL Token https://api.fitbit.com/oauth2/token https://oauth2.googleapis.com/token
Masa Aktif Token Akses 8 jam 1 jam
Ukuran Token Akses 1.024 byte 2048 byte
Refresh Token Token refresh dibuat saat menggunakan Alur Pemberian Kode Otorisasi. Hanya 1 token refresh yang dapat dibuat untuk pengguna. Token tidak pernah berakhir masa berlakunya dan hanya dapat digunakan satu kali. Untuk membuat token refresh, string otorisasi harus berisi parameter kueri "access_type=offline". Beberapa token refresh dapat dibuat untuk satu pengguna. Token refresh dapat berbasis waktu. Masa berlakunya akan berakhir jika tidak digunakan dalam waktu 6 bulan, pengguna memberikan akses berbasis waktu, atau aplikasi dalam mode "Pengujian". Lihat Masa berlaku token refresh untuk mengetahui detail selengkapnya.
Respons Token Respons JSON berisi:
  • token akses
  • masa berlaku token akses
  • cakupan
  • jenis token
  • token refresh
  • ID pengguna
 Respons JSON berisi:
  • token akses
  • masa berlaku token akses
  • cakupan
  • jenis token
  • token refresh

Untuk mendapatkan ID pengguna, gunakan endpoint users.getIdentity.

Pengguna Fitbit harus memberikan izin ulang untuk integrasi baru Anda, karena aplikasi Anda menggunakan library OAuth yang berbeda. Token akses dan token refresh tidak dapat ditransfer ke Google Health API dan berfungsi.

Cakupan

Anda harus memperbarui permintaan otorisasi untuk menggunakan cakupan Google Health API. Cakupan menentukan apakah aplikasi Anda mendukung operasi baca atau tulis. Jangan gunakan cakupan yang tidak diperlukan untuk aplikasi Anda. Anda dapat menambahkan lebih banyak cakupan nanti jika desain aplikasi Anda berubah.

Cakupan Google Health API adalah URL HTTP yang diawali dengan https://www.googleapis.com/auth/googlehealth.{scope}. Misalnya, https://www.googleapis.com/auth/googlehealth.activity_and_fitness.

Pemetaan cakupan

Berikut cara cakupan Fitbit Web API dipetakan ke cakupan Google Health API:

Tabel: Pemetaan cakupan Fitbit Web API ke Google Health API
Cakupan Fitbit Web API Cakupan Google Health API
aktivitas .activity_and_fitness
.activity_and_fitness.readonly
cardio_fitness .activity_and_fitness
.activity_and_fitness.readonly
detak jantung .health_metrics_and_measurements
.health_metrics_and_measurements.readonly
lokasi .location.readonly
gizi .nutrition
.nutrition.readonly
oxygen_saturation .health_metrics_and_measurements
.health_metrics_and_measurements.readonly
profil .profile
.profile.readonly
respiratory_rate .health_metrics_and_measurements
.health_metrics_and_measurements.readonly
setelan .settings
.settings.readonly
sleep .sleep
.sleep.readonly
suhu .health_metrics_and_measurements
.health_metrics_and_measurements.readonly
bobot .health_metrics_and_measurements
.health_metrics_and_measurements.readonly

Jenis data

Berikut daftar jenis data Google Health API dan cara pemetaannya ke Fitbit Web API.

Tabel: Pemetaan jenis data Fitbit Web API ke Google Health API
Jenis Data Fitbit Web API Jenis Data Google Health API
  ID Endpoint
Menit Zona Aktif Menit Zona Aktif
  active-zone-minutes
Berisi perubahan pada tingkat aktivitas pengguna Tingkat Aktivitas
  activity-level
Elevasi Ketinggian
  altitude
Lemak tubuh Lemak Tubuh
  body-fat
caloriesOut di setiap zona detak jantung Kalori di Zona Detak Jantung
  calories-in-heart-rate-zone
Ringkasan HRV Variabilitas Detak Jantung Harian
  daily-heart-rate-variability
Ringkasan SpO2 Saturasi Oksigen Harian
  daily-oxygen-saturation
Detak jantung saat istirahat Detak Jantung Istirahat Harian
  daily-resting-heart-rate
Suhu kulit Turunan Suhu Tidur Harian
  daily-sleep-temperature-derivations
Jarak Jarak
  distance
Aktivitas yang direkam Exercise
  exercise
Lantai Lantai
  floors
Detak Jantung Detak Jantung
  heart-rate
HRV Intrahari Variabilitas Detak Jantung
  heart-rate-variability
SpO2 Intrahari Saturasi Oksigen
  oxygen-saturation
Nilai VO2 Maks saat pengguna berlari VO2 Maks Lari
  run-vo2-max
Deret waktu aktivitas dalam menit tidak bergerak Periode Tidak Aktif
  sedentary-period
Tidur Tidur
  sleep
Langkah Langkah-langkah
  steps
Aktivitas caloriesOut Total Kalori
  total-calories
Nilai VO2 Maks VO2 Maks
  vo2-max
Berat Berat
  weight

Endpoint

Endpoint REST mengadopsi sintaksis yang konsisten untuk semua jenis data.

  • Service Endpoint: URL HTTP dasar berubah menjadi https://health.googleapis.com.
  • Sintaksis Endpoint: Google Health API mendukung sejumlah kecil endpoint, yang dapat digunakan oleh sebagian besar jenis data yang didukung. Hal ini memberikan sintaksis yang konsisten untuk semua jenis data dan membuat endpoint lebih mudah digunakan.
  • ID Pengguna: ID pengguna atau me harus ditentukan dalam sintaksis endpoint. Saat menggunakan saya, ID pengguna disimpulkan dari token akses.

Contoh: Berikut adalah contoh endpoint GET Profile yang dipanggil menggunakan Google Health API

GET https://health.googleapis.com/v4/users/me/profile

Pemetaan endpoint

Lihat tabel Ketersediaan Jenis Data untuk mengetahui daftar jenis data yang tersedia dan metode API yang didukungnya.

Jenis Endpoint Fitbit Web API Google Health API
GET (Log | Ringkasan | Ringkasan Harian) tempat Anda meminta data satu hari Metode dailyRollup dengan windowSize = 1 hari
GET (Intraday) jika Anda meminta data terperinci Metode list
GET (Deret Waktu) menurut Tanggal atau Interval Metode rollUp atau dailyRollUp yang mencakup rentang tanggal
GET (Daftar Log) Metode list
MEMBUAT & MEMPERBARUI Log Metode patch
HAPUS Log Metode batchDelete
GET Profile users.getProfile menampilkan informasi spesifik pengguna
users.getSettings menampilkan unit dan zona waktu pengguna
PERBARUI Profil users.updateProfile mengubah informasi spesifik pengguna
users.updateSettings mengubah unit dan zona waktu pengguna
Mendapatkan ID Pengguna users.getIdentity menampilkan ID pengguna Google dan ID pengguna lama Fitbit.

Memigrasikan Pengguna Anda

Bermigrasi dari Fitbit Web API ke Google Health API bukan hanya sekadar update teknis. Pengguna Anda harus memberikan izin ulang untuk integrasi baru Anda karena perubahan library OAuth. Token akses dan token refresh tidak dapat ditransfer ke Google Health API dan berfungsi. Untuk membantu mempertahankan pengguna selama migrasi, berikut beberapa saran teknis dan strategis untuk migrasi yang berhasil.

Strategi Perpustakaan Ganda

Karena Fitbit Web API dan Google Health API menggunakan library OAuth2 yang berbeda, Anda harus mengelola periode "bridging" saat kedua library ada dalam codebase Anda.

Pengelolaan Otorisasi Paralel

  • Mengenkapsulasi Klien: Buat lapisan atau antarmuka abstraksi untuk "Layanan Kesehatan" Anda. Hal ini memungkinkan bagian aplikasi Anda lainnya meminta data tanpa mengetahui pustaka mana (Fitbit OAuth versus Google OAuth) yang aktif untuk pengguna tertentu tersebut.
  • Pembaruan Skema Database: Perbarui tabel pengguna Anda untuk menyertakan tanda oauth_type. Misalnya, gunakan fitbit untuk Fitbit OAuth dan google untuk Google OAuth.
    • Pengguna Baru: Secara default menggunakan Google Health API dan library Google OAuth. Setel oauth_type ke google.
    • Pengguna Lama: Tetap menggunakan Fitbit Web API hingga mereka menyelesaikan alur pemberian izin ulang. Setel oauth_type ke fitbit.

Alur Pemberian Izin Ulang "Step-Up"

Daripada memaksakan logout, gunakan pendekatan otorisasi inkremental:

  1. Mendeteksi Token Open Source Fitbit: Saat pengguna Fitbit Web API membuka aplikasi, picu notifikasi "Pembaruan Layanan".
  2. Luncurkan Alur OAuth Google: Saat pengguna mengklik "Perbarui", mulai alur library OAuth2 Google.
  3. Ganti & Cabut: Setelah token OAuth Google berhasil diterima, simpan ke profil pengguna, perbarui oauth_type dari fitbit ke google, dan (jika memungkinkan) cabut token fitbit lama secara terprogram untuk menjaga profil keamanan pengguna tetap bersih.

Memaksimalkan Retensi Pengguna

Pemberian izin ulang adalah "zona bahaya" untuk churn. Untuk mencegah pengguna meninggalkan aplikasi, ikuti praktik terbaik UX berikut:

Komunikasi "Mengutamakan Nilai"

Jangan memulai dengan "Kami memperbarui API kami". Mulai dengan manfaat sistem baru yang didukung Google:

  • Keamanan yang Ditingkatkan: Sebutkan perlindungan akun terdepan di industri dan 2FA dari Google.
  • Keandalan: Waktu sinkronisasi yang lebih cepat dan koneksi data yang lebih stabil.
  • Pembatasan Fitur: Memberi tahu pengguna secara halus bahwa fitur dan jenis data baru memerlukan update.

Waktu Cerdas

  • Jangan Mengganggu Tugas Bernilai Tinggi: Jangan pernah memicu layar izin ulang saat pengguna sedang berolahraga atau mencatat makanan.
  • Fase "Dorongan": Selama 30 hari pertama, gunakan banner yang dapat ditutup.
  • Fase "Penghentian Paksa": Hanya mewajibkan izin ulang setelah beberapa minggu peringatan, bertepatan dengan batas waktu penghentian penggunaan Fitbit Web API resmi.

Perbandingan Alur Migrasi

Perbedaan visual yang jelas antara alur lama dan baru membantu developer memahami tempat logika bercabang.

Fitur Fitbit Web API (Legacy) Google Health API (Google-Identity)
Auth Library Open Source Standar Google Identity Services (GIS) / Google Auth
Akun Pengguna Kredensial Lama Fitbit Akun Google
Jenis Token Akses / Penyegaran Khusus Fitbit Token Akses/Refresh yang dikeluarkan Google
Pengelolaan Cakupan Izin luas Izin terperinci / inkremental

Menangani Nuansa Migrasi Akun

Menurut dokumentasi Fitbit, pengguna yang memigrasikan akun mereka ke Google umumnya tidak langsung kehilangan koneksi pihak ketiga mereka, tetapi mengubah versi API adalah persyaratan sisi developer.

  • Periksa Validitas Token: Gunakan backgroundworker untuk memeriksa apakah token Fitbit gagal dengan error "Tidak Sah". Hal ini dapat menunjukkan bahwa pengguna telah memigrasikan akunnya, tetapi aplikasi Anda belum siap.
  • Kegagalan yang Baik: Jika panggilan Fitbit OAuth gagal, alihkan pengguna ke halaman "Hubungkan Kembali Fitbit" kustom yang secara khusus menggunakan alur Google OAuth baru.

Contoh kode

Untuk bermigrasi dari Fitbit Web API lama ke Google Health API, Anda akan berpindah dari library OAuth2 umum ke Google Auth Library. Berikut adalah saran arsitektur dan penerapan pseudo-code yang ditulis dalam Javascript untuk menangani status "Dual-Library" ini.

1. "Middleware Switch"

Karena Anda tidak dapat memigrasikan semua pengguna sekaligus, backend Anda perlu menentukan library mana yang akan digunakan berdasarkan apiVersion pengguna saat ini yang disimpan di database Anda.

Penerapan

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. Memigrasikan alur UX

Untuk memaksimalkan retensi, gunakan pola "Interrupt-and-Upgrade". Hal ini memastikan pengguna tidak dipaksa untuk login ulang hingga mereka sudah berinteraksi dengan aplikasi.

Logika pengalihan

Saat pengguna Fitbit Web API mengakses fitur tertentu, picu migrasi:

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. Transisi Teknis Utama

Saat menulis skrip migrasi JavaScript, perhatikan perbedaan berikut:

Fitur Fitbit Web API (Legacy) Google Health API (Google-Identity)
Endpoint Token https://api.fitbit.com/oauth2/token https://oauth2.googleapis.com/token
Auth Library Open Source Standar Autentikasi Google
Cakupan aktivitas https://www.googleapis.com/auth/googlehealth.activity_and_fitness
ID Pengguna ID yang Dikodekan Fitbit ditampilkan dalam respons /oauth2/token ID pengguna yang ditampilkan dari endpoint users.getIdentity

4. Checklist retensi

  • Persistensi Sesi: Jangan hapus sesi Fitbit Web API lama pengguna hingga access_token Google Health API berhasil diverifikasi dan disimpan ke database Anda.
  • Pencabutan Otomatis: Setelah migrasi Google Health API selesai, gunakan permintaan POST ke endpoint pencabutan Fitbit lama: https://api.fitbit.com/oauth2/revoke. Tindakan ini memastikan pengguna tidak melihat izin aplikasi "duplikat" di setelan Fitbit mereka.
  • Penanganan Error: Jika panggilan Fitbit menampilkan 401 Unauthorized, otomatis dialihkan ke alur OAuth Google, bukan menampilkan pesan error.